AgentPi

The Mission Control for AI Coding Agents

Monitor, orchestrate, and review Claude Code, Codex CLI, and pi-mono sessions — all in real time, all on your machine.

English | 中文

Privacy-first. All data stays on your machine. No telemetry, no cloud, no tracking. Communication is localhost only.

Why AgentPi?

Running multiple AI coding agents across projects gets messy fast. Context windows fill up silently, tool calls pile up awaiting approval, and costs spiral without visibility.

AgentPi gives you a unified cockpit — one screen to monitor every active session, review diffs inline, approve tool calls, launch parallel agents, and track token usage across providers.

Features

Real-time Monitoring

Live session updates via kqueue file-system watchers — zero polling, byte-offset incremental reads. Status indicators, token counts, tool activity feed, and context window usage at a glance.

Multi-Provider Orchestration

Run Claude Code, Codex CLI, and pi-mono sessions side by side — all as first-class citizens. Launch parallel agents with manual prompts or AI-planned orchestration across git worktrees.

Inline Diff Review

Split-pane diff viewer with syntax highlighting. Built-in inline editor to review changes and send feedback directly to agents.

Embedded Terminal

Full PTY terminal (SwiftTerm) inside each session card. Resume or start sessions without ever leaving the app.

Mobile Relay & `happy` CLI

One-click handoff of tasks between providers (Claude ↔ Codex ↔ Pi). Generates JSONL + Markdown handoff artifacts preserving full session context. Powered by the happy CLI wrapper with intelligent detection and fallback.

Batch Task Runner

Run non-interactive one-off commands from configurable templates. Real-time stdout/stderr streaming with smart ANSI stripping, stop/rerun controls, elapsed time tracking, and auto-scroll. One-click Stop button sends SIGTERM; 20-second watchdog prevents "frozen UI" for buffered-output CLIs. CI-safe execution (CI=1, GIT_TERMINAL_PROMPT=0) with automatic happy relay fallback.

Smart Orchestration

AI-driven parallel session planning via ClaudeCodeSDK. Three modes: Parallel, Prototype, and Exploration. Claude generates a structured plan, AgentPi spawns sessions across git worktrees automatically.

DAG Workflow Engine

Execution graphs with parallel nodes, conditional branching, approval gates, and safe expression evaluation.

Unified Command Templates

Single template system for all providers and intents — start_session, resume_session, batch_run, mobile_relay. Supports placeholders ({{prompt}}, {{project_path}}, {{handoff_jsonl}}), custom executables, drag-to-reorder, enable/disable.

Git Integration

Worktree management, branch-based session launching, pending changes preview, and inline diff review.

Developer UX

Command palette (Cmd+K), web preview panel, plan view, global full-text search, drag-and-drop file attachments, dev server management, proxy injection, and multi-column layouts.

Customizable Themes & i18n

YAML themes with hot-reload. Built-in themes: Claude, Codex, Bat, Xcode. Localized in 5 languages: English, 简体中文, 日本語, 한국어, Tiếng Việt.

Auto-Updates

Sparkle-powered updates with EdDSA signature verification. One-command local release flow with DMG distribution.

Quick Start

Prerequisites

Requirement	Notes
macOS 14.0+	Xcode Command Line Tools required
Node.js >= 22	Download
Claude Code CLI	Installed & authenticated — Setup guide
Codex CLI (optional)	Setup guide
happy CLI (optional)	Enables cross-provider Mobile Relay

Install & Run

# Clone the repository
git clone https://github.com/Cz07cring/agentpi.git
cd agentpi && npm install

# Start the local daemon (port 43210)
npm run dev

# Build & launch the macOS app
npm run mac:build && npm run mac:open

Or try it instantly with demo data:

npm run mac:demo

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                      macOS Native Client                         │
│                   Swift 6 · SwiftUI · AppKit                     │
│                                                                  │
│    Hub  ·  Diff View  ·  Terminal  ·  Cmd+K  ·  Settings         │
│                           │                                      │
│                 CLISessionsViewModel                             │
│                 (@MainActor · Combine)                           │
│                           │                                      │
│     SessionFileWatcher  ·  CodexFileWatcher  ·  ThemeWatcher     │
│              kqueue + byte-offset incremental reads              │
└───────────────┬──────────────────────────────────────────────────┘
                │
                │  ~/.claude/projects/{path}/{id}.jsonl
                │  ~/.codex/sessions/{date}/{id}.jsonl
                │
                │  HTTP + WebSocket · localhost:43210
                ▼
┌──────────────────────────────────────────────────────────────────┐
│                         Local Daemon                             │
│                  Node.js 22 · Express 5 · WS                     │
│                                                                  │
│    SessionManager  ·  WorkflowEngine  ·  TerminalService         │
│    WorktreeService ·  PiRuntimeUpdater ·  RpcProcessPool         │
│    SearchIndexer   ·  StatsAggregator  ·  PersistenceStore       │
│    DevServerService ·  DaemonEventBus                            │
└──────────────────────────────────────────────────────────────────┘

Layer	Stack	Responsibility
Native Client	Swift 6 / SwiftUI / AppKit	Real-time UI, file watching, terminal emulation, diff rendering
Local Daemon	Node.js 22 / Express 5 / WS	Session orchestration, workflow engine, RPC pool, persistence
Protocol	TypeScript 5.9 / Zod 4	Shared type-safe schemas for client ↔ daemon communication

Mobile Relay & `happy` CLI

AgentPi integrates with the happy CLI wrapper to enable seamless cross-provider handoff:

Claude  → Codex    happy codex --project {{project_path}} --handoff {{handoff_jsonl}}
Claude  → Pi       happy pi --project {{project_path}} --handoff {{handoff_jsonl}}
Codex   → Claude   happy --project {{project_path}} --handoff {{handoff_jsonl}}
Codex   → Pi       happy pi --project {{project_path}} --handoff {{handoff_jsonl}}
Pi      → Claude   happy --project {{project_path}} --handoff {{handoff_jsonl}}
Pi      → Codex    happy codex --project {{project_path}} --handoff {{handoff_jsonl}}

How it works:

Click the relay button on any active session
AgentPi captures the session's prompt, conversation history, project path, and git branch
Two handoff artifacts are written to {project}/.agentpi/mobile-relay/{YYYY-MM-DD}/:
- JSONL — machine-readable state (session ID, providers, prompt, timestamps)
- Markdown — human-readable summary with context, diffs, and instructions
The target agent launches via happy with full context preserved

Smart Fallback: When a happy relay command is used as a batch template, AgentPi automatically detects it and falls back to the native CLI (claude, codex, pi), ensuring commands run reliably without the external terminal dependency.

Smart Orchestration

AgentPi uses ClaudeCodeSDK to enable AI-driven parallel session planning. Describe your goal and Claude generates a structured orchestration plan:

{
  "modulePath": "/path/to/project",
  "sessions": [
    {
      "description": "Implement user authentication module",
      "branchName": "feat/auth-module",
      "sessionType": "parallel",
      "prompt": "Implement JWT-based authentication..."
    },
    {
      "description": "Add database migration scripts",
      "branchName": "feat/db-migrations",
      "sessionType": "parallel",
      "prompt": "Create migration scripts for..."
    }
  ]
}

AgentPi spawns each session in its own git worktree, running them in parallel across branches:

Mode	Use Case
Parallel	Same task split across different modules or files
Prototype	Same goal with different implementation approaches
Exploration	Related but distinct features explored simultaneously

Command Templates

All session launching, batch execution, and mobile relay commands are driven by a unified template system (AgentCommandTemplateV1). Templates are configurable per provider and intent.

Template Intents

Intent	Description
`start_session`	Launch an interactive PTY session
`resume_session`	Resume an existing session
`batch_run`	One-off non-interactive command
`mobile_relay`	Mobile handoff via external terminal

Built-in Templates

Provider	Template	Intent	Command
Claude	Session Fast	start_session	`claude --dangerously-skip-permissions {{prompt}}`
Claude	Batch Fast	batch_run	`claude -p {{prompt}} --dangerously-skip-permissions`
Claude	Batch Stream Verbose	batch_run	`claude -p {{prompt}} --output-format stream-json --verbose`
Claude	Mobile Relay	mobile_relay	`happy --project {{project_path}} --handoff {{handoff_jsonl}}`
Codex	Session Fast	start_session	`codex {{prompt}}`
Codex	Session Aggressive	start_session	`codex --full-auto {{prompt}}`
Codex	Batch JSONL	batch_run	`codex exec {{prompt}} --json`
Codex	Mobile Relay	mobile_relay	`happy codex --project {{project_path}} --handoff {{handoff_jsonl}}`
Pi	Session Stable	start_session	`pi --no-extensions --no-skills --no-themes {{prompt}}`
Pi	Batch Fast	batch_run	`pi -p {{prompt}} --no-extensions --no-skills --no-themes`
Pi	Mobile Relay	mobile_relay	`happy pi --project {{project_path}} --handoff {{handoff_jsonl}}`

Placeholders

Placeholder	Replaced With
`{{prompt}}`	User prompt text
`{{project_path}}`	Absolute path to the project directory
`{{handoff_jsonl}}`	Path to the generated JSONL handoff artifact
`{{handoff_markdown}}`	Path to the generated Markdown handoff artifact
`{{session_id}}`	Current session ID
`{{branch}}`	Current git branch name

Create custom templates, reorder them, and set per-provider defaults from Settings → Command Templates.

Batch Task Runner

The batch runner executes non-interactive commands defined by batch_run templates. Unlike interactive sessions, batch tasks run as headless subprocesses with piped I/O.

Real-time streaming — stdout and stderr are captured and displayed live in the Batch Runs panel with smart ANSI/control-sequence stripping for clean output
Stop & Cancel — one-click Stop button sends SIGTERM to the running process; cancelled tasks show "Cancelled" status (exit code 130) instead of generic failure
Watchdog timer — if no visible output appears within 20 seconds, a helpful hint is displayed so the UI never looks frozen
Auto-scroll — output panel automatically scrolls to the latest line as new data arrives
Waiting state — when CLI output is buffered (e.g. claude -p in non-stream mode), the panel shows a live elapsed-time counter and chunk count
Process lifecycle — each task captures its PID immediately after launch; rerun re-launches from the same template and context
happy auto-detection — if a happy relay command is used as a batch template, AgentPi automatically falls back to the native CLI for local execution
CI-safe environment — batch tasks run with CI=1, GIT_TERMINAL_PROMPT=0, and GIT_ASKPASS=/usr/bin/false to prevent interactive prompts from blocking headless execution

Proxy Support

AgentPi supports configurable proxy injection for CLI sessions. When enabled, proxy environment variables (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY) are automatically set in the spawned process environment.

Configure proxy settings in Settings → Network or via ProxyEnvironment defaults.

Project Structure

agentpi/
├── apps/
│   └── daemon/                       # Local Node.js server (Express + WebSocket)
│       └── src/modules/              # Session, Workflow, Terminal, Search, Stats, DevServer
├── packages/
│   └── protocol/                     # Shared Zod schemas & TypeScript types
├── external/
│   └── AgentPi/                      # macOS native client (Swift / SwiftUI)
│       └── app/modules/AgentPiCore/  # Core framework (120+ Swift sources)
│           └── Sources/AgentPi/
│               ├── Configuration/    # Service locator, defaults, environment
│               ├── Design/           # Theme system (YAML parsing, hot-reload)
│               ├── Intelligence/     # Smart orchestration via ClaudeCodeSDK
│               ├── Models/           # Session, state, cost, relay, template models
│               ├── Services/         # File watchers, Git, search, terminal, batch, relay
│               ├── UI/              # 40+ SwiftUI views
│               ├── ViewModels/      # @MainActor view models
│               ├── Utils/           # Logging, proxy, scoring, L10n
│               └── Resources/       # Localization (en, zh-Hans, ja, ko, vi)
├── scripts/                          # Build, seed, diagnostic scripts
├── docs/                             # Build, testing, troubleshooting guides
└── .github/workflows/                # CI/CD pipelines

Tech Stack

Component	Technology
macOS Client	Swift 6.0, SwiftUI, AppKit, Combine, `@Observable` macro
Concurrency	Swift actors, `async/await`, `withTaskGroup`, `@MainActor`
Daemon	Node.js 22, Express 5, WebSocket (`ws`), SQLite (`node:sqlite`)
Protocol	TypeScript 5.9, Zod 4
Persistence	GRDB.swift (client) + `node:sqlite` (daemon)
File Watching	kqueue via DispatchSource — zero polling, byte-offset incremental reads
Terminal	SwiftTerm (PTY emulation)
Diff Rendering	PierreDiffsSwift (split-pane with inline editor)
Markdown	swift-markdown-ui
Syntax Highlighting	HighlightSwift
Theme Parsing	Yams (YAML hot-reload)
AI Integration	ClaudeCodeSDK 1.2.4
CLI Compatibility	`happy` wrapper (auto-detection & native fallback)
Auto-Updates	Sparkle (EdDSA signed)
Testing	Vitest (daemon/protocol), XCTest (macOS client)
Monorepo	npm workspaces
CI/CD	GitHub Actions

API Overview

The daemon exposes a REST + WebSocket API on localhost:43210.

Sessions

Method	Endpoint	Description
`GET`	`/v1/sessions`	List active sessions
`POST`	`/v1/sessions`	Create a new session
`POST`	`/v1/sessions/:id/prompt`	Send a user prompt
`POST`	`/v1/sessions/:id/steer`	Steer a running agent
`POST`	`/v1/sessions/:id/follow-up`	Follow-up prompt
`POST`	`/v1/sessions/:id/abort`	Abort the running agent
`POST`	`/v1/sessions/:id/wait-idle`	Block until session idle (max 60s)
`GET`	`/v1/sessions/:id/state`	Get full session state
`GET`	`/v1/sessions/:id/runtime-state`	Get runtime binding state
`DELETE`	`/v1/sessions/:id`	Close session

Workflows & Approvals

Method	Endpoint	Description
`POST`	`/v1/workflows`	Create workflow from DAG
`POST`	`/v1/workflows/:id/run`	Execute a workflow
`GET`	`/v1/workflows/runs/:runId`	Get run state
`POST`	`/v1/workflows/:id/validate`	Validate workflow graph
`POST`	`/v1/approvals/:id/decision`	Approve or reject a tool call

Terminals, Dev Servers & System

Method	Endpoint	Description
`POST`	`/v1/terminals`	Start a PTY terminal
`POST`	`/v1/terminals/:id/input`	Send input to terminal
`DELETE`	`/v1/terminals/:id`	Stop terminal
`POST`	`/v1/dev-servers`	Start dev server (npm/pnpm/yarn/bun)
`DELETE`	`/v1/dev-servers/:id`	Stop dev server
`POST`	`/v1/worktrees`	Create a git worktree
`DELETE`	`/v1/worktrees/:id`	Remove a git worktree
`GET`	`/v1/search?q=...`	Full-text search across sessions
`GET`	`/v1/stats/:id`	Session token & tool stats
`POST`	`/v1/runtime/update/check`	Check for runtime updates
`POST`	`/v1/runtime/update/apply`	Apply runtime updates
`GET`	`/health`	Health check (no auth required)
`GET`	`/health/details`	Detailed health (uptime, connections, PID)

WebSocket — ws://localhost:43210/ws?token=... Real-time events: session state, workflow progress, approval requests, terminal output, runtime updates.

Scripts

Script	Description
`npm run dev`	Start daemon in dev mode (file watching)
`npm run dev:doctor`	Diagnose environment & ports
`npm run build`	Build all workspaces
`npm run typecheck`	TypeScript type checking
`npm test`	Unit & contract tests (Vitest)
`npm run mac:build`	Build macOS app (xcodebuild)
`npm run mac:open`	Launch macOS app
`npm run mac:demo`	Seed demo data + open app
`npm run test:release-gate`	Full release gate (typecheck + test + mac:build + build)

Keyboard Shortcuts

Shortcut	Action	Shortcut	Action
Cmd+K	Command palette	Cmd+N	New session
Cmd+B	Toggle sidebar	Cmd+,	Settings
Cmd+[	Previous session	Cmd+]	Next session
Escape	Dismiss / close	Return	Send inline comment (diff view)

Security

All communication stays on 127.0.0.1. Zero network egress.

Mechanism	Detail
Token Auth	Required on all routes except `/health` via `x-agentpi-token` header or `Authorization: Bearer`
CORS	Restricted to `localhost` origins
WebSocket Auth	Token via header or query parameter
Audit Logging	Every request logged to local SQLite
Safe Evaluation	Workflow conditions use a sandboxed evaluator — no `eval()`

export AGENTPI_DAEMON_TOKEN="your-secret-token"

Custom Themes

Drop a YAML file into ~/Library/Application Support/AgentPi/Themes/ — changes apply instantly via hot-reload.

name: My Theme
version: 1
author: Your Name
colors:
  brand:
    primary: "#7C3AED"
    secondary: "#6D28D9"
  backgrounds:
    dark: "#1A1A2E"
    light: "#FFFFFF"

Built-in themes: Claude · Codex · Bat · Xcode

Provider Compatibility

AgentPi treats all providers as first-class citizens:

Provider	Session Monitoring	Batch Execution	Mobile Relay	Smart Orchestration
Claude Code	✓	✓	✓	✓
Codex CLI	✓	✓	✓	—
pi-mono	✓	✓	✓	—
`happy` CLI	—	✓ (fallback)	✓ (wrapper)	—

pi-mono is an open-source AI agent toolkit by @badlogic. The happy CLI wrapper enables seamless cross-provider relay with intelligent command detection and automatic native fallback.

Contributing

Fork the repo & create a feature branch
Keep PRs focused — one feature or fix per PR
Run the release gate before submitting: npm run test:release-gate
Open a PR with clear motivation, approach, and test results

See CONTRIBUTING.md for details.

Documentation

Document	Description
`docs/macos-agentpi.md`	macOS build & branding guide
`docs/testing-matrix.md`	Testing strategy & coverage matrix
`docs/troubleshooting.md`	Common issues & debugging
`external/AgentPi/CLAUDE.md`	Architecture deep-dive

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github/workflows		.github/workflows
apps/daemon		apps/daemon
docs		docs
external/AgentPi		external/AgentPi
packages/protocol		packages/protocol
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
appcast.xml		appcast.xml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

AgentPi

The Mission Control for AI Coding Agents

Why AgentPi?

Features

Real-time Monitoring

Multi-Provider Orchestration

Inline Diff Review

Embedded Terminal

Mobile Relay & happy CLI

Batch Task Runner

Smart Orchestration

DAG Workflow Engine

Unified Command Templates

Git Integration

Developer UX

Customizable Themes & i18n

Auto-Updates

Quick Start

Prerequisites

Install & Run

Architecture

Mobile Relay & happy CLI

Smart Orchestration

Command Templates

Template Intents

Built-in Templates

Placeholders

Batch Task Runner

Proxy Support

Project Structure

Tech Stack

API Overview

Scripts

Keyboard Shortcuts

Security

Custom Themes

Provider Compatibility

Contributing

Documentation

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Mobile Relay & `happy` CLI

Mobile Relay & `happy` CLI

Packages