https://github.com/op7418/codepilot
A native desktop GUI for Claude Code — chat, code, and manage projects visually. Built with Electron + Next.js.
https://github.com/op7418/codepilot
ai anthropic claude claude-code desktop-app electron gui nextjs
Last synced: 11 days ago
JSON representation
A native desktop GUI for Claude Code — chat, code, and manage projects visually. Built with Electron + Next.js.
- Host: GitHub
- URL: https://github.com/op7418/codepilot
- Owner: op7418
- Created: 2026-02-06T12:38:55.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-02-11T06:45:29.000Z (29 days ago)
- Last Synced: 2026-02-11T14:43:08.912Z (29 days ago)
- Topics: ai, anthropic, claude, claude-code, desktop-app, electron, gui, nextjs
- Language: TypeScript
- Size: 2.86 MB
- Stars: 1,679
- Watchers: 10
- Forks: 174
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
CodePilot
===
**A desktop GUI client for Claude Code** -- chat, code, and manage projects through a polished visual interface instead of the terminal.
[](https://github.com/op7418/CodePilot/releases)
[](https://github.com/op7418/CodePilot/releases)
[](LICENSE)
[中文文档](./README_CN.md) | [日本語](./README_JA.md)
---
## 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
---
## 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**](https://github.com/op7418/CodePilot/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
```bash
# Clone the repository
git clone https://github.com/op7418/CodePilot.git
cd CodePilot
# Install dependencies
npm install
# Start in development mode (browser)
npm run dev
# -- or start the full Electron app in dev mode --
node scripts/build-electron.mjs # compile Electron main process (first time only)
npm run electron:dev
```
Then open [http://localhost:3000](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**
1. Right-click (or Control-click) `CodePilot.app` in Finder.
2. Select **Open** from the context menu.
3. Click **Open** in the confirmation dialog.
**Option 2 -- System Settings**
1. Open **System Settings** > **Privacy & Security**.
2. Scroll down to the **Security** section.
3. You will see a message about CodePilot being blocked. Click **Open Anyway**.
4. Authenticate if prompted, then launch the app.
**Option 3 -- Terminal command**
```bash
xattr -cr /Applications/CodePilot.app
```
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**
1. On the SmartScreen dialog, click **More info**.
2. Click **Run anyway**.
**Option 2 -- Disable App Install Control**
1. Open **Settings** > **Apps** > **Advanced app settings**.
2. Toggle **App Install Control** (or "Choose where to get apps") to allow apps from anywhere.
---
## Tech Stack
| Layer | Technology |
|---|---|
| Framework | [Next.js 16](https://nextjs.org/) (App Router) |
| Desktop shell | [Electron 40](https://www.electronjs.org/) |
| UI components | [Radix UI](https://www.radix-ui.com/) + [shadcn/ui](https://ui.shadcn.com/) |
| Styling | [Tailwind CSS 4](https://tailwindcss.com/) |
| Animation | [Motion](https://motion.dev/) (Framer Motion) |
| AI integration | [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) |
| Database | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) (embedded, per-user) |
| Markdown | react-markdown + remark-gfm + rehype-raw + [Shiki](https://shiki.style/) |
| Streaming | [Vercel AI SDK](https://sdk.vercel.ai/) helpers + Server-Sent Events |
| Icons | [Hugeicons](https://hugeicons.com/) + [Lucide](https://lucide.dev/) |
| Testing | [Playwright](https://playwright.dev/) |
| CI/CD | [GitHub Actions](https://github.com/features/actions) (auto-build + release on tag) |
| Build / Pack | electron-builder + esbuild |
---
## Project Structure
```
codepilot/
├── .github/workflows/ # CI/CD: multi-platform build & auto-release
├── electron/ # Electron main process & preload
│ ├── main.ts # Window creation, embedded server lifecycle
│ └── preload.ts # Context bridge
├── src/
│ ├── app/ # Next.js App Router pages & API routes
│ │ ├── chat/ # New-chat page & [id] session page
│ │ ├── extensions/ # Skills + MCP server management
│ │ ├── settings/ # Settings editor
│ │ └── api/ # REST + SSE endpoints
│ │ ├── chat/ # Sessions, messages, streaming, permissions
│ │ ├── files/ # File tree & preview
│ │ ├── plugins/ # Plugin & MCP CRUD
│ │ ├── settings/ # Settings read/write
│ │ ├── skills/ # Skill CRUD
│ │ └── tasks/ # Task tracking
│ ├── components/
│ │ ├── ai-elements/ # Message bubbles, code blocks, tool calls, etc.
│ │ ├── chat/ # ChatView, MessageList, MessageInput, streaming
│ │ ├── layout/ # AppShell, NavRail, ResizeHandle, RightPanel
│ │ ├── plugins/ # MCP server list & editor
│ │ ├── project/ # FileTree, FilePreview, TaskList
│ │ ├── skills/ # SkillsManager, SkillEditor
│ │ └── ui/ # Radix-based primitives (button, dialog, tabs, ...)
│ ├── hooks/ # Custom React hooks (usePanel, ...)
│ ├── lib/ # Core logic
│ │ ├── claude-client.ts # Agent SDK streaming wrapper
│ │ ├── db.ts # SQLite schema, migrations, CRUD
│ │ ├── files.ts # File system helpers
│ │ ├── permission-registry.ts # Permission request/response bridge
│ │ └── utils.ts # Shared utilities
│ └── types/ # TypeScript interfaces & API contracts
├── electron-builder.yml # Packaging configuration
├── package.json
└── tsconfig.json
```
---
## Development
```bash
# Run Next.js dev server only (opens in browser)
npm run dev
# Compile the Electron main process (required before first run)
node scripts/build-electron.mjs
# Run the full Electron app in dev mode
# (starts Next.js + waits for it, then opens Electron)
npm run electron:dev
# Production build (Next.js static export)
npm run build
# Build Electron distributable + Next.js
npm run electron:build
# Package for specific platforms
npm run electron:pack:mac # macOS DMG (arm64 + x64)
npm run electron:pack:win # Windows NSIS installer
npm run electron:pack:linux # Linux AppImage, deb, rpm
```
### 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:
```bash
git tag v0.8.1
git push origin v0.8.1
# CI builds Windows + macOS + Linux, then publishes the release
```
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:
1. Fork the repository and create a feature branch.
2. Install dependencies with `npm install`.
3. Run `npm run electron:dev` to test your changes locally.
4. Make sure `npm run lint` passes before opening a pull request.
5. Open a PR against `main` with a clear description of what changed and why.
Please keep PRs focused -- one feature or fix per pull request.
---
## License
MIT