AgentPlane

May 14, 2026 · View on GitHub

AgentPlane latest release header

AgentPlane

Git-native infrastructure for traceable AI work.

AgentPlane turns Claude Code, Codex, Cursor, Aider, and other coding-agent changes into reviewable Git evidence: task intent, approved plan, verification, finish state, and Agent Change Record.

task -> plan -> approve -> implement -> verify -> finish

The review trail for AI work, inside Git.

Use any coding agent. Keep the review trail in your repository.

Install

npm i -g agentplane
agentplane init
agentplane quickstart

Requirements: Node.js 24+, Git, and a local terminal.

AgentPlane CLI demo

AgentPlane intentionally enables GitHub issue prompts for internal AgentPlane errors by default. This helps us speed up framework development: when AgentPlane itself fails, the CLI can suggest a privacy-bounded issue payload for the basilisk-labs/agentplane repository.

Preview the payload before creating anything:

agentplane insights issue --error-code E_INTERNAL --dry-run

If you do not want this mode, ask your agent to disable feedback issue prompts or run:

agentplane config set feedback.github_issues.enabled false

Why

A pull request shows what changed. It does not reliably show what the agent was asked to do, which plan constrained the change, which checks ran, or why the work is safe to merge.

AgentPlane records that missing evidence before it disappears into chat history, terminal scrollback, or IDE state.

What AgentPlane writes

agentplane init adds a local workflow surface:

AGENTS.md                         Repository policy gateway
.agentplane/WORKFLOW.md           Workflow contract
.agentplane/tasks/<task-id>/       Task state and evidence
.agentplane/tasks/<task-id>/acr.json
                                  Agent Change Record

Reviewers do not need to trust an agent transcript. They can inspect files, commits, checks, hashes, and the ACR.

Agent Change Record

ACR is a commit-safe JSON record for AI-authored work. It captures task intent, approved plan, Git commits, policy decisions, verification evidence, and merge readiness.

agentplane acr generate <task-id> --work-commit HEAD --write
agentplane acr validate <task-id> --mode local
agentplane acr check <task-id> --mode ci
agentplane acr explain <task-id>

Schema: schemas/acr-v0.1.schema.json.

Context management

AgentPlane also gives agents a repository-owned memory layer. Instead of asking an agent to rediscover project knowledge from raw files on every prompt, keep reusable context in Git and let AgentPlane project it into searchable local state.

context/raw/**              source material
context/wiki/**             maintained markdown wiki
context/facts/**/*.jsonl    sourced facts
context/graph/**/*.jsonl    entities and relationships
.agentplane/context/derived disposable generated projection

Initialize it with:

agentplane context init
agentplane context learn changes
agentplane context learn tasks --tag release --limit 20 --dry-run
agentplane context search "release checklist"
agentplane context check

The model matches the LLM Wiki pattern: raw sources stay immutable, the wiki accumulates synthesis, and schema/policy files tell agents how to maintain it. AgentPlane adds task lifecycle, provenance, proposal-before-promotion, and verification gates so context updates remain reviewable.

Read Local context.

First task flow

Create a task:

agentplane task new --title "Fix parser edge case" --description "Reject empty labels." --owner <agent-id> --tag code

Record the plan and approval:

agentplane task plan set <task-id> --text "Add a fixture, tighten validation, and run focused tests." --updated-by <agent-id>
agentplane task plan approve <task-id> --by <reviewer-id>

Then start, verify, and finish:

agentplane task start-ready <task-id> --author <agent-id> --body "Start: implementing parser validation with focused tests."
agentplane task verify-show <task-id>
agentplane verify <task-id> --ok --by <agent-id> --note "Focused parser tests passed."
agentplane finish <task-id> --author <agent-id> --result "Parser rejects empty labels." --commit <git-rev>

Agent IDs are configurable profiles. See Agents.

AgentPlane is not

Not another coding agent.
Not a prompt framework.
Not a replacement for Git, CI, or PR review.

It is the evidence layer around the tools you already use.

Why AgentPlane

Without AgentPlane	With AgentPlane
Prompt in chat history	Task intent recorded in the repo
Plan is implicit	Plan is explicit and can be approved
Verification is a claim	Verification is recorded with context
Reviewer reads one diff	Reviewer reads diff plus task record
Closure is manual	Finish state links to a commit
Workflow lives elsewhere	Workflow artifacts live in Git

vs. other tools

AgentPlane is not another coding agent. It is the workflow envelope around the agent you already use:

Claude Code, Codex, Cursor, and Aider generate or edit code; AgentPlane records the task trail.
AGENTS.md and CLAUDE.md are policy text; AgentPlane adds task state and CLI gates around it.
Git stores the final diff; AgentPlane stores the task, plan, verification, and closure evidence beside that diff.
Hosted agent dashboards centralize workflow state; AgentPlane keeps it local to the repository.

See the full comparison page in docs/compare.mdx.

Recipes

Recipes are optional signed behavior modules. Start with the task -> plan -> verify -> ACR flow first; add recipes only when you need reusable agent profiles, prompt modules, skills, scenario assets, or repository mapping.

agentplane recipes list-remote
agentplane recipes install code-map --refresh --yes

The current catalog starts with Code Map.

Who uses it

Solo developers who want future-you to know why an agent changed 19 files.
OSS maintainers who require agent-generated PRs to include task intent, plan, checks, and ACR.
Engineering teams that make agent work follow a shared lifecycle before review.
Platform and security teams that need local, inspectable, policy-aware, CI-gateable AI work.

DCO sign-off and multi-author commits are first-class. AgentPlane-managed commits preserve DCO identity fallbacks so agent and human co-authoring stays compliant.

Using AgentPlane in a real repo? Tell us in Discussions. We will add your story to docs/showcase.