Agent-Cockpit

Agent Cockpit is a local whiteboard plus an MCP server for AI agents that do research. Any agent that speaks MCP (Claude Code, Codex, Cursor, Gemini CLI, …) draws its work onto the same board: the plan, the tasks, every experiment run, every claim, and the code each run depended on. A deterministic engine keeps checking the whole evidence chain. When any link changes, the cards that depend on it turn red. You can tell which results still hold, and why, without reading the code.

Why

After a few days of research with AI agents, the same things keep going wrong:

• Claims lose their footing silently. An agent edits the grader, the data pipeline or a statistics helper, and results that were "verified" no longer hold. Nobody notices.
• Changes go unreported. Files change and no agent says so, or an agent says it changed something it didn't.
• Decisions pile up, assumptions harden, loops spin. Questions meant for a human wait unanswered, untested premises become foundations, and an agent keeps tweaking hyperparameters "one more time".
• The code grows faster than you can read it.

Agent Cockpit turns these into rules a machine can check, and shows the result on one board.

Features

• Evidence chains, down to a JSON field. A claim must cite a value that a recorded run actually wrote. Each run records the hash of its script, of every file the script depends on, and of each function it reaches. If any of those changes, the run goes stale and every claim built on it is flagged for recheck. Revert the change and the hashes match again, so the claims recover.
• Works with any MCP agent. Agent identity comes from the MCP handshake. cockpit init writes the config for Claude Code, Cursor, VS Code and Gemini CLI, and prints the command for Codex.
• One write gate. Every write from MCP, the CLI or the board passes through the same validator. Non-compliant writes are rejected with a reason the agent can act on. Rejections are logged too.
• Unreported changes get caught. Real file changes are detected whether or not an agent reports them. Unreported changes block git commit, and Claude Code cannot end its turn until it reports them.
• Built-in code graph and code review, no extra installs. A lightweight graphify-style call graph supplies dependency closures, communities, core nodes and impact analysis. A rule-based reviewer looks at the changed lines every time a file changes. Install the real graphify or open-code-review and they are used automatically.
• Human decisions in the loop. Agents ask through cockpit_decide and wait. When a change breaks claims, the cockpit raises a decision itself and writes a one-page evidence brief, laid out by answer-me-with-html.
• Replay. Everything is an append-only event, so you can scrub or play the board back to any moment. A brief stays available even after the problem is fixed.
• Local and deterministic. The board binds to 127.0.0.1. Every check is a plain rule, with no LLM calls and zero tokens.

Quick start

Requires Node.js 22.13+ (for the built-in node:sqlite), git, and python3 for the demo project.

git clone https://github.com/chutingyean/Agent-Cockpit.git
cd Agent-Cockpit
npm install
npm run demo                                       # build a demo research repo: 6 real runs, 6 claims
node bin/cockpit.mjs serve --repo demo/research    # open http://127.0.0.1:4180

Then, in a second terminal, break something and watch the board:

node bin/cockpit.mjs demo --break      # quietly loosens the grader's answer matching, unreported
node bin/cockpit.mjs demo --restore    # put it back: hashes match, claims recover

Use it on your own research repo

No clone needed:

cd /path/to/your-research                                   # must be a git repo
npx -y @tingyen/agent-cockpit init                      # MCP configs, AGENTS.md, Stop hook, pre-commit
npx -y @tingyen/agent-cockpit serve                     # the board
npx -y @tingyen/agent-cockpit run -- python3 train.py   # run experiments through the cockpit

Prefer a permanent cockpit command? npm install -g @tingyen/agent-cockpit.

init only writes inside your repo. Open the repo in your agent and it reads AGENTS.md and the MCP config. The tutorial walks through every agent step by step.

Claude Code plugin. Adds a skill that teaches Claude when and how to use Agent Cockpit, including how to set it up:

claude plugin marketplace add chutingyean/Agent-Cockpit
claude plugin install agent-cockpit@agent-cockpit

The same skill lives in skills/agent-cockpit/SKILL.md for other agents that read SKILL.md files. The MCP server is also listed in the MCP Registry as io.github.chutingyean/agent-cockpit.

How it works

• Content hashes, not timestamps. Staleness is decided by comparing hashes, so reverting a file restores validity exactly.
• Function-level precision. For Python dependencies, a change to a function the run never reaches does not make the run stale. Changes to reachable functions, imports or module-level code always do.
• Event sourcing. .cockpit/events.jsonl is the single source of truth, and it doubles as the agents' work log. Commit it. The board is a pure projection (reduce → derive), which makes replay possible.

MCP tools

Research tools	Purpose
cockpit_overview	Call first: pending decisions, claims needing recheck and why, unreported changes
cockpit_plan / cockpit_stage	The research path. A stage cannot close until its required tools have been called
cockpit_task	The agent's own task card, updated every round (what, why, next)
cockpit_run	Run an experiment and record it
cockpit_claim	Register a claim. Evidence must be a file and field written by a recorded run
cockpit_hypothesis / cockpit_premise	Hypotheses and not-yet-verified premises
cockpit_decide / cockpit_decisions	Ask a human; read the answers
cockpit_report	Report which files changed
cockpit_review	Code review: ocr if installed, otherwise built-in rules; or report your own findings

Canvas tools: canvas_list, canvas_read, canvas_search, canvas_createNode, canvas_link, canvas_diagram (architecture diagrams in md²'s format) and canvas_structure (code graph and impact analysis).

CLI

npm install -g @tingyen/agent-cockpit gives you a global cockpit command. Otherwise use npx -y @tingyen/agent-cockpit <command>, or node bin/cockpit.mjs from a clone.

Command	Purpose
cockpit init	Write MCP configs, rules files, the Stop hook and the pre-commit hook
cockpit serve [--port 4180]	Open the board
cockpit run -- <command>	Run and record an experiment
cockpit graph	Rebuild the code graph (graphify if installed)
cockpit review [--all]	Code review (ocr if installed; changed lines by default)
cockpit status / cockpit check	Print the cockpit summary / list unreported changes
cockpit demo [--break|--restore|--fresh]	The demo project

Every command accepts --repo <path>; the default is the current directory.

Project layout

bin/cockpit.mjs      CLI
src/engine.mjs       reduce and derive: evidence chains, propagation rules, tours, brief drafts
src/gate.mjs         the single write gate
src/store.mjs        event store (node:sqlite) and canvas projection
src/run.mjs          cockpit run
src/graph.mjs        built-in code graph (graphify-compatible output)
src/review.mjs       built-in rule-based code review
src/mcp.mjs          MCP server
src/server.mjs       board server (SSE, decisions, briefs, replay)
web/board.html       the board (no framework, no build step)
demo/template/       demo research project (Python, really runs)
skills/              SKILL.md that teaches agents to work under Agent Cockpit
.claude-plugin/      Claude Code plugin and marketplace manifests
server.json          MCP Registry metadata
docs/                tutorial, figures, screenshots, a recorded real session
test/                node:test suite (npm test)

Documentation

• Tutorial: from the demo to your own project, every agent, replay, and a recorded real session
• Recorded session: the events, the code the agents wrote, and their output

Acknowledgements

Agent Cockpit fuses ideas from six projects into one evidence graph: research-cockpit (claims, hypotheses, premises, decisions), graphify (code graph), open-code-review (code review), Understand-Anything (summaries, layers, tours, personas), md² (architecture diagram format) and answer-me-with-html (one-page briefs). See THIRD_PARTY_NOTICES.md for what is bundled and under which license.

License

Copyright (C) 2026 chutingyean

Agent Cockpit is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. If you modify it and let others use it over a network, you must offer them the source code of your version. Third-party components keep their own licenses; see THIRD_PARTY_NOTICES.md.