A unified web interface for AI coding agents. Own your data, switch between providers freely.

---

Why Agent Cockpit?

When you use vendor-hosted AI interfaces — Anthropic's Claude, Amazon's Kiro, Google's Gemini, OpenAI's ChatGPT — each one builds up memory and context about you: your preferences, your codebase knowledge, your working style. That memory is locked inside their platform. If a better model comes along from another provider, you can't take your conversation history, accumulated context, or customizations with you. You end up explaining yourself from scratch.

Agent Cockpit solves this by decoupling your data from the AI provider. It sits on your machine, talks to CLI-based coding agents, and keeps all conversations, sessions, and context locally on disk in open JSON files. When you switch to a different CLI backend, the new agent can access everything the previous one built up. Your investment in AI-assisted workflows stays with you, not with a vendor.

Highlighted features

• Own your data across any CLI — Every conversation, session, and memory update is stored locally as open JSON on your own disk. Switch between Claude Code, Kiro, and future backends without losing history or context. When a better model ships from another vendor, your accumulated context comes with you instead of being locked inside their platform.
• Remote web access to local or remote CLIs — Install Agent Cockpit on your laptop or on a remote machine and drive it from any browser. Pair it with a tunnel like Cloudflare Tunnel to chat with your coding agents from your phone, tablet, or a café laptop while they operate on real files in their native environment.
• Integrated memory system — Adds persistent memory to CLIs that don't have one (like Kiro) and captures memory on the fly from CLIs that do (like Claude Code). Every change to the CLI's own memory file is snapshotted locally, so your accumulated context is portable and vendor-neutral — not trapped inside whichever CLI happens to own it today.
• Token and cost tracking — Token usage and cost are tracked per conversation so you always know what a long-running task or an experiment is actually costing you.
• Message queue — Keep typing while the CLI is still responding. Queued messages fire automatically as soon as the current response finishes, so your thinking isn't gated on the agent's latency — a feature rarely found in other chat UIs.
• File and image uploads — Drag and drop, paste from the clipboard, or use the attach button to send images and text files directly into chat, with inline previews, just like any modern chat interface.
• Pick your CLI, model, and effort — Switch backends per-conversation, choose the model, and set the reasoning effort when the CLI supports it.
• Markdown export — Download any conversation or individual session as a Markdown file with one click, so your history is usable outside Agent Cockpit too.
• Knowledge base — Upload PDFs, Word docs, PowerPoints, images, spreadsheets, and text files into a per-workspace knowledge base. Agent Cockpit automatically converts and analyzes each file, extracts structured entries, organizes them into topics, and discovers connections between ideas — building a personal knowledge graph your AI agents can search and reason over during conversations. Organize uploads into folders, let the system find patterns you missed, and give every future conversation deep, queryable context that goes far beyond what fits in a single prompt or memory file.

Supported Backends

Backend	CLI	Status
Claude Code	claude	Fully supported
Kiro	kiro-cli	Fully supported

Switch between backends per-conversation using the dropdown in the chat input area. Your selected backend is remembered for new conversations.

See BACKENDS.md for a comparison of feature support across backends.

How It Works

Agent Cockpit runs on the same machine as your CLI tools. When you send a message through the browser, the server spawns a CLI process locally, streams the response back over WebSocket, and stores the conversation as a JSON file on disk. The CLI runs with full access to your local filesystem and tools, just as it would in your terminal.

This means:

• The CLI and the web interface must run on the same machine. Agent Cockpit spawns local processes, not remote API calls.
• Expose the server for remote access. Use a tunnel like Cloudflare Tunnel to chat with your coding agents from any browser, anywhere, while they operate on your local files and environment.
• OAuth protects access. Only the email addresses you configure in ALLOWED_EMAIL can log in, so your CLI sessions stay private even when exposed over the internet.

Additional features

Beyond the headline capabilities above, Agent Cockpit also ships with:

• Real-time streaming — responses stream live via WebSocket with automatic reconnection and state recovery
• Agent & tool visualization — sub-agents, tool calls, thinking, and outcomes shown in real time with grouped activity panels
• Multi-workspace support — conversations are organized by workspace directory, each with its own system prompt
• Conversation management — create, rename, search, archive, and delete conversations grouped by workspace
• Session management — reset CLI sessions and view session history with LLM-generated summaries
• Auto-generated titles — conversation titles are generated automatically from the first message
• Draft persistence — unsent messages and attached files are preserved when switching conversations
• Plan mode and interactive questions — approve plans and answer questions from the CLI directly in the browser
• Dark and light themes — system-aware theme with manual override
• Google and GitHub OAuth — email whitelist for access control
• Self-update — check for updates and apply them from the UI with one click
• Pluggable backend system — extensible adapter architecture for adding new CLI backends
• Graceful shutdown — clean process cleanup on SIGTERM/SIGINT
• File-based storage — conversations, sessions, and settings stored as JSON on disk (no database)

Prerequisites

• Node.js 18+
• At least one CLI backend installed and authenticated on the same machine:
  • Claude Code CLI (claude)
  • Kiro CLI (kiro-cli)
• At least one OAuth provider configured: Google OAuth 2.0 or GitHub OAuth (or both)
• (Optional) Cloudflare Tunnel or a similar tunnel for remote access

Quick Start

1. Clone the repository and install dependencies:

git clone https://github.com/daronyondem/agent-cockpit.git
cd agent-cockpit
npm install

2. Copy .env.example to .env and fill in your values:

cp .env.example .env

3. Start the server:

npm start

4. Open http://localhost:3334 in your browser.

Environment Variables

Variable	Required	Default	Description
PORT	No	3334	Server listen port
SESSION_SECRET	Yes	—	Secret for signing session cookies
GOOGLE_CLIENT_ID	No*	—	Google OAuth 2.0 client ID
GOOGLE_CLIENT_SECRET	No*	—	Google OAuth 2.0 client secret
GOOGLE_CALLBACK_URL	No*	—	Google OAuth callback URL
GITHUB_CLIENT_ID	No*	—	GitHub OAuth client ID
GITHUB_CLIENT_SECRET	No*	—	GitHub OAuth client secret
GITHUB_CALLBACK_URL	No*	—	GitHub OAuth callback URL
ALLOWED_EMAIL	Yes	—	Comma-separated list of allowed email addresses
DEFAULT_WORKSPACE	No	~/.openclaw/workspace	Default working directory for CLI processes
BASE_PATH	No	''	URL base path for reverse proxy deployments
KIRO_ACP_IDLE_TIMEOUT_MS	No	600000	Idle timeout (ms) before killing the Kiro ACP process

* At least one OAuth provider (Google or GitHub) must be fully configured. You can set up one or both.

Authentication Setup

You need at least one OAuth provider configured. You can use Google, GitHub, or both.

Google OAuth

1. Go to the Google Cloud Console.
2. Create a new project (or select an existing one).
3. Navigate to APIs & Services > Credentials.
4. Click Create Credentials > OAuth client ID.
5. Select Web application as the application type.
6. Add http://localhost:3334 to Authorized JavaScript origins.
7. Add http://localhost:3334/auth/google/callback to Authorized redirect URIs.
8. Copy the Client ID and Client Secret into your .env file.
9. Set ALLOWED_EMAIL to the Google account email you want to grant access.

GitHub OAuth

1. Go to GitHub Settings > Developer settings > OAuth Apps > New OAuth App.
2. Set the Authorization callback URL to http://localhost:3334/auth/github/callback (or your production URL).
3. After creating the app, copy the Client ID and generate a Client Secret.
4. Add GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, and GITHUB_CALLBACK_URL to your .env.

Remote Access with Cloudflare Tunnel

To access Agent Cockpit from outside your local network, use Cloudflare Tunnel:

cloudflared tunnel --url http://localhost:3334

Use the tunnel-provided URL to reach your local Agent Cockpit from any device. Make sure to update your OAuth provider's Authorized JavaScript origins and Authorized redirect URIs to include the tunnel URL.

Project Structure

agent-cockpit/
├── server.ts                 # Express server entry point (TypeScript, run via tsx)
├── src/
│   ├── types/index.ts        # Shared type definitions
│   ├── config/index.ts       # Environment configuration
│   ├── middleware/
│   │   ├── auth.ts           # OAuth strategies, login page, auth routes
│   │   ├── csrf.ts           # CSRF token generation and validation
│   │   └── security.ts       # Helmet CSP configuration
│   ├── routes/chat.ts        # All chat API routes
│   └── services/
│       ├── backends/
│       │   ├── base.ts           # Base adapter interface for CLI backends
│       │   ├── claudeCode.ts     # Claude Code CLI adapter
│       │   ├── kiro.ts           # Kiro CLI adapter (ACP protocol)
│       │   ├── toolUtils.ts      # Shared tool helpers across backends
│       │   └── registry.ts       # Backend registry (pluggable adapter system)
│       ├── chatService.ts    # Conversation CRUD, messages, sessions, workspaces
│       └── updateService.ts  # Self-update: version checking, git pull, PM2 restart
├── public/
│   ├── index.html            # HTML shell
│   ├── js/                   # Frontend ES modules (no build step)
│   └── styles.css            # CSS with light/dark themes
├── test/                     # Jest test suites
└── data/                     # Runtime data (gitignored)
    ├── chat/
    │   ├── workspaces/{hash}/  # Workspace-based conversation storage
    │   │   ├── index.json      # Conversations + session metadata
    │   │   └── {convId}/       # Session files per conversation
    │   ├── artifacts/          # Per-conversation uploaded files
    │   └── settings.json       # User settings
    └── sessions/               # Express session files

Testing

Tests use Jest and run with:

npm test

Tests cover ChatService CRUD/messaging/sessions, backend adapter system (registry, ClaudeCodeAdapter, KiroAdapter, tool utilities), chat route integration (streaming, reconnection, options passthrough), graceful shutdown (SIGINT/SIGTERM), session file-store persistence, draft state persistence, message queuing, and self-update service.

CI runs tests automatically on every pull request against main via GitHub Actions. Version bumps are automated on merge to main.

Backend-Specific Notes

Claude Code CLI

Agent Cockpit spawns Claude Code CLI processes on your behalf. To get the best experience, consider adding these settings to your ~/.claude/settings.json:

{
  "attribution": {
    "gitCommit": "",
    "pullRequest": ""
  },
  "permissions": {
    "allow": [
      "Edit(**)"
    ]
  }
}

• attribution.gitCommit: "" removes the Co-Authored-By: Claude trailer from git commits.
• attribution.pullRequest: "" removes the Claude attribution from pull request descriptions.
• permissions.allow: ["Edit(**)"] gives Claude Code permission to edit any file without prompting, useful since Agent Cockpit has no interactive terminal for approvals.

Kiro CLI

Kiro connects via ACP (Agent Client Protocol) — JSON-RPC 2.0 over stdin/stdout. The adapter handles:

• Lazy process spawning with idle timeout (configurable via KIRO_ACP_IDLE_TIMEOUT_MS)
• Automatic session creation, loading, and resume across server restarts
• Sub-agent tracking with grouped tool activity visualization
• Permission auto-approval for all tool calls

Ensure kiro-cli is installed and authenticated before selecting Kiro as a backend.

Adding a New Backend

Agent Cockpit's pluggable adapter system makes it straightforward to add new CLI backends:

1. Create src/services/backends/myBackend.ts extending BaseBackendAdapter
2. Implement metadata, sendMessage(), generateSummary(), and optionally generateTitle(), shutdown(), onSessionReset()
3. Import shared helpers from toolUtils.ts (never import from another adapter)
4. Register in server.ts — no other file changes needed

See SPEC.md for the full adapter contract and stream event protocol.

Roadmap

Agent Cockpit supports Claude Code and Kiro as its first two backends. As vendors release more CLI-based coding agents, Agent Cockpit will add adapters so you can use them all from a single interface while keeping your data portable.

Specification

See SPEC.md for a complete technical specification covering every API endpoint, data model, frontend behavior, security mechanism, and implementation detail.