CodeFire

1<p align="center">
2  <img src="assets/codefire-logo.png" alt="CodeFire" width="128">
3</p>
4 
5<h1 align="center">CodeFire</h1>
6 
7<p align="center">
8  <strong>Persistent memory for AI coding agents</strong><br>
9  A cross-platform companion app for Claude Code, Gemini CLI, Codex CLI, and OpenCode
10</p>
11 
12<p align="center">
13  <a href="https://github.com/websitebutlers/codefire-app/releases/latest"><img src="https://img.shields.io/badge/download-macOS-orange?style=flat-square" alt="Download macOS"></a>
14  <a href="https://github.com/websitebutlers/codefire-app/releases/latest"><img src="https://img.shields.io/badge/download-Windows-blue?style=flat-square" alt="Download Windows"></a>
15  <a href="https://github.com/websitebutlers/codefire-app/releases/latest"><img src="https://img.shields.io/badge/download-Linux-green?style=flat-square" alt="Download Linux"></a>
16  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square" alt="MIT License"></a>
17</p>
18 
19<p align="center">
20  <a href="https://codefire.app">Website</a> · <a href="https://codefire.app/getting-started">Getting Started</a> · <a href="https://discord.gg/cMtjR83D">Discord</a> · <a href="https://github.com/websitebutlers/codefire-app/discussions">Community</a> · <a href="https://github.com/websitebutlers/codefire-app/releases/latest">Download</a>
21</p>
22 
23---
24 
25## What is CodeFire?
26 
27Your AI coding agent forgets everything between sessions. CodeFire fixes that.
28 
29It auto-discovers your projects, tracks tasks and sessions, monitors live coding activity, and exposes project data back to your AI via MCP — creating a persistent memory layer where your agent knows what you were working on, what decisions were made, and what's left to do.
30 
31Two platform implementations share the same SQLite database schema and MCP protocol:
32 
33| Platform | Technology | Status |
34|----------|-----------|--------|
35| **macOS (Apple Silicon)** | Swift / SwiftUI | Beta — primary platform |
36| **Windows (x64)** | Electron / React / TypeScript | Early Alpha |
37| **Linux (x64)** | Electron / React / TypeScript | Early Alpha |
38| **macOS (Intel)** | Electron / React / TypeScript | Early Alpha |
39 
40### Features
41 
42- **Persistent memory** — Tasks, notes, and session context that survive across CLI sessions
43- **Task tracking** — Drag-and-drop Kanban board with priorities, labels, and task notes
44- **Live session monitoring** — Real-time token usage, cost tracking, and tool call stats
45- **Semantic code search** — Vector + keyword hybrid search across your indexed codebase
46- **Multi-tab file editor** — Browse and edit project files in tabs, with syntax highlighting, line numbers, Cmd+F find, unsaved-change protection, and a right-click context menu to turn any selection into a task, note, or terminal command
47- **Rendered markdown** — Notes and Claude Code memory files render as styled markdown (tables, headings, code blocks) with a one-click Edit/Preview toggle
48- **Claude Code memory editor** — Edit the memory files Claude Code auto-loads every session, straight from the app
49- **Built-in terminal** — Tabbed terminal sessions alongside your project views, with show/hide toggle
50- **Browser automation** — 40+ MCP tools for navigating, clicking, typing, screenshotting (Electron)
51- **Git integration** — Commits, staged changes, diffs, and branch management
52- **AI chat** — Ask questions about your codebase with RAG-powered context
53- **Image generation** — Text-to-image via OpenRouter (Gemini, DALL-E, etc.)
54- **Notes & briefings** — Pin architecture decisions, capture gotchas, get AI-generated daily briefings
55- **Gmail integration** — Sync emails into tasks with whitelist rules
56- **MCP server** — 63 tools exposing project data to any AI coding CLI
57- **Universal compatibility** — Works with Claude Code, Gemini CLI, Codex CLI, and OpenCode
58 
59<p align="center">
60  <img src="assets/screenshot-01.png" alt="CodeFire — Planner view with Kanban board, task tracking, and project intelligence" width="100%">
61</p>
62 
63## Download
64 
65| Platform | Download | Notes |
66|----------|----------|-------|
67| **macOS (Apple Silicon)** | [CodeFire-macOS.zip](https://github.com/websitebutlers/codefire-app/releases/latest/download/CodeFire-macOS.zip) | Native Swift app. Unzip and drag to Applications. |
68| **macOS (Intel)** | [CodeFire Electron DMG](https://github.com/websitebutlers/codefire-app/releases/latest) | Electron app. Also runs on Apple Silicon via Rosetta 2. |
69| **Windows** | [CodeFire Setup exe](https://github.com/websitebutlers/codefire-app/releases/latest) | NSIS installer. Windows 10+ required. |
70| **Linux** | [Latest Release](https://github.com/websitebutlers/codefire-app/releases/latest) | AppImage + .deb available when built on Linux CI. |
71 
72> For detailed setup instructions including API key configuration, see the **[Getting Started guide](https://codefire.app/getting-started)**.
73 
74## Quick Start
75 
76### 1. Install & Open
77 
78Download for your platform above, install, and launch CodeFire.
79 
80### 2. Add Your OpenRouter API Key
81 
82Open Settings and go to the **Engine** tab (Electron) or **CodeFire Engine** tab (Swift). Paste your [OpenRouter API key](https://openrouter.ai/keys). This powers AI chat, semantic code search, and image generation.
83 
84### 3. Connect Your CLI
85 
86The fastest way is the one-click install — visit [codefire.app/getting-started](https://codefire.app/getting-started) and click the button for your CLI.
87 
88Or configure manually:
89 
90```bash
91# Claude Code — macOS (Swift)
92claude mcp add codefire ~/Library/Application\ Support/CodeFire/bin/CodeFireMCP
93 
94# Claude Code — Linux (AppImage, auto-synced on first launch)
95claude mcp add codefire node ~/.local/share/CodeFire/mcp-server/server.js
96 
97# Claude Code — Windows
98claude mcp add codefire node "%APPDATA%\CodeFire\resources\mcp-server\server.js"
99```
100 
101<details>
102<summary>Other CLI tools</summary>
103 
104**Gemini CLI** — `~/.gemini/settings.json`:
105```json
106{
107  "mcpServers": {
108    "codefire": {
109      "command": "~/Library/Application Support/CodeFire/bin/CodeFireMCP",
110      "args": []
111    }
112  }
113}
114```
115 
116**Codex CLI** — `~/.codex/config.toml`:
117```toml
118[mcp_servers.codefire]
119command = "~/Library/Application Support/CodeFire/bin/CodeFireMCP"
120args = []
121```
122 
123**OpenCode** — `opencode.json` (project root):
124```json
125{
126  "mcpServers": {
127    "codefire": {
128      "type": "local",
129      "command": ["~/Library/Application Support/CodeFire/bin/CodeFireMCP"]
130    }
131  }
132}
133```
134 
135> Electron users: the MCP server path differs by platform. See the [setup guides](#4-add-system-instructions) for exact paths. Linux AppImage users: the MCP server is automatically synced to `~/.local/share/CodeFire/mcp-server/` on first launch.
136 
137</details>
138 
139### 4. Add System Instructions
140 
141For the best experience, add CodeFire instructions to your CLI's system prompt file. This teaches your AI agent how to use CodeFire's tools effectively — session workflows, task tracking, notes, and more.
142 
143| CLI | Setup Guide |
144|-----|-------------|
145| Claude Code | [codefire-claude-md-setup.md](docs/codefire-claude-md-setup.md) |
146| Gemini CLI | [codefire-gemini-setup.md](docs/codefire-gemini-setup.md) |
147| Codex CLI | [codefire-codex-setup.md](docs/codefire-codex-setup.md) |
148| OpenCode | [codefire-opencode-setup.md](docs/codefire-opencode-setup.md) |
149 
150Each guide includes platform-specific MCP connection instructions (macOS, Windows, Linux) and copy-pasteable system instructions.
151 
152### 5. Start Coding
153 
154Open a project folder in CodeFire, then start a CLI session. Your agent now has access to persistent memory, task tracking, browser automation, and code search — all through MCP.
155 
156## MCP Server
157 
158CodeFire's MCP server exposes **63 tools** to your AI coding agent:
159 
160| Category | Tools | Examples |
161|----------|-------|---------|
162| **Tasks** | 6 | Create, update, list, and annotate tasks with notes |
163| **Notes** | 5 | Create, search, pin, and manage project notes |
164| **Projects** | 2 | List projects, get current project context |
165| **Sessions** | 2 | List and search session history |
166| **Code Search** | 1 | Full-text search across indexed codebase |
167| **Browser** | 40+ | Navigate, click, type, screenshot, eval JS, manage cookies |
168| **Images** | 1 | List generated images |
169| **Clients** | 2 | List and create client groups |
170 
171## Build from Source
172 
173### macOS (Swift)
174 
175```bash
176cd swift
177swift build -c release
178```
179 
180See [`swift/README.md`](swift/) for full build and signing instructions.
181 
182### Windows / Linux / macOS Intel (Electron)
183 
184```bash
185cd electron
186npm install          # Install deps + rebuild native modules
187npm run dev          # Start dev server + Electron
188npm run build        # TypeScript compile + Vite build
189npm test             # Run tests (Vitest)
190npm run dist         # Package for current platform
191npm run dist:win     # Windows installer (NSIS)
192npm run dist:linux   # Linux packages (AppImage + deb)
193npm run dist:mac     # macOS DMG + zip
194```
195 
196See [`electron/README.md`](electron/) for detailed architecture and development docs.
197 
198## Repository Structure
199 
200```
201swift/          macOS app (Swift/SwiftUI) — Beta
202electron/       Windows/Linux/macOS Intel app (Electron/React/TypeScript) — Alpha
203landing/        Marketing website (codefire.app)
204assets/         Shared screenshots and branding
205scripts/        Build and packaging scripts
206CLAUDE.md       Architecture docs for AI coding agents
207SECURITY.md     Security policy and vulnerability reporting
208```
209 
210## Architecture
211 
212Both apps follow the same data model:
213 
214- **SQLite database** at `~/Library/Application Support/CodeFire/codefire.db` (macOS), `~/.config/CodeFire/codefire.db` (Linux), or `%APPDATA%\CodeFire\codefire.db` (Windows)
215- **MCP server** communicates via stdio — no network listeners, fully local
216- **Project discovery** scans `~/.claude/projects/` for Claude Code session data
217- **Shared schema** — both Swift and Electron apps read/write the same database
218 
219### Electron Architecture
220 
221The Electron app follows strict **main/preload/renderer** process separation:
222 
223- **Main process** (`src/main/`) — Database, IPC handlers, services (Git, Terminal, Search, MCP)
224- **Preload** (`src/preload/`) — Typed bridge exposing `window.api` via contextBridge
225- **Renderer** (`src/renderer/`) — React 19 + Tailwind CSS 4 + Vite
226- **MCP server** (`src/mcp/`) — Standalone Node.js process spawned by CLI tools
227 
228Path aliases: `@shared`, `@renderer`, `@main`
229 
230## Contributing
231 
232We're actively looking for contributors, especially for the Electron app on Windows and Linux.
233 
234- **[Getting Started guide](https://codefire.app/getting-started)** — Set up the app
235- **[Testers Wanted](https://github.com/websitebutlers/codefire-app/discussions/48)** — Testing guide with platform-specific instructions
236- **[Developer Wishlist](https://github.com/websitebutlers/codefire-app/discussions/49)** — Areas where we need help (search engine, browser automation, testing, MCP)
237- **[Community Guidelines](https://github.com/websitebutlers/codefire-app/discussions/47)** — How to get involved
238- **[CONTRIBUTING.md](CONTRIBUTING.md)** — Code style, branch naming, and PR guidelines
239- **[SECURITY.md](SECURITY.md)** — Vulnerability reporting
240 
241### Priority Contribution Areas
242 
2431. **Semantic search improvements** — Local embedding fallback, reranking, better chunking
2442. **Browser automation** — Network capture, session persistence, Web Vitals
2453. **Testing** — Swift unit tests, MCP protocol tests, E2E browser tests, CI matrix builds
2464. **Cross-platform parity** — Port features between Swift and Electron
2475. **MCP server extensions** — Git operations, custom tool plugins, metrics
248 
249## Requirements
250 
251- **macOS (Swift):** macOS 14.0 (Sonoma) or later, Apple Silicon
252- **Electron:** Windows 10+, Ubuntu 20.04+, or macOS 10.15+ (Intel or Apple Silicon via Rosetta)
253- **OpenRouter API key** for AI-powered features ([get one here](https://openrouter.ai/keys))
254- An AI coding CLI: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex CLI](https://github.com/openai/codex), or [OpenCode](https://github.com/sst/opencode)
255 
256## License
257 
258MIT
259