okooooooo/CodePilot
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite READMEs from dev memo to user-facing landing page

Browse Source 
- Replace 17-item flat feature list with "Why CodePilot" benefit paragraphs
- Add Quick Links nav bar, First Launch guide, and 3 grouped capability tables
- Collapse ~120-line installation troubleshooting into <details> blocks
- Remove Tech Stack and Project Structure (already in ARCHITECTURE.md)
- Move WeChat QR from hero to Community section
- Add Documentation section linking to ARCHITECTURE.md and docs/
- README_CN.md: full Chinese translation, identical structure
- README_JA.md: Japanese headings/tables, English kept for narrative sections

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
7418andClaude Opus 4.6 committed 2026-03-08 15:32:42 +08:00
1 parent 1e0958f598
commit a249fb9c4f
3 files changed
+382 -550
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+128 -191
View File
@@ -1,7 +1,7 @@
<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.
**A unified desktop client for Claude Code** -- multi-provider support, MCP extensions, custom skills, cross-platform bridge, and an assistant workspace that understands your projects.
[![GitHub release](https://img.shields.io/github/v/release/op7418/CodePilot)](https://github.com/op7418/CodePilot/releases)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)](https://github.com/op7418/CodePilot/releases)
@@ -9,251 +9,188 @@
[中文文档](./README_CN.md) | [日本語](./README_JA.md)
### Join the Community / 加入用户群
<img src="docs/wechat-group-qr.png" width="240" alt="WeChat Group QR Code" />
Scan the QR code to join the WeChat user group for discussions, feedback, and updates.
---
## 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](docs/screenshot.png)
---
## 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](#platform--installation) | [Quick Start](#quick-start) | [Documentation](#documentation) | [Contributing](#contributing) | [Community](#community)
---
## Download
## Why CodePilot
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.
**Multi-provider, one interface.** Connect to Anthropic, OpenRouter, Bedrock, Vertex, or any custom endpoint. Switch providers and models mid-conversation without losing context.
### Supported Platforms
**MCP + Skills extensibility.** Add MCP servers (stdio / sse / http) with runtime status monitoring. Define reusable prompt-based skills -- global or per-project -- and invoke them as slash commands. Browse and install community skills from skills.sh.
- **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`
**Control from anywhere.** Bridge connects CodePilot to Telegram, Feishu, Discord, and QQ. Send a message from your phone, get the response on your desktop.
**An assistant that knows your project.** The .assistant workspace stores persona files, onboarding flows, daily check-ins, and persistent memory. Claude adapts to your project's conventions over time.
**Built for daily use.** Pause, resume, and rewind sessions to any checkpoint. Work in split-screen with two conversations side by side. Track token usage and costs. Import CLI session history. Switch between dark and light themes.
---
## Quick Start
### Path A: Download a release (most users)
1. Install the Claude Code CLI: `npm install -g @anthropic-ai/claude-code`
2. Authenticate: `claude login`
3. Download the installer for your platform from the [Releases](https://github.com/op7418/CodePilot/releases) page
4. Launch CodePilot
### Path B: Build from source (developers)
| Prerequisite | Minimum version |
|---|---|
| Node.js | 18+ |
| Claude Code CLI | Installed and authenticated |
| npm | 9+ (ships with Node 18) |
```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
npm run dev # browser mode at http://localhost:3000
# -- or --
npm run electron:dev # full desktop app
```
Then open [http://localhost:3000](http://localhost:3000) (browser mode) or wait for the Electron window to appear.
---
## Installation Troubleshooting
## First Launch
CodePilot is not code-signed yet, so your operating system will display a security warning the first time you open it.
1. **Authenticate Claude** -- Run `claude login` in your terminal if you haven't already.
2. **Configure a Provider** -- Open Settings > Providers. Add an API key or use the CLI's default authentication.
3. **Create a conversation** -- Pick a working directory, select a mode (Code / Plan / Ask), and choose a model.
4. **Set up Assistant Workspace** (optional) -- Enable Onboarding, daily check-ins, and persona files under the .assistant directory.
5. **Add MCP servers** (optional) -- Go to the Extensions page to connect external tools and services.
### macOS
---
You will see a dialog that says **"Apple cannot check it for malicious software"**.
## Core Capabilities
**Option 1 -- Right-click to open**
### Conversation & Coding
1. Right-click (or Control-click) `CodePilot.app` in Finder.
2. Select **Open** from the context menu.
3. Click **Open** in the confirmation dialog.
| Capability | Details |
|---|---|
| Interaction modes | Code / Plan / Ask |
| Reasoning effort | Low / Medium / High / Max + Thinking mode |
| Permission control | Default / Full Access, per-action approval |
| Session control | Pause, resume, rewind to checkpoint, archive |
| Model switching | Change model mid-conversation |
| Split screen | Side-by-side dual sessions |
| Attachments | Files and images with multimodal vision support |
| Slash commands | /help /clear /cost /compact /doctor /review and more |
**Option 2 -- System Settings**
### Extensions & Integrations
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.
| Capability | Details |
|---|---|
| Providers | Anthropic / OpenRouter / Bedrock / Vertex / custom endpoints |
| MCP servers | stdio / sse / http, runtime status monitoring |
| Skills | Custom / project / global skills, skills.sh marketplace |
| Bridge | Telegram / Feishu / Discord / QQ remote control |
| CLI import | Import Claude Code CLI .jsonl session history |
| Image generation | Gemini / Anthropic image gen, batch tasks, gallery |
**Option 3 -- Terminal command**
### Data & Workspace
| Capability | Details |
|---|---|
| Assistant Workspace | .assistant directory, persona, onboarding, check-in, memory |
| File browser | Project file tree with syntax-highlighted preview |
| Usage analytics | Token counts, cost estimates, daily usage charts |
| Local storage | SQLite (WAL mode), all data stays on your machine |
| i18n | English + Chinese |
| Themes | Dark / Light, one-click toggle |
---
## Platform & Installation
| Platform | Format | Architecture |
|---|---|---|
| macOS | .dmg | arm64 (Apple Silicon) + x64 (Intel) |
| Windows | .exe (NSIS) | x64 + arm64 |
| Linux | .AppImage / .deb / .rpm | x64 + arm64 |
Download from the [Releases](https://github.com/op7418/CodePilot/releases) page.
CodePilot is not code-signed yet, so your OS will show a security warning on first launch.
<details>
<summary>macOS: "Apple cannot check it for malicious software"</summary>
**Option 1** -- Right-click `CodePilot.app` in Finder > Open > confirm.
**Option 2** -- System Settings > Privacy & Security > scroll to Security > click Open Anyway.
**Option 3** -- Run in Terminal:
```bash
xattr -cr /Applications/CodePilot.app
```
</details>
This strips the quarantine attribute so macOS will no longer block the app.
<details>
<summary>Windows: SmartScreen blocks the installer</summary>
### Windows
**Option 1** -- Click "More info" on the SmartScreen dialog, then "Run anyway".
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.
**Option 2** -- Settings > Apps > Advanced app settings > set App Install Control to allow apps from anywhere.
</details>
---
## Tech Stack
## Documentation
| 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 |
- [ARCHITECTURE.md](./ARCHITECTURE.md) -- Architecture, tech stack, directory structure, data flow
- [docs/handover/](./docs/handover/) -- Design decisions and handover documents
- [docs/exec-plans/](./docs/exec-plans/) -- Execution plans and tech debt tracker
---
## Project Structure
## Community
```
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
```
<img src="docs/wechat-group-qr.png" width="240" alt="WeChat Group QR Code" />
---
Scan the QR code to join the WeChat user group for discussions, feedback, and updates.
## 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.
- [GitHub Issues](https://github.com/op7418/CodePilot/issues) -- Bug reports and feature requests
- [GitHub Discussions](https://github.com/op7418/CodePilot/discussions) -- Questions and general discussion
---
## Contributing
Contributions are welcome. To get started:
1. Fork the repository and create a feature branch
2. `npm install` and `npm run electron:dev` to develop locally
3. Run `npm run test` before opening a PR
4. Submit a PR against `main` with a clear description
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.
Keep PRs focused -- one feature or fix per pull request.
Please keep PRs focused -- one feature or fix per pull request.
<details>
<summary>Development commands</summary>
```bash
npm run dev # Next.js dev server (browser)
npm run electron:dev # Full Electron app (dev mode)
npm run build # Production build
npm run electron:build # Build Electron distributable
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:** Pushing a `v*` tag triggers a full multi-platform build and creates a GitHub Release automatically.
**Notes:**
- Electron forks a Next.js standalone server on `127.0.0.1` with a random free port
- Chat data is stored in `~/.codepilot/codepilot.db` (dev mode: `./data/`)
- SQLite uses WAL mode for fast concurrent reads
</details>
---
README_CN.md
+127 -190
View File
@@ -1,260 +1,197 @@
<img src="docs/icon-readme.png" width="32" height="32" alt="CodePilot" style="vertical-align: middle; margin-right: 8px;" /> CodePilot
===
**Claude Code 的桌面 GUI 客户端** -- 通过可视化界面进行对话、编码和项目管理，无需在终端中操作。
[English](./README.md) | [日本語](./README_JA.md)
**Claude Code 的统一桌面客户端** -- 多 Provider 支持、MCP 扩展、自定义技能、跨平台 Bridge，以及理解你项目的助手工作区。
[![GitHub release](https://img.shields.io/github/v/release/op7418/CodePilot)](https://github.com/op7418/CodePilot/releases)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)](https://github.com/op7418/CodePilot/releases)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
### 加入用户群
<img src="docs/wechat-group-qr.png" width="240" alt="微信用户群二维码" />
扫描二维码加入微信用户群，交流使用心得、反馈问题和获取最新动态。
---
## 功能特性
- **实时对话编码** -- 流式接收 Claude 的响应，支持完整的 Markdown 渲染、语法高亮代码块和工具调用可视化
- **会话管理** -- 创建、重命名、归档和恢复聊天会话。所有对话本地持久化存储在 SQLite 中，重启不丢失
- **项目感知上下文** -- 为每个会话选择工作目录。右侧面板实时展示文件树和文件预览，随时了解 Claude 正在查看的内容
- **可调节面板宽度** -- 拖拽聊天列表和右侧面板的边缘调整宽度，偏好设置跨会话保存
- **文件和图片附件** -- 在聊天输入框直接附加文件和图片。图片以多模态视觉内容发送给 Claude 进行分析
- **权限控制** -- 逐项审批、拒绝或自动允许工具使用，可选择不同的权限模式
- **多种交互模式** -- 在 *Code*、*Plan* 和 *Ask* 模式之间切换，控制 Claude 在每个会话中的行为方式
- **模型切换** -- 在对话中随时切换 Claude 模型（Opus、Sonnet、Haiku）
- **MCP 服务器管理** -- 直接在扩展页面添加、配置和移除 Model Context Protocol 服务器。支持 `stdio`、`sse` 和 `http` 传输类型
- **自定义技能** -- 定义可复用的提示词技能（全局或项目级别），在聊天中作为斜杠命令调用
- **设置编辑器** -- 可视化和 JSON 编辑器管理 `~/.claude/settings.json`，包括权限和环境变量配置
- **Token 用量追踪** -- 每次助手回复后查看输入/输出 Token 数量和预估费用
- **自动更新** -- 已签名版本支持应用内自动下载和安装更新；未签名本地构建仅支持手动下载
- **深色/浅色主题** -- 导航栏一键切换主题
- **斜杠命令** -- 内置 `/help`、`/clear`、`/cost`、`/compact`、`/doctor`、`/review` 等命令
- **Electron 打包** -- 桌面应用，隐藏标题栏，内置 Next.js 服务器，优雅关闭进程，自动端口分配
---
## 截图
[English](./README.md) | [日本語](./README_JA.md)
![CodePilot](docs/screenshot.png)
---
## 环境要求
[下载](#平台与安装) | [快速开始](#快速开始) | [文档](#文档) | [贡献](#贡献) | [社区](#社区)
| 要求 | 最低版本 |
|------|---------|
| **Node.js** | 18+ |
| **Claude Code CLI** | 已安装并完成认证（`claude --version` 可正常运行） |
| **npm** | 9+（Node 18 自带） |
---
> **注意**：CodePilot 底层调用 Claude Code Agent SDK。请确保 `claude` 命令在 `PATH` 中可用，并且已完成认证（`claude login`）。
## 为什么选择 CodePilot
**多 Provider，统一界面。** 连接 Anthropic、OpenRouter、Bedrock、Vertex 或任何自定义端点。对话中随时切换 Provider 和模型，不丢失上下文。
**MCP + Skills 扩展体系。** 添加 MCP 服务器（stdio / sse / http），支持运行时状态监控。定义可复用的提示词技能 -- 全局或项目级 -- 作为斜杠命令调用。从 skills.sh 浏览和安装社区技能。
**随时随地控制。** Bridge 连接 CodePilot 到 Telegram、飞书、Discord 和 QQ。在手机上发消息，在桌面上收回复。
**了解你项目的助手。** .assistant 工作区存储人设文件、Onboarding 流程、每日签到和持久记忆。Claude 会随时间适应你的项目惯例。
**为日常使用而建。** 暂停、恢复和回退会话到任意检查点。分屏并排运行两个对话。追踪 Token 用量和费用。导入 CLI 会话历史。深浅主题一键切换。
---
## 快速开始
### 路径 A：下载发布版（大多数用户）
1. 安装 Claude Code CLI：`npm install -g @anthropic-ai/claude-code`
2. 认证：`claude login`
3. 从 [Releases](https://github.com/op7418/CodePilot/releases) 页面下载对应平台的安装包
4. 启动 CodePilot
### 路径 B：源码构建（开发者）
| 前置条件 | 最低版本 |
|---|---|
| Node.js | 18+ |
| Claude Code CLI | 已安装并完成认证 |
| npm | 9+（Node 18 自带） |
```bash
# 克隆仓库
git clone https://github.com/op7418/CodePilot.git
cd CodePilot
# 安装依赖
npm install
# 以开发模式启动（浏览器）
npm run dev
# -- 或者启动完整的 Electron 桌面应用 --
node scripts/build-electron.mjs # 编译 Electron 主进程（首次运行前需要）
npm run electron:dev
npm run dev # 浏览器模式，访问 http://localhost:3000
# -- 或者 --
npm run electron:dev # 完整桌面应用
```
然后打开 [http://localhost:3000](http://localhost:3000)（浏览器模式）或等待 Electron 窗口弹出。
---
## 首次使用
1. **认证 Claude** -- 如果还没有，先在终端运行 `claude login`。
2. **配置 Provider** -- 打开 设置 > Providers，添加 API Key 或使用 CLI 默认认证。
3. **创建对话** -- 选择工作目录、交互模式（Code / Plan / Ask）和模型。
4. **设置 Assistant Workspace**（可选）-- 在 .assistant 目录下开启 Onboarding、每日签到和人设文件。
5. **添加 MCP 服务器**（可选）-- 前往扩展页面连接外部工具和服务。
---
## 下载
## 核心能力
预编译版本可在 [Releases](https://github.com/op7418/CodePilot/releases) 页面下载。所有平台的安装包均由 GitHub Actions 自动构建发布。
### 对话与编码
### 支持平台
| 能力 | 说明 |
|---|---|
| 交互模式 | Code / Plan / Ask |
| 推理力度 | Low / Medium / High / Max + Thinking 模式 |
| 权限控制 | Default / Full Access，逐项审批 |
| 会话控制 | 暂停、恢复、回退到检查点、归档 |
| 模型切换 | 对话中随时切换模型 |
| 分屏 | 并排双会话 |
| 附件 | 文件和图片，支持多模态视觉 |
| 斜杠命令 | /help /clear /cost /compact /doctor /review 等 |
- **macOS** -- 支持 arm64（Apple Silicon）和 x64（Intel）架构的 `.dmg` 安装包
- **Windows** -- NSIS 安装程序（`.exe`），包含 x64 + arm64
- **Linux** -- 支持 x64 和 arm64 架构，提供 `.AppImage`、`.deb` 和 `.rpm` 格式
### 扩展与集成
| 能力 | 说明 |
|---|---|
| Provider | Anthropic / OpenRouter / Bedrock / Vertex / 自定义端点 |
| MCP 服务器 | stdio / sse / http，运行时状态监控 |
| Skills | 自定义 / 项目 / 全局技能，skills.sh 市场 |
| Bridge | Telegram / 飞书 / Discord / QQ 远程控制 |
| CLI 导入 | 导入 Claude Code CLI .jsonl 会话历史 |
| 图片生成 | Gemini / Anthropic 生图、批量任务、画廊 |
### 数据与工作区
| 能力 | 说明 |
|---|---|
| Assistant Workspace | .assistant 目录、人设、Onboarding、签到、记忆 |
| 文件浏览 | 项目文件树、语法高亮预览 |
| 用量分析 | Token 计数、费用估算、日用量图表 |
| 本地存储 | SQLite（WAL 模式），数据全部在本地 |
| 国际化 | 英文 + 中文 |
| 主题 | 深色 / 浅色，一键切换 |
---
## 安装问题排查
## 平台与安装
CodePilot 尚未进行代码签名，因此操作系统在首次打开时会显示安全警告。
| 平台 | 格式 | 架构 |
|---|---|---|
| macOS | .dmg | arm64 (Apple Silicon) + x64 (Intel) |
| Windows | .exe (NSIS) | x64 + arm64 |
| Linux | .AppImage / .deb / .rpm | x64 + arm64 |
### macOS
从 [Releases](https://github.com/op7418/CodePilot/releases) 页面下载。
你会看到一个对话框提示 **"无法验证开发者"** 或 **"Apple 无法检查其是否包含恶意软件"**。
CodePilot 尚未进行代码签名，首次启动时操作系统会显示安全警告。
**方案一 -- 右键打开**
<details>
<summary>macOS："无法验证开发者" / "Apple 无法检查其是否包含恶意软件"</summary>
1. 在访达中右键（或 Control-点击）`CodePilot.app`
2. 从右键菜单中选择 **打开**
3. 在确认对话框中点击 **打开**
**方案一** -- 在访达中右键 `CodePilot.app` > 打开 > 确认。
**方案二 -- 系统设置**
1. 打开 **系统设置** > **隐私与安全性**
2. 向下滚动到 **安全性** 部分
3. 你会看到关于 CodePilot 被阻止的提示，点击 **仍要打开**
4. 如有提示则输入密码验证，然后启动应用
**方案三 -- 终端命令**
**方案二** -- 系统设置 > 隐私与安全性 > 滚动到安全性 > 点击「仍要打开」。
**方案三** -- 在终端运行：
```bash
xattr -cr /Applications/CodePilot.app
```
</details>
此命令会移除隔离属性，macOS 将不再阻止该应用。
<details>
<summary>Windows：SmartScreen 阻止安装</summary>
### Windows
**方案一** -- 在 SmartScreen 对话框中点击「更多信息」，然后点击「仍要运行」。
Windows SmartScreen 会阻止安装程序或可执行文件。
**方案一 -- 仍要运行**
1. 在 SmartScreen 对话框中，点击 **更多信息**
2. 点击 **仍要运行**
**方案二 -- 关闭应用安装控制**
1. 打开 **设置** > **应用** > **高级应用设置**
2. 将 **应用安装控制**（或"选择获取应用的位置"）切换为允许任何来源
**方案二** -- 设置 > 应用 > 高级应用设置 > 将应用安装控制设为允许任何来源。
</details>
---
## 技术栈
## 文档
| 层级 | 技术 |
|------|------|
| 框架 | [Next.js 16](https://nextjs.org/)（App Router） |
| 桌面壳 | [Electron 40](https://www.electronjs.org/) |
| UI 组件 | [Radix UI](https://www.radix-ui.com/) + [shadcn/ui](https://ui.shadcn.com/) |
| 样式 | [Tailwind CSS 4](https://tailwindcss.com/) |
| 动画 | [Motion](https://motion.dev/)（Framer Motion） |
| AI 集成 | [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) |
| 数据库 | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)（嵌入式，用户独立） |
| Markdown | react-markdown + remark-gfm + rehype-raw + [Shiki](https://shiki.style/) |
| 流式传输 | [Vercel AI SDK](https://sdk.vercel.ai/) + Server-Sent Events |
| 图标 | [Hugeicons](https://hugeicons.com/) + [Lucide](https://lucide.dev/) |
| 测试 | [Playwright](https://playwright.dev/) |
| CI/CD | [GitHub Actions](https://github.com/features/actions)（自动构建 + tag 发版） |
| 构建打包 | electron-builder + esbuild |
- [ARCHITECTURE.md](./ARCHITECTURE.md) -- 架构、技术栈、目录结构、数据流
- [docs/handover/](./docs/handover/) -- 设计决策、交接文档
- [docs/exec-plans/](./docs/exec-plans/) -- 执行计划、技术债务
---
## 项目结构
## 社区
```
codepilot/
├── .github/workflows/ # CI/CD：多平台构建和自动发版
├── electron/ # Electron 主进程和预加载脚本
│ ├── main.ts # 窗口创建、内嵌服务器生命周期管理
│ └── preload.ts # Context bridge
├── src/
│ ├── app/ # Next.js App Router 页面和 API 路由
│ │ ├── chat/ # 新建对话页面和 [id] 会话页面
│ │ ├── extensions/ # 技能 + MCP 服务器管理
│ │ ├── settings/ # 设置编辑器
│ │ └── api/ # REST + SSE 接口
│ │ ├── chat/ # 会话、消息、流式传输、权限
│ │ ├── files/ # 文件树和预览
│ │ ├── plugins/ # 插件和 MCP 增删改查
│ │ ├── settings/ # 设置读写
│ │ ├── skills/ # 技能增删改查
│ │ └── tasks/ # 任务追踪
│ ├── components/
│ │ ├── ai-elements/ # 消息气泡、代码块、工具调用等
│ │ ├── chat/ # ChatView、MessageList、MessageInput、流式消息
│ │ ├── layout/ # AppShell、NavRail、ResizeHandle、RightPanel
│ │ ├── plugins/ # MCP 服务器列表和编辑器
│ │ ├── project/ # FileTree、FilePreview、TaskList
│ │ ├── skills/ # SkillsManager、SkillEditor
│ │ └── ui/ # 基于 Radix 的基础组件（button、dialog、tabs...）
│ ├── hooks/ # 自定义 React Hooks（usePanel 等）
│ ├── lib/ # 核心逻辑
│ │ ├── claude-client.ts # Agent SDK 流式封装
│ │ ├── db.ts # SQLite 数据库、迁移、CRUD
│ │ ├── files.ts # 文件系统工具函数
│ │ ├── permission-registry.ts # 权限请求/响应桥接
│ │ └── utils.ts # 通用工具函数
│ └── types/ # TypeScript 接口和 API 类型定义
├── electron-builder.yml # 打包配置
├── package.json
└── tsconfig.json
```
<img src="docs/wechat-group-qr.png" width="240" alt="微信用户群二维码" />
---
扫描二维码加入微信用户群，交流使用心得、反馈问题和获取最新动态。
## 开发
```bash
# 仅运行 Next.js 开发服务器（在浏览器中打开）
npm run dev
# 编译 Electron 主进程（首次运行前需要执行）
node scripts/build-electron.mjs
# 运行完整的 Electron 桌面应用（开发模式）
# （先启动 Next.js，等待就绪后打开 Electron）
npm run electron:dev
# 生产构建（Next.js standalone）
npm run build
# 构建 Electron 可分发包 + Next.js
npm run electron:build
# 打包特定平台
npm run electron:pack:mac # macOS DMG（arm64 + x64）
npm run electron:pack:win # Windows NSIS 安装包
npm run electron:pack:linux # Linux AppImage、deb、rpm
```
### CI/CD
项目使用 GitHub Actions 自动构建。推送 `v*` tag 会自动触发全平台构建并创建 GitHub Release：
```bash
git tag v0.8.1
git push origin v0.8.1
# CI 自动构建 Windows + macOS + Linux，然后发布 Release
```
也可以在 Actions 页面手动触发单个平台的构建。
### 说明
- Electron 主进程（`electron/main.ts`）会 fork Next.js standalone 服务器，通过 `127.0.0.1` 上的随机可用端口进行连接
- 聊天数据存储在 `~/.codepilot/codepilot.db`（开发模式下为 `./data/`）
- 应用使用 SQLite WAL 模式，并发读取性能优秀
- [GitHub Issues](https://github.com/op7418/CodePilot/issues) -- Bug 反馈和功能建议
- [GitHub Discussions](https://github.com/op7418/CodePilot/discussions) -- 提问和讨论
---
## 贡献
欢迎贡献代码。开始之前：
1. Fork 本仓库并创建功能分支
2. 使用 `npm install` 安装依赖
3. 运行 `npm run electron:dev` 在本地测试你的更改
4. 确保 `npm run lint` 通过后再提交 Pull Request
5. 向 `main` 分支提交 PR，并附上清晰的变更说明
2. `npm install` 然后 `npm run electron:dev` 本地开发
3. 提交 PR 前运行 `npm run test`
4. 向 `main` 提交 PR，附上清晰的变更说明
请保持 PR 聚焦 -- 每个 PR 只包含一个功能或修复。
<details>
<summary>开发命令</summary>
```bash
npm run dev # Next.js 开发服务器（浏览器）
npm run electron:dev # 完整 Electron 应用（开发模式）
npm run build # 生产构建
npm run electron:build # 构建 Electron 可分发包
npm run electron:pack:mac # macOS DMG（arm64 + x64）
npm run electron:pack:win # Windows NSIS 安装包
npm run electron:pack:linux # Linux AppImage、deb、rpm
```
**CI/CD：** 推送 `v*` tag 会自动触发全平台构建并创建 GitHub Release。
**说明：**
- Electron 在 `127.0.0.1` 上 fork Next.js standalone 服务器，使用随机可用端口
- 聊天数据存储在 `~/.codepilot/codepilot.db`（开发模式：`./data/`）
- SQLite 使用 WAL 模式，并发读取性能优秀
</details>
---
## 许可证
README_JA.md
+127 -169
View File
@@ -1,234 +1,192 @@
<img src="docs/icon-readme.png" width="32" height="32" alt="CodePilot" style="vertical-align: middle; margin-right: 8px;" /> CodePilot
===
**Claude Code のデスクトップ GUI クライアント** -- ターミナルではなく、洗練されたビジュアルインターフェースを通じてチャット、コーディング、プロジェクト管理を行えます。
**Claude Code の統合デスクトップクライアント** -- マルチプロバイダー対応、MCP 拡張、カスタムスキル、クロスプラットフォーム Bridge、プロジェクトを理解するアシスタントワークスペース。
[![GitHub release](https://img.shields.io/github/v/release/op7418/CodePilot)](https://github.com/op7418/CodePilot/releases)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows-lightgrey)](https://github.com/op7418/CodePilot/releases)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)](https://github.com/op7418/CodePilot/releases)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[English](./README.md) | [中文文档](./README_CN.md)
---
## 機能
- **💬 会話型コーディング** -- Claude からのレスポンスをリアルタイムでストリーミング受信します。完全な Markdown レンダリング、シンタックスハイライトされたコードブロック、ツール呼び出しの可視化に対応しています。
- **📂 セッション管理** -- チャットセッションの作成、名前変更、アーカイブ、再開ができます。会話は SQLite にローカル保存されるため、再起動後もデータが失われません。
- **🎯 プロジェクト対応コンテキスト** -- セッションごとに作業ディレクトリを指定できます。右パネルにはライブファイルツリーとファイルプレビューが表示されるため、Claude が何を見ているかが常にわかります。
- **🔒 権限制御** -- ツール使用をアクション単位で承認、拒否、または自動許可できます。お好みに応じて権限モードを選択できます。
- **🎭 複数の相互作用モード** -- *Code*、*Plan*、*Ask* モード間で切り替えて、各セッションで Claude の動作を制御できます。
- **🤖 モデルセレクター** -- 会話中に Claude モデル（Opus、Sonnet、Haiku）を切り替えられます。
- **🔌 MCP サーバー管理** -- Model Context Protocol サーバーをエクステンション ページから直接追加、設定、削除できます。`stdio`、`sse`、`http` トランスポート型に対応しています。
- **⚡ カスタムスキル** -- スラッシュコマンドとして呼び出し可能な、再利用可能なプロンプトベースのスキル（グローバルまたはプロジェクト単位）を定義できます。
- **⚙️ 設定エディター** -- `~/.claude/settings.json` のビジュアルエディターと JSON エディター。権限と環境変数の設定に対応しています。
- **📊 トークン使用量追跡** -- アシスタントのレスポンスごとに入力/出力トークン数と推定コストが表示されます。
- **🌗 ダーク / ライト テーマ** -- ナビゲーションレールのワンクリックでテーマを切り替えられます。
- **⌨️ スラッシュコマンド** -- `/help`、`/clear`、`/cost`、`/compact`、`/doctor`、`/review` などの組み込みコマンドを使用できます。
- **🖥️ Electron パッケージング** -- 隠れたタイトルバー、バンドルされた Next.js サーバー、自動ポート割り当てを備えたデスクトップ アプリとして配布されます。
---
## スクリーンショット
![CodePilot](docs/screenshot.png)
---
## 前提条件
> **重要**: CodePilot は Claude Code Agent SDK を内部で呼び出します。アプリを起動する前に、`claude` が `PATH` で利用可能であることを確認し、認証済み (`claude login`) であることを確認してください。
| 要件 | 最小バージョン |
|---|---|
| **Node.js** | 18+ |
| **Claude Code CLI** | インストール済みおよび認証済み (`claude --version` が動作することを確認) |
| **npm** | 9+ (Node 18 に付属) |
[ダウンロード](#プラットフォームとインストール) | [クイックスタート](#クイックスタート) | [ドキュメント](#ドキュメント) | [コントリビュート](#コントリビュート) | [コミュニティ](#コミュニティ)
---
## ダウンロード
## Why CodePilot
プリビルド版のリリースは [**Releases**](https://github.com/op7418/CodePilot/releases) ページから利用できます。
**Multi-provider, one interface.** Connect to Anthropic, OpenRouter, Bedrock, Vertex, or any custom endpoint. Switch providers and models mid-conversation without losing context.
### サポートプラットフォーム
**MCP + Skills extensibility.** Add MCP servers (stdio / sse / http) with runtime status monitoring. Define reusable prompt-based skills and invoke them as slash commands. Browse community skills from skills.sh.
- **macOS**: ユニバーサルバイナリ（arm64 + x64）を `.dmg` として配布
- **Windows**: x64 を `.zip` として配布
- **Linux**: x64 と arm64 を `.AppImage`、`.deb`、`.rpm` として配布
**Control from anywhere.** Bridge connects CodePilot to Telegram, Feishu, Discord, and QQ. Send a message from your phone, get the response on your desktop.
**An assistant that knows your project.** The .assistant workspace stores persona files, onboarding flows, daily check-ins, and persistent memory.
**Built for daily use.** Pause, resume, and rewind sessions. Split-screen dual conversations. Token usage tracking. CLI session import. Dark and light themes.
---
## クイックスタート
### パス A: リリース版をダウンロード（ほとんどのユーザー向け）
1. Claude Code CLI をインストール: `npm install -g @anthropic-ai/claude-code`
2. 認証: `claude login`
3. [Releases](https://github.com/op7418/CodePilot/releases) ページからプラットフォームに合ったインストーラーをダウンロード
4. CodePilot を起動
### パス B: ソースからビルド（開発者向け）
| 前提条件 | 最小バージョン |
|---|---|
| Node.js | 18+ |
| Claude Code CLI | インストール済みおよび認証済み |
| npm | 9+ (Node 18 に付属) |
```bash
# リポジトリのクローン
git clone https://github.com/op7418/CodePilot.git
cd codepilot
# 依存関係のインストール
cd CodePilot
npm install
# 開発モードで起動（ブラウザ）
npm run dev
# -- または、開発モードで完全な Electron アプリを起動 --
node scripts/build-electron.mjs # Electron メインプロセスをコンパイル（初回のみ必要）
npm run electron:dev
npm run dev # ブラウザモード http://localhost:3000
# -- または --
npm run electron:dev # フルデスクトップアプリ
```
その後、[http://localhost:3000](http://localhost:3000)（ブラウザモード）を開くか、Electron ウィンドウが表示されるまで待ちます。
---
## インストールのトラブルシューティング
## 初回起動
CodePilot はまだコード署名されていないため、初回起動時にオペレーティングシステムがセキュリティ警告を表示します。
1. **Claude を認証** -- ターミナルで `claude login` を実行。
2. **プロバイダーを設定** -- 設定 > Providers で API キーを追加するか、CLI のデフォルト認証を使用。
3. **会話を作成** -- 作業ディレクトリ、モード（Code / Plan / Ask）、モデルを選択。
4. **Assistant Workspace を設定**（任意）-- .assistant ディレクトリで Onboarding、デイリーチェックイン、ペルソナファイルを有効化。
5. **MCP サーバーを追加**（任意）-- エクステンションページで外部ツールやサービスを接続。
### macOS
---
**「Apple はこのソフトウェアを確認できません」** というダイアログが表示されます。
## コア機能
**オプション 1 -- 右クリックで開く**
### 会話とコーディング
1. Finder で `CodePilot.app` を右クリック（または Control キーを押しながらクリック）します。
2. コンテキストメニューから **開く** を選択します。
3. 確認ダイアログで **開く** をクリックします。
| 機能 | 詳細 |
|---|---|
| インタラクションモード | Code / Plan / Ask |
| 推論レベル | Low / Medium / High / Max + Thinking モード |
| 権限制御 | Default / Full Access、アクション単位の承認 |
| セッション制御 | 一時停止、再開、チェックポイントへの巻き戻し、アーカイブ |
| モデル切り替え | 会話中にモデルを変更 |
| スプリットスクリーン | 2 つのセッションを並べて表示 |
| 添付ファイル | ファイルと画像、マルチモーダルビジョン対応 |
| スラッシュコマンド | /help /clear /cost /compact /doctor /review など |
**オプション 2 -- システム設定**
### 拡張と統合
1. **システム設定** > **プライバシーとセキュリティ** を開きます。
2. **セキュリティ** セクションまでスクロールします。
3. CodePilot がブロックされているというメッセージが表示されます。**このまま開く** をクリックします。
4. 必要に応じて認証を行い、アプリを起動します。
| 機能 | 詳細 |
|---|---|
| プロバイダー | Anthropic / OpenRouter / Bedrock / Vertex / カスタムエンドポイント |
| MCP サーバー | stdio / sse / http、ランタイム状態監視 |
| スキル | カスタム / プロジェクト / グローバルスキル、skills.sh マーケットプレイス |
| Bridge | Telegram / Feishu / Discord / QQ リモート制御 |
| CLI インポート | Claude Code CLI .jsonl セッション履歴のインポート |
| 画像生成 | Gemini / Anthropic 画像生成、バッチタスク、ギャラリー |
**オプション 3 -- ターミナルコマンド**
### データとワークスペース
| 機能 | 詳細 |
|---|---|
| Assistant Workspace | .assistant ディレクトリ、ペルソナ、Onboarding、チェックイン、メモリ |
| ファイルブラウザ | プロジェクトファイルツリー、シンタックスハイライトプレビュー |
| 使用量分析 | トークン数、コスト見積もり、日次使用量チャート |
| ローカルストレージ | SQLite（WAL モード）、全データはローカルに保存 |
| i18n | English + Chinese |
| テーマ | ダーク / ライト、ワンクリック切り替え |
---
## プラットフォームとインストール
| プラットフォーム | フォーマット | アーキテクチャ |
|---|---|---|
| macOS | .dmg | arm64 (Apple Silicon) + x64 (Intel) |
| Windows | .exe (NSIS) | x64 + arm64 |
| Linux | .AppImage / .deb / .rpm | x64 + arm64 |
[Releases](https://github.com/op7418/CodePilot/releases) ページからダウンロードしてください。
CodePilot はまだコード署名されていないため、初回起動時に OS がセキュリティ警告を表示します。
<details>
<summary>macOS:「Apple はこのソフトウェアを確認できません」</summary>
**オプション 1** -- Finder で `CodePilot.app` を右クリック > 開く > 確認。
**オプション 2** -- システム設定 > プライバシーとセキュリティ > セキュリティまでスクロール >「このまま開く」をクリック。
**オプション 3** -- ターミナルで実行:
```bash
xattr -cr /Applications/CodePilot.app
```
</details>
これは隔離属性を削除するため、macOS はアプリをブロックしなくなります。
<details>
<summary>Windows: SmartScreen がインストーラーをブロック</summary>
### Windows
**オプション 1** -- SmartScreen ダイアログで「詳細情報」をクリック、次に「実行を続ける」。
Windows SmartScreen はインストーラーまたは実行ファイルをブロックします。
**オプション 1 -- 実行を続ける**
1. SmartScreen ダイアログで **詳細情報** をクリックします。
2. **実行を続ける** をクリックします。
**オプション 2 -- アプリインストール制御を無効にする**
1. **設定** > **アプリ** > **詳細アプリ設定** を開きます。
2. **アプリインストール制御**（または「アプリの取得元」）をトグルして、どこからでもアプリをインストール可能にします。
**オプション 2** -- 設定 > アプリ > 詳細アプリ設定 > アプリインストール制御をどこからでも許可に設定。
</details>
---
## テック スタック
## ドキュメント
| レイヤー | テクノロジー |
|---|---|
| フレームワーク | [Next.js 16](https://nextjs.org/)（App Router） |
| デスクトップシェル | [Electron 40](https://www.electronjs.org/) |
| UI コンポーネント | [Radix UI](https://www.radix-ui.com/) + [shadcn/ui](https://ui.shadcn.com/) |
| スタイリング | [Tailwind CSS 4](https://tailwindcss.com/) |
| アニメーション | [Motion](https://motion.dev/)（Framer Motion） |
| AI 統合 | [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) |
| データベース | [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)（組み込み、ユーザーごと） |
| Markdown | react-markdown + remark-gfm + rehype-raw + [Shiki](https://shiki.style/) |
| ストリーミング | [Vercel AI SDK](https://sdk.vercel.ai/) ヘルパー + Server-Sent Events |
| アイコン | [Hugeicons](https://hugeicons.com/) + [Lucide](https://lucide.dev/) |
| テスト | [Playwright](https://playwright.dev/) |
| ビルド / パック | electron-builder + esbuild |
- [ARCHITECTURE.md](./ARCHITECTURE.md) -- アーキテクチャ、テックスタック、ディレクトリ構成、データフロー
- [docs/handover/](./docs/handover/) -- 設計決定、引き継ぎドキュメント
- [docs/exec-plans/](./docs/exec-plans/) -- 実行計画、技術的負債トラッカー
---
## プロジェクト構成
## コミュニティ
```
codepilot/
├── electron/ # Electron メインプロセス＆プリロード
│ ├── main.ts # ウィンドウ作成、組み込みサーバーライフサイクル
│ └── preload.ts # コンテキスト ブリッジ
├── src/
│ ├── app/ # Next.js App Router ページ＆ API ルート
│ │ ├── chat/ # 新規チャットページ＆ [id] セッションページ
│ │ ├── extensions/ # スキル＋ MCP サーバー管理
│ │ ├── settings/ # 設定エディター
│ │ └── api/ # REST ＋ SSE エンドポイント
│ │ ├── chat/ # セッション、メッセージ、ストリーミング、権限
│ │ ├── files/ # ファイルツリー＆プレビュー
│ │ ├── plugins/ # プラグイン＆ MCP CRUD
│ │ ├── settings/ # 設定の読み書き
│ │ ├── skills/ # スキル CRUD
│ │ └── tasks/ # タスク追跡
│ ├── components/
│ │ ├── ai-elements/ # メッセージバブル、コードブロック、ツール呼び出しなど
│ │ ├── chat/ # ChatView、MessageList、MessageInput、ストリーミング
│ │ ├── layout/ # AppShell、NavRail、Header、RightPanel
│ │ ├── plugins/ # MCP サーバーリスト＆エディター
│ │ ├── project/ # FileTree、FilePreview、TaskList
│ │ ├── skills/ # SkillsManager、SkillEditor
│ │ └── ui/ # Radix ベースのプリミティブ（button、dialog、tabs など）
│ ├── hooks/ # カスタム React フック（usePanel など）
│ ├── lib/ # コアロジック
│ │ ├── claude-client.ts # Agent SDK ストリーミングラッパー
│ │ ├── db.ts # SQLite スキーマ、マイグレーション、CRUD
│ │ ├── files.ts # ファイルシステムヘルパー
│ │ ├── permission-registry.ts # 権限リクエスト/レスポンスブリッジ
│ │ └── utils.ts # 共有ユーティリティ
│ └── types/ # TypeScript インターフェース＆ API コントラクト
├── electron-builder.yml # パッケージング設定
├── package.json
└── tsconfig.json
```
- [GitHub Issues](https://github.com/op7418/CodePilot/issues) -- バグ報告と機能リクエスト
- [GitHub Discussions](https://github.com/op7418/CodePilot/discussions) -- 質問と一般的なディスカッション
---
## 開発
## コントリビュート
1. リポジトリをフォークしてフィーチャーブランチを作成
2. `npm install` と `npm run electron:dev` でローカル開発
3. PR を開く前に `npm run test` を実行
4. `main` に対して明確な説明付きの PR を提出
PR はフォーカスを保つ -- 1 つのフィーチャーまたは修正ごとに 1 つの PR。
<details>
<summary>開発コマンド</summary>
```bash
# Next.js 開発サーバーのみを実行（ブラウザで開く）
npm run dev
# Electron メインプロセスをコンパイル（初回実行前に必要）
node scripts/build-electron.mjs
# 開発モードで完全な Electron アプリを実行
# (Next.js を起動して待機し、その後 Electron を開く)
npm run electron:dev
# 本番環境ビルド（Next.js 静的エクスポート）
npm run build
# Electron 配布可能ファイルと Next.js をビルド
npm run electron:build
# macOS DMG をパッケージ（ユニバーサルバイナリ）
npm run electron:pack
npm run dev # Next.js 開発サーバー（ブラウザ）
npm run electron:dev # フル Electron アプリ（開発モード）
npm run build # 本番ビルド
npm run electron:build # Electron 配布ファイルをビルド
npm run electron:pack:mac # macOS DMG (arm64 + x64)
npm run electron:pack:win # Windows NSIS インストーラー
npm run electron:pack:linux # Linux AppImage, deb, rpm
```
### メモ
**CI/CD:** `v*` タグをプッシュすると、全プラットフォームビルドが自動的にトリガーされ、GitHub Release が作成されます。
- Electron メインプロセス（`electron/main.ts`）は Next.js スタンドアロン サーバーをフォークし、`127.0.0.1` 経由でランダムなフリーポートで接続します。
- チャット データは `~/.codepilot/codepilot.db`（または開発モードでは `./data/codepilot.db`）に保存されます。
- アプリは SQLite の WAL モードを使用するため、同時読み込みは高速です。
---
## 貢献
貢献を歓迎します。開始するには：
1. リポジトリをフォークしてフィーチャーブランチを作成します。
2. `npm install` で依存関係をインストールします。
3. `npm run electron:dev` を実行して、変更をローカルでテストします。
4. プルリクエストを開く前に `npm run lint` が成功することを確認します。
5. 変更内容と理由を明確に説明した PR を `main` に対して開きます。
PR はフォーカスを保つようにしてください -- 1 つのフィーチャーまたは修正ごとに 1 つの PR を開いてください。
**メモ:**
- Electron は `127.0.0.1` 上で Next.js スタンドアロンサーバーをフォークし、ランダムなフリーポートで接続
- チャットデータは `~/.codepilot/codepilot.db`（開発モード: `./data/`）に保存
- SQLite は WAL モードを使用し、同時読み込みが高速
</details>
---