chutingyean/Agent-Cockpit

What it does

Agent Cockpit is a local whiteboard plus an MCP server for AI research agents. Any MCP-capable agent such as Claude Code, Codex, Cursor or Gemini CLI writes its plan, tasks, experiment runs, claims and the code each run depended on to the same board.

The central idea is an evidence chain. A claim must cite a value that a recorded run actually wrote, and each run stores hashes of its script, the files it depends on and the functions it reaches. If any of those change, the run goes stale and dependent claims are flagged for recheck; reverting the change restores validity because the comparison is by content hash, not timestamp. A deterministic engine performs these checks without LLM calls.

The project targets researchers and agent users who want to know which results still hold and why, without reading every line of generated code.

Quick start

The demo requires Node.js 22.13+, git and python3. From a clone:

git clone https://github.com/chutingyean/Agent-Cockpit.git
cd Agent-Cockpit
npm install
npm run demo
node bin/cockpit.mjs serve --repo demo/research

The board should then be available at http://127.0.0.1:4180. In a second terminal, break and restore the demo to see the effect:

node bin/cockpit.mjs demo --break
node bin/cockpit.mjs demo --restore

--break quietly loosens the grader's answer matching without reporting it; dependent claims turn red. --restore puts the change back and the claims recover.

Using it on your own repo

The target must be a git repository. From inside it:

node /path/to/Agent-Cockpit/bin/cockpit.mjs init
node /path/to/Agent-Cockpit/bin/cockpit.mjs serve
node /path/to/Agent-Cockpit/bin/cockpit.mjs run -- python3 train.py --lr 1e-3

init writes MCP configs, AGENTS.md, a Stop hook and a pre-commit hook inside the target repo only. Agents read AGENTS.md and the MCP config; the tutorial walks through each agent step. npm link adds a global cockpit command as an alternative to node bin/cockpit.mjs.

How it fits together

Every write from MCP, the CLI or the board goes through one validator, and rejected writes are logged. Unreported file changes block git commit, and Claude Code cannot end its turn until it reports them. Human decisions are requested through cockpit_decide; when a change breaks claims, the cockpit raises a decision and writes an evidence brief. All state is event-sourced in .cockpit/events.jsonl, which is the single source of truth and should be committed, enabling replay at any moment.

MCP tools include cockpit_overview, cockpit_plan, cockpit_stage, cockpit_run, cockpit_claim, cockpit_hypothesis, cockpit_premise, cockpit_decide, cockpit_report and cockpit_review, plus canvas tools such as canvas_structure for code graph and impact analysis (tool table). A built-in rule-based reviewer and lightweight code graph work without extras; installing graphify or open-code-review makes them used automatically.

Constraints

• Node.js 22.13+ is required for the built-in node:sqlite; git is needed for the repo and hook integration, and python3 for the demo project.
• The board binds to 127.0.0.1; every check is a plain rule with no LLM calls and no token usage.
• The project is licensed AGPL-3.0-or-later: if you modify it and let others use it over a network, you must offer them your modified source. Third-party components keep their own licenses.
• Function-level staleness precision is described for Python dependencies; changes to reachable functions, imports or module-level code invalidate a run.

HotRepo's take

Agent Cockpit entered HotRepo's new-project JavaScript list on 2026-11-02 with 49 stars gained over a window from 2026-11-01 18:45 UTC to 2026-11-02 18:45 UTC, against 4 forks gained in the same window. Over the collected hourly samples it rose from 100 stars on 2026-10-31 to 180 by the end of 2026-11-02, with a visible acceleration in the final hours of that period. No best all-language daily rank was recorded and no discussion threads were captured, so the available evidence supports only this growth observation rather than a broader popularity claim. The combination of event-sourced state, hash-based staleness checks and an MCP interface is the concrete basis for judging whether it fits an agent-driven research workflow.