CodePilot is an open-source desktop graphical user interface (GUI) client designed to facilitate interaction with Claude Code, offering a visual alternative to command-line interface (CLI) interactions for chat, code generation, and project management.

Core Purpose and Features:
The primary goal of CodePilot is to provide a rich, intuitive, and persistent environment for leveraging Claude's coding capabilities. Key features include:

• Conversational Coding: Real-time streaming of Claude's responses with comprehensive Markdown rendering, syntax-highlighted code blocks, and visual representations of tool calls.
• Session Management: Robust local persistence of chat sessions (create, rename, archive, resume) using SQLite, ensuring data integrity across restarts.
• Project-Aware Context: Ability to define a working directory per session, with a live file tree and file previews displayed in a right panel, providing Claude with explicit contextual awareness.
• User Interface Customization: Resizable chat list and right panels, with user preferences for sizes saved across sessions. Includes a one-click dark/light theme toggle.
• File and Image Attachments: Direct attachment of files and images within the chat input, enabling multimodal vision content analysis by Claude.
• Permission Controls: Granular control over Claude's tool usage with options to approve, deny, or auto-allow actions on a per-action basis.
• Multiple Interaction Modes: Switching between "Code," "Plan," and "Ask" modes to govern Claude's behavior for specific tasks.
• Model Selector: On-the-fly switching between different Claude models (Opus, Sonnet, Haiku) mid-conversation.
• Model Context Protocol (MCP) Server Management: Direct configuration and removal of MCP servers via an Extensions page, supporting stdio, sse, and http transport types.
• Custom Skills: Definition of reusable, prompt-based skills (global or project-specific) invocable as slash commands during chat.
• Settings Editor: Visual and JSON editors for ~/.claude/settings.json, including permissions and environment variables.
• Token Usage Tracking: Displays input/output token counts and estimated costs after each assistant response.
• Auto Update: Periodic checks for new releases with user notifications for available updates.
• Built-in Slash Commands: Includes commands like /help, /clear, /cost, /compact, /doctor, and /review.
• Electron Packaging: Ships as a self-contained desktop application with a hidden title bar, bundled Next.js server, graceful shutdown mechanisms, and automatic port allocation.

Technical Architecture and Core Methodology:
CodePilot is built upon a hybrid desktop application architecture combining Electron for the desktop shell and Next.js (App Router) for the user interface and API backend.

• Technology Stack:
  • 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 SQLite)
  • Markdown Rendering: react-markdown + remark-gfm + rehype-raw + Shiki
  • Streaming: Vercel AI SDK helpers + Server-Sent Events (SSE)
  • Icons: Hugeicons + Lucide
  • Testing: Playwright
  • CI/CD: GitHub Actions
  • Build/Packaging: electron-builder + esbuild

• Project Structure (codepilot/):
  • .github/workflows/: Houses CI/CD configurations for multi-platform builds and auto-releases.
  • electron/: Contains Electron's main process (main.ts) for window creation and embedded server lifecycle management, and a preload script (preload.ts) for context bridging.
  • src/app/: Next.js App Router pages and API routes (chat/, extensions/, settings/, api/ for sessions, files, plugins, settings, skills, tasks).
  • src/components/: Reusable UI components (AI elements, chat UI, layout, plugins, project, skills, Radix-based primitives).
  • src/lib/: Core logic including 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), and utils.ts.
  • types/: TypeScript interfaces and API contracts.

• Inter-process Communication and Data Flow:

The Electron main process (electron/main.ts) is responsible for forking the Next.js standalone server. Communication between the Electron renderer process (which displays the Next.js UI) and the Next.js backend occurs over 127.0.0.1 using a randomly assigned free port, ensuring isolation and preventing port conflicts. All AI interactions occur via calls to the underlying Claude Code Agent SDK, which requires the claude CLI to be available on the system's PATH and authenticated (claude login).

• Data Persistence:

Chat data and other application-specific information are stored locally in an embedded SQLite database using the better-sqlite3 library. The database file is located at ~/.codepilot/codepilot.db (or ./data/codepilot.db in development mode). The application utilizes SQLite's Write-Ahead Logging (WAL) mode to optimize performance for concurrent read operations.

Prerequisites and Installation:
To run CodePilot, the following minimum requirements must be met: Node.js 18+, npm 9+, and the Claude Code CLI installed and authenticated (verified via claude --version). Pre-built releases are available via GitHub Actions for macOS (arm64, x64 .dmg), Windows (x64, arm64 .exe NSIS installer), and Linux (x64, arm64 .AppImage, .deb, .rpm). Manual installation involves cloning the repository, installing dependencies via npm install, and running npm run electron:dev for development or npm run electron:build for a production build. Security warnings on macOS (Gatekeeper) and Windows (SmartScreen) are common for unsigned applications and can be bypassed through specific OS settings or commands.

Development and CI/CD:
The project supports development in a browser-only mode (npm run dev) or full Electron mode (npm run electron:dev). Production builds are generated with npm run build (Next.js static export) and npm run electron:build (Electron distributable). Specific packaging commands exist for macOS, Windows, and Linux. Continuous Integration/Continuous Deployment (CI/CD) is managed via GitHub Actions. Pushing a tag prefixed with v (e.g., v0.8.1) automatically triggers a full multi-platform build and publishes a new GitHub Release with all artifacts.

License:
CodePilot is licensed under the MIT License.