cc-pane

Imported from wuxiran/cc-pane (AGENTS.md). Install upstream with npx skills add wuxiran/cc-pane. Copyright stays with the author.

CC-Panes Agent Guide

Multi-instance split-pane manager for Claude Code — a cross-platform desktop app built with Tauri 2.

This document provides essential information for AI coding agents working on the CC-Panes codebase.

Project Overview

CC-Panes is a desktop application that lets users run multiple Claude Code CLI instances side by side in a split-pane terminal layout. It organizes AI-powered development workflows with workspaces, projects, and tasks — all from a single desktop app.

Key Features

• Split-Pane Terminal — Run multiple terminals in flexible horizontal/vertical split layouts
• Workspace Management — Organize projects into workspaces with pinning, hiding, and reordering
• Built-in Terminal — Full-featured terminal (xterm.js + PTY) with multi-tab support
• Claude Code Integration — Launch Claude Code sessions, resume conversations, manage providers
• Git Integration — Branch status, pull/push/fetch/stash, worktree management, git clone
• Session Management — Track launch history, clean broken sessions, resume previous work
• Local History — File version tracking with diff view, labels, branch-aware snapshots
• File Browser — Project file tree with search, create, rename, delete, copy, move operations
• Code Editor — Monaco-based editor with 60+ language support, Markdown preview, image preview
• Screenshot — Region capture with global shortcut, multi-monitor support
• MCP Server Config — Configure MCP servers per project

Technology Stack

Architecture

Data Flow

React Component → Zustand Store → Service (invoke) → Tauri IPC → Command → Service → Repository → SQLite/FS

┌─────────────────────────────────────────────────────────────┐
│  React Frontend                                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐  │
│  │ Sidebar  │ │ Panes    │ │ Panels   │ │ UI Components │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └───────────────┘  │
│       │             │            │                           │
│  ┌────┴─────────────┴────────────┴────┐                     │
│  │  Services (invoke) + Stores        │                     │
│  └────────────────┬───────────────────┘                     │
├───────────────────┼─────────────────────────────────────────┤
│  Tauri IPC        │                                         │
├───────────────────┼─────────────────────────────────────────┤
│  Rust Backend     │                                         │
│  ┌────────────────┴───────────────────┐                     │
│  │  Commands → Services → Repository  │                     │
│  └────────────────┬───────────────────┘                     │
│  ┌────────────────┴───────────────────┐                     │
│  │  SQLite / File System / PTY        │                     │
│  └────────────────────────────────────┘                     │
└─────────────────────────────────────────────────────────────┘

Workspace Crate Structure

The Rust backend is organized as a Cargo workspace:

Project Structure

cc-panes/
├── web/                    # React frontend source
│   ├── components/         # React components
│   │   ├── panes/          # Split-pane terminal components
│   │   ├── sidebar/        # Sidebar components
│   │   ├── settings/       # Settings sub-components
│   │   └── ui/             # shadcn/ui base components
│   ├── stores/             # Zustand state management
│   ├── services/           # Frontend service layer (invoke wrappers)
│   ├── hooks/              # Custom React hooks
│   ├── types/              # TypeScript type definitions
│   ├── i18n/               # Internationalization
│   ├── lib/                # Shared frontend helpers
│   └── utils/              # Utility functions
│
├── src-tauri/              # Tauri Rust backend
│   └── src/
│       ├── commands/        # Tauri IPC command handlers
│       ├── services/        # Business logic layer
│       ├── repository/      # Data access layer (SQLite)
│       ├── models/          # Data models
│       └── utils/           # Utilities (AppPaths, AppError)
│
├── cc-panes-core/          # Core business logic crate
├── cc-panes-api/           # HTTP API adapter crate
├── cc-panes-web/           # Web server for Docker deployment
├── cc-panes-cli-hook/      # Shared CLI hook runner source
├── cc-memory/              # Memory system crate
├── cc-memory-mcp/          # MCP server for memory
├── cc-notify/              # Push notification crate
├── cc-cli-adapters/        # CLI adapters crate
│
├── docs/                   # Architecture documentation
├── .claude/                # Claude Code commands, agents, hooks
└── scripts/                # Build and utility scripts

Frontend imports use the @/ alias, which resolves to web/.

Build and Test Commands

Prerequisites

• Node.js 22+
• Rust 1.83+
• Platform-specific Tauri 2 dependencies

Development

Lock file 与 CI 同步（必读）：CI 用 Node 20（npm 10）跑 npm ci。npm 11 生成/重写 package-lock.json 时会丢掉 @docsearch/js 嵌套的 react@18 子树（peer 约束 < 19.0.0），导致 CI 全矩阵 npm ci EUSAGE 失败。加减依赖后务必用 npx npm@10 install 重新生成 lock 并提交。

# Install frontend dependencies
npm install

# Run in development mode (frontend + Rust backend)
npm run tauri:dev

# Build frontend only
npm run build

# Build the production app
npm run tauri build

Sidecar sync after backend changes（必读）：终端会话的 spawn 由常驻侧车 cc-panes-daemon 执行（app 只发请求），cc-panes-cli-hook / cc-panes-ctl / cc-panes-web 同为独立二进制。改了 cc-panes-core / 适配器等后端代码后， npm run tauri:dev 不会自动重建它们——旧 daemon 仍在服务，会出现「UI 是新的、 行为是旧的」的幽灵 bug（实例：旧 daemon 不认识新 CLI id，from_id 回落 launch_claude 把启动静默换成 Claude）。同步流程：

cargo build -p cc-panes-daemon -p cc-panes-cli-hook -p cc-panes-ctl -p cc-panes-web
node scripts/copy-hook.cjs --debug        # 同步到 src-tauri/binaries + resources
# dev 运行时目录还需镜像（app 从那里拉起侧车）：
cp -f ../cc-book-target/debug/cc-panes-{daemon,cli-hook,ctl,web}.exe ../cc-book-target/debug/binaries/
# 然后杀掉常驻 daemon 让 app 重新拉起（或重启 dev app）

Frontend Testing & Checks

# TypeScript type check
npx tsc --noEmit

# Run tests
npm run test:run

# Run tests with coverage
npm run test:coverage

# Run tests with UI
npm run test:ui

Rust Testing & Checks

# Check formatting
cargo fmt --all -- --check

# Build hook binary (required before tauri build)
cargo build -p cc-panes-cli-hook --release
node scripts/copy-hook.cjs

# Cargo check
cargo check --workspace

# Lint (zero warnings policy)
cargo clippy --workspace -- -D warnings

# Run tests
cargo test --workspace

Code Style Guidelines

TypeScript (Frontend)

• Functional components + Hooks — No class components
• Zustand + Immer for immutable state updates: set((state) => { state.x = y })
• Service layer — Wrap all invoke() calls in services; components must not call Tauri APIs directly
• Path alias — Use @/ which maps to web/
• Co-located tests — Place test files next to implementation (*.test.ts)
• Keep files under 800 lines, functions under 50 lines
• Handle errors explicitly; never silently swallow them

Rust (Backend)

• AppResult<T> — Use Result<T, AppError> for unified error handling
• State injection — Inject services via State<'_, Arc<XxxService>>
• Layered architecture — Maintain Command → Service → Repository separation
• In-memory SQLite — Use :memory: for tests
• Keep files under 800 lines, functions under 50 lines

Commit Message Format

Follow Conventional Commits:

<type>: <description>

[optional body]

Testing Instructions

Frontend Tests

• Uses Vitest with jsdom environment
• Tests located in web/**/*.test.{ts,tsx}
• Coverage thresholds: 80% for statements, branches, functions, lines
• Tauri APIs are mocked in web/test/setup.ts

Rust Tests

• Uses built-in Rust test framework
• Tests co-located with source files or in tests/ directories
• In-memory SQLite for repository tests

Running Full Test Suite

# Frontend
npm run test:run

# Rust
cargo test --workspace

Dev/Release Isolation

Dev and release builds are fully isolated via cfg!(debug_assertions):

The dev build uses --config src-tauri/tauri.dev.conf.json to override settings.

New Feature Workflow (7 Steps)

1. Model: src-tauri/src/models/ (Rust) + web/types/ (TS)
2. Repository: src-tauri/src/repository/
3. Service (Rust): src-tauri/src/services/
4. Command: src-tauri/src/commands/ + register in lib.rs
5. Service (TS): web/services/
6. Store: web/stores/ (Zustand + Immer)
7. Component: web/components/

Security Considerations

CSP Configuration

Content Security Policy is defined in src-tauri/tauri.conf.json:

default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline';
worker-src 'self' blob:; img-src 'self' asset: http://asset.localhost blob: data:;
connect-src 'self' ipc: http://ipc.localhost http://localhost:* https:

Asset Protocol

Asset protocol is enabled with scope ** for file access. Be cautious when handling user-provided paths.

Input Validation

• Validate all inputs at system boundaries
• Use type-safe APIs between frontend and backend
• Sanitize file paths before filesystem operations

Secrets Management

• Updater public key is embedded in tauri.conf.json
• Provider API keys stored in local config files
• No secrets should be committed to the repository

Repository Environment Boundary

This repository supports development and verification across multiple environments, including WSL, Linux, Windows, and CI.

• When platform behavior matters, separate guidance into current-environment-verifiable and Windows-host-required.
• Do not claim Windows desktop behavior is verified from WSL or non-Windows environments alone.
• Windows-host-required validation includes: app startup on Windows, WebView2 behavior, tray behavior, global shortcuts, screenshot flow, updater or installer behavior, and Win32 or Windows PTY specifics.
• When working from WSL, prefer editing and preflight checks there, then validate Windows desktop behavior on the Windows host using the same branch or a built installer.

CI/CD Pipeline

The CI pipeline (.github/workflows/ci.yml) runs:

1. Frontend Check (Windows)

   • TypeScript type check
   • Build frontend
   • Run tests

2. Backend Check (Windows, Ubuntu)

   • Format check
   • Build hook binary
   • Cargo check
   • Clippy lint (zero warnings)
   • Run tests

3. Tauri Build Check (Windows, Ubuntu)

   • Full debug build

Key Files Reference

Claude Code Integration

This project includes .claude/ directory with:

• Commands in .claude/commands/ccbook/ — Project-specific slash commands
• Agents in .claude/agents/ — Specialized sub-agents for tasks
• Hooks in .claude/hooks/ — Session lifecycle hooks

These are bundled with the application and installed to user projects.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).