内容摘录
<img src="docs/icon-readme.png" width="32" height="32" alt="CodePilot" style="vertical-align: middle; margin-right: 8px;" /> CodePilot
===
**A desktop GUI client for Claude Code** -- chat, code, and manage projects through a polished visual interface instead of the terminal.
GitHub release
Platform
License
中文文档 | 日本語
---
Features
**Conversational coding** -- Stream responses from Claude in real time with full Markdown rendering, syntax-highlighted code blocks, and tool-call visualization.
**Session management** -- Create, rename, archive, and resume chat sessions. Conversations are persisted locally in SQLite so nothing is lost between restarts.
**Project-aware context** -- Pick a working directory per session. The right panel shows a live file tree and file previews so you always know what Claude is looking at.
**Resizable panels** -- Drag the edges of the chat list and right panel to adjust their width. Your preferred sizes are saved across sessions.
**File & image attachments** -- Attach files and images directly in the chat input. Images are sent as multimodal vision content for Claude to analyze.
**Permission controls** -- Approve, deny, or auto-allow tool use on a per-action basis. Choose between permission modes to match your comfort level.
**Multiple interaction modes** -- Switch between *Code*, *Plan*, and *Ask* modes to control how Claude behaves in each session.
**Model selector** -- Switch between Claude models (Opus, Sonnet, Haiku) mid-conversation.
**MCP server management** -- Add, configure, and remove Model Context Protocol servers directly from the Extensions page. Supports stdio, sse, and http transport types.
**Custom skills** -- Define reusable prompt-based skills (global or per-project) that can be invoked as slash commands during chat.
**Settings editor** -- Visual and JSON editors for your ~/.claude/settings.json, including permissions and environment variables.
**Token usage tracking** -- See input/output token counts and estimated cost after every assistant response.
**Auto update check** -- The app periodically checks for new releases and notifies you when an update is available.
**Dark / Light theme** -- One-click theme toggle in the navigation rail.
**Slash commands** -- Built-in commands like /help, /clear, /cost, /compact, /doctor, /review, and more.
**Electron packaging** -- Ships as a desktop app with a hidden title bar, bundled Next.js server, graceful shutdown, and automatic port allocation.
---
Screenshots
!CodePilot
---
Prerequisites
**Important**: CodePilot calls the Claude Code Agent SDK under the hood. Make sure claude is available on your PATH and that you have authenticated (claude login) before launching the app.
| Requirement | Minimum version |
|---|---|
| **Node.js** | 18+ |
| **Claude Code CLI** | Installed and authenticated (claude --version should work) |
| **npm** | 9+ (ships with Node 18) |
---
Download
Pre-built releases are available on the **Releases** page. Releases are built automatically via GitHub Actions for all platforms.
Supported Platforms
**macOS** -- arm64 (Apple Silicon) and x64 (Intel) distributed as .dmg
**Windows** -- NSIS installer (.exe) bundling x64 + arm64
**Linux** -- x64 and arm64 distributed as .AppImage, .deb, and .rpm
---
Quick Start
Then open http://localhost:3000 (browser mode) or wait for the Electron window to appear.
---
Installation Troubleshooting
CodePilot is not code-signed yet, so your operating system will display a security warning the first time you open it.
macOS
You will see a dialog that says **"Apple cannot check it for malicious software"**.
**Option 1 -- Right-click to open**
Right-click (or Control-click) CodePilot.app in Finder.
Select **Open** from the context menu.
Click **Open** in the confirmation dialog.
**Option 2 -- System Settings**
Open **System Settings** > **Privacy & Security**.
Scroll down to the **Security** section.
You will see a message about CodePilot being blocked. Click **Open Anyway**.
Authenticate if prompted, then launch the app.
**Option 3 -- Terminal command**
This strips the quarantine attribute so macOS will no longer block the app.
Windows
Windows SmartScreen will block the installer or executable.
**Option 1 -- Run anyway**
On the SmartScreen dialog, click **More info**.
Click **Run anyway**.
**Option 2 -- Disable App Install Control**
Open **Settings** > **Apps** > **Advanced app settings**.
Toggle **App Install Control** (or "Choose where to get apps") to allow apps from anywhere.
---
Tech Stack
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| Desktop shell | Electron 40 |
| UI components | Radix UI + shadcn/ui |
| Styling | Tailwind CSS 4 |
| Animation | Motion (Framer Motion) |
| AI integration | Claude Agent SDK |
| Database | better-sqlite3 (embedded, per-user) |
| Markdown | react-markdown + remark-gfm + rehype-raw + Shiki |
| Streaming | Vercel AI SDK helpers + Server-Sent Events |
| Icons | Hugeicons + Lucide |
| Testing | Playwright |
| CI/CD | GitHub Actions (auto-build + release on tag) |
| Build / Pack | electron-builder + esbuild |
---
Project Structure
---
Development
CI/CD
The project uses GitHub Actions for automated builds. Pushing a v* tag triggers a full multi-platform build and automatically creates a GitHub Release with all artifacts:
You can also manually trigger builds for individual platforms from the Actions tab.
Notes
The Electron main process (electron/main.ts) forks the Next.js standalone server and connects to it over 127.0.0.1 with a random free port.
Chat data is stored in ~/.codepilot/codepilot.db (or ./data/codepilot.db in dev mode).
The app uses WAL mode for SQLite, so concurrent reads are fast.
---
Contributing
Contributions are welcome. To get started:
Fork the repository and create a feature branch.
Install dependencies with npm install.
Run npm run electron:dev to test your changes locally.
Make sure npm run lint passes before opening a pull request.
Open a PR against m…