Agentpack is a local-first MCP server that keeps AI coding task state in .agentpack/ so agents and people can resume, hand off, and audit work across sessions and clients.
Resume task context: load_context / resume return a token-budgeted summary of the current Task Passport, git state, decisions, dead ends, source conclusions, next actions, and gate warnings.
Record durable knowledge: record_decision, record_dead_end, attach_evidence, and record_source store decisions, failed approaches, verification evidence, and file conclusions with content hashes.
Manage Task Passports: start, inspect, list, switch, park, update, set verification, and finalize tasks with write scopes and lifecycle rules.
Save and compare progress: checkpoint, diff, and replay capture session state and show what changed over time.
Audit continuity: task_audit and source_status check task risks, stale source conclusions, changed files, and missing files.
Hand off or port work: task_handoff creates a compact handoff; bundle_export, bundle_inspect, bundle_import_plan, and bundle_import move tasks between repos/machines.
Report usage locally: usage_report and usage_link link Codex/Claude Code transcripts to tasks and report token usage without collection or network calls.
Check release readiness: release_preflight reports local release metadata and manual prep steps without publishing.
Stay local: normal operation is local-only, with writes under .agentpack/ and secret-like values best-effort redacted.
Repo-native task continuity for AI coding agents.
Agent memory remembers how you work. Agentpack remembers where the task stands.
Your agent spent an hour on a task. It found the cause, rejected two approaches, and wrote down the next step. Then the context was compacted, or the chat closed. The next session starts from zero and does the same investigation again.
Agentpack keeps the task state in your repo. Connected agents record the goal, decisions, dead ends, verification evidence, and checkpoints in .agentpack/ while they work. Then the next session loads that state and continues: the same agent after compaction, a different client, or you next week.
Here it is in action. In session 1, an agent works on a flaky test and records a decision, a dead end, and a checkpoint through the Agentpack MCP tools. In session 2, the next day with an empty context, one load_context call brings the task back:
▶ Watch the 80-second explainer, with sound
To try the same flow by hand from the CLI, see docs/DEMOS.md.
Local-first. Plain files in your repo. No cloud, no telemetry, no network calls.
Made for agents. A local MCP server and generated project instructions (AGENTS.md, CLAUDE.md, Cursor rules) tell agents when to load and record state.
Open to people. The CLI shows the same state, so you can inspect it, fix it, or hand it off yourself.
Claude Code memory, Codex memories, and CLAUDE.md or AGENTS.md keep how to work: your preferences, project conventions, and facts that stay true. Agentpack keeps where the work is: the goal of the current task, its constraints, decisions, dead ends, next actions, and verification result.
Agent memory | Agentpack | |
Holds | Preferences, conventions, long-lived facts | The state of one task |
Lives in | The profile or account of one client |
|
Read by | That client only | Any MCP client: Claude Code, Codex, Cursor, Claude Desktop |
Shape | Free-form notes, recalled by relevance | A Task Passport per task: goal, lifecycle, the paths it may change, and verification bound to a commit |
Staleness | Not tied to file changes | Notes about files store the file hash, so Agentpack flags a note when its file changes |
Use both. Memory keeps how you like to work. Agentpack keeps what the task needs next.
Related MCP server: MCP Starter
Agentpack needs Node.js 20 or later.
npm install -g agentpack-cli
cd path/to/your/repo
agentpack init # once per repo
agentpack install claude --write # per client: codex | claude | cursor | claude-desktop
agentpack install git-hooks --write # optional: task gate check before each commitRestart or reconnect your coding agent, and approve the Agentpack server or hooks when the client asks. From then on, the agent loads the task state when a session starts, records decisions and evidence while it works, and creates checkpoints at meaningful points.
To check the setup, run agentpack doctor. To see the task state yourself, run agentpack resume --preset agent --query "<topic>".
In a Git repository, init adds the local Agentpack files to .git/info/exclude. The list includes .agentpack/, .mcp.json, .claude, .codex, .cursor, AGENTS.md, and CLAUDE.md. Agentpack does not change your .gitignore. Files that Git already tracks stay tracked.
For each client, docs/INTEGRATIONS.md shows what the installer writes and why.
When a session starts, the agent loads a compact summary: the current Task Passport, recent checkpoints, decisions, and source conclusions.
While it works, the agent records what is worth keeping: decisions, failed approaches, and verification evidence. It can also record a source conclusion: a short note about what a file does, stored with the file hash. If the file changes later, Agentpack flags the conclusion. A matching hash shows that the file is unchanged, not that the conclusion is correct.
At a natural stop, the agent creates a checkpoint with the status, the next actions, and the Git state.
The next session, in any MCP client, continues from that state. It does not rebuild the task from chat history.
Each task has a Task Passport: the goal, status, constraints, write scope (the paths the task may change), next actions, and verification. You can start, park, switch, and finalize tasks, so each handoff is explicit.
The task gate checks edits against the current Passport. The client installers add native hooks for Claude Code, Codex, and Cursor. install git-hooks adds a pre-commit check. By default, the gate only warns. Set "gateMode" in .agentpack/config.json to "block" to stop edits outside the write scope or outside an active task, or to "off" to turn the gate off. Hooks are a guardrail, not a sandbox. See docs/CLI.md.
The summary stays inside a token budget. The agent gets the useful state back, not the full history.
Task bundles. Export a task to one JSON file, and import it in a fresh clone or on another machine. See docs/TASK-PASSPORT.md.
Tasks across repositories. One Passport can cover changes in several repositories, each with its own write scope.
Monorepo focus. Give each part of a monorepo (api/, frontend/, cron/) short tasks with their own write scope. The task gate warns when the agent leaves that part.
Usage reports. agentpack usage report reads local Claude Code and Codex transcripts and shows the token use of a task, including the Agentpack share. Nothing leaves your machine.
Read-only inspector. agentpack tui shows tasks, evidence, and checkpoints in the terminal. See docs/TUI.md.
Builder subagent. Codex, Claude Code, and Cursor installs include an optional builder for larger implementation work. The main agent says what it will hand off before it uses the builder. Small tasks stay with the main agent.
The context is compacted in the middle of a task, and the next turn needs the state back.
You start a new chat on a task that is still open.
You change between Claude Code, Cursor, Codex, or another MCP client.
You come back to a refactor or a bug fix days later.
Another agent continues from your checkpoint.
Agentpack context also uses tokens. The compact output keeps the task state available without the full ledger history.
Zero runtime dependencies, exact dev dependencies, a committed lockfile, and ignore-scripts=true.
No telemetry and no network calls in normal CLI or MCP operation.
Best-effort redaction of values that look like secrets in stored context and handoff output.
GitHub Actions publishes each release with npm provenance (Trusted Publisher, no long-lived tokens). To verify, run npm audit signatures.
See SECURITY.md for the full policy, including what Agentpack reads outside the repo.
docs/INTEGRATIONS.md: setup for Codex, Claude Code, Cursor, Claude Desktop, and Git hooks
docs/TASK-PASSPORT.md: task lifecycle, handoffs, additional repositories, and task bundles
docs/CLI.md: full CLI reference, budgets, and manual workflows
docs/MCP.md: MCP server contract and tools
docs/DEMOS.md: short continuity demos to run yourself
docs/TUI.md: the read-only terminal inspector
docs/LEDGER-HYGIENE.md: keep the ledger small and useful
Clone the repo and use Node.js 20 or later:
npm ci --ignore-scripts
npm test
npm run mcp:smoke
node dist/src/agentpack.js --helpSee docs/SETUP.md for the development setup and docs/RELEASING.md for the release steps.
Mirror: Codeberg. Issues, releases, and npm provenance stay on GitHub.
Store verification output (test results, command output, review findings, notes, or links) as a file under .agentpack/evidence/ plus a ledger event, returning an evidence id to reference from task_update_verification, task_finalize, or record_decision. Call for meaningful verification worth preserving; for small tasks prefer one aggregated evidence item over many per-command items. Provide the body inline via content or from a file via path.
Inputs: kind, path, command, content, +1 more.
Export one Task Passport, compact handoff, latest task checkpoint when available, selected source conclusions, and optionally referenced evidence to a redacted agentpack.task-bundle JSON file. Writes only the new bundle file at outputPath; pack state is unchanged.
Inputs: outputPath (required), taskId, sources, includeEvidence.
Import a task bundle into this pack. By default it only returns the read-only import plan; nothing is written unless write is true. A write import runs under a pack lock, creates a parked task with local verification reset to unknown, retains the bundle and an import manifest, and never changes the current-task pointer. Inspect or plan untrusted bundles first.
Inputs: path (required), json, asNew, write.
Plan a task bundle import against this pack without writing anything: returns create, idempotent, or conflict actions with an explicit read-only guarantee. Call to preview exactly what bundle_import with write: true would do.
Inputs: path (required), json, asNew.
Validate and summarize an untrusted task bundle file: schema and digest status, origin, included records, and warnings. Read-only — never writes pack state. Call before planning or applying an import of a bundle you did not produce.
Inputs: path (required), json.
Save a durable progress checkpoint under .agentpack/checkpoints, capturing summary, git state (branch, commit, diff) and the current task id when that task is active, blocked or verifying, and updating the pack-level status and next actions that seed the next session's load_context. Call after meaningful progress, before ending a session, or before risky changes — not after every small step.
Inputs: status, summary, nextActions.
Compare two checkpoints, showing their summaries, status lines, and git refs side by side. Defaults to comparing the previous checkpoint against the latest. Call to see what changed between sessions. Read-only.
Inputs: to, from.
Load a token-budgeted markdown resume of Agentpack state for the current task: Task Passport status and next actions, git state, query-relevant decisions, dead ends, and source conclusions, plus gate warnings when the task lifecycle needs attention. Call once at the start of a session or task, before reading code; re-call only for a different query or budget. Read-only.
Inputs: query, budget, preset.
Record an approach that failed so future agents do not repeat it. Call when an attempted direction is abandoned for a durable reason, not for ordinary debugging iterations. Writes one event under .agentpack/; secret-like values are redacted.
Inputs: text (required), files, reason.
Append a durable technical or product decision to the Agentpack ledger so future sessions inherit it. Call for decisions that matter beyond this session (architecture, contracts, tradeoffs), not for routine preferences or per-edit narration. Writes one event under .agentpack/; secret-like values are redacted.
Inputs: text (required), files, evidence.
Record a durable conclusion about a source file in the Source Cache: stores the file's current content hash with your summary so future sessions can reuse the conclusion until the file changes. Call after inspecting an important file when the conclusion is reusable; do not record every file read, and re-record only when the conclusion itself changed. Writes under .agentpack/.
Inputs: path (required), snippet, summary.
Report local release readiness: release metadata, Trusted Publisher wiring, and the manual release-prep commands. Read-only — never pushes, tags, publishes, or creates GitHub Releases. Call when preparing a release, not during routine work.
Inputs: no named parameters.
Print a chronological timeline of recent Agentpack ledger events (decisions, dead ends, evidence, source records, checkpoints, task events), one line per event with timestamp and type. Call to audit how the task history unfolded when a resume is not enough; not part of the routine load_context/checkpoint loop. Read-only.
Inputs: limit.
Generate the same token-budgeted markdown resume as load_context: Task Passport state, git state, query-relevant records, and gate warnings. Prefer load_context at task start; use resume for ad-hoc re-reads with a different query or budget mid-session. Read-only.
Inputs: query, budget, preset.
Check whether recorded source conclusions are unchanged, changed, or missing by re-hashing the files; use changed/missing filters for stale source-cache triage. Call when you need a full stale-source check beyond what load_context already showed; do not repeat it when a recent load_context, task_audit, or status check answered the question. Read-only.
Inputs: json, changed, missing.
Audit the current Task Passport for continuity risks and advisory-only risk-proportional adversarial-verification evidence (a concise verification note or test output at low risk; independent read-only review and a named disconfirming check at medium/high risk). It does not judge semantic correctness or block lifecycle actions. Call before finalizing, after a long gap, or when drift is suspected; skip when a recent audit already answered it. Read-only.
Inputs: json.
Close the current Task Passport. Requires verification to already be passed, failed, or accepted, or that final status passed explicitly via status. Use task_park for deferred work instead of closing it; accepted finalization with remaining next actions requires force. Returns non-blocking hygiene and adversarial-verification advisories only; it never judges semantic correctness or blocks completion.
Inputs: force, status, summary, evidence.
Generate a compact handoff for the current Task Passport — objective, constraints, write scope, next actions, verification, latest task checkpoint when available, drift, and audit summary — so another chat, client, worktree, or agent can continue the work. Call before switching contexts. Read-only.
Inputs: no named parameters.
Find Task Passport ids or inspect task history. Without status lists open tasks; pass all: true for full history. compact and limit shorten the result. Filters combine with AND; current task is marked with an asterisk. Read-only.
Inputs: all, json, open, limit, +3 more.
Mark the current Task Passport parked so unrelated work can start without finalizing it. Use for intentionally deferred work: parking preserves verification state and the task can be resumed later with task_switch. Do not park to skip verification of finished work; use task_finalize to close it instead.
Inputs: no named parameters.
Create a new Task Passport and make it current, persisting it under .agentpack/. Call when starting a coherent phase of work and no task is active; it refuses to replace an active, blocked, or verifying current task — park or finalize that task first. Declare writeScope so the task gate can protect the task's boundaries.
Inputs: title (required), risk, tags, objective, +4 more.
Print a compact current-task state line by default; pass full: true for the detailed current view, or id to inspect a selected Passport with objective, constraints, all next actions and verification without switching tasks. Gate warnings always concern the actual current task. No source-cache scan; use task_audit for the full continuity audit. Read-only.
Inputs: id, full.
Make another open Task Passport current by id. Set parkCurrent: true to park a different active/blocked/verifying current task in the same locked transaction, after validating the target. Otherwise park or finalize it first. A parked target with pending or unknown verification resumes as active; a parked target with a final verdict resumes as verifying and stays frozen until verification returns to pending. Closed targets cannot be switched to.
Inputs: id (required), parkCurrent.
Patch the current Task Passport without changing lifecycle status. List fields (constraints, writeScope, nextActions, tags) append and deduplicate; repositories upsert by id; omitted fields are preserved; empty or no-op updates fail. Pass clearNextActions to replace the next-actions list instead of appending, e.g. to clear a stale plan before finalizing. Pass replaceConstraints to replace constraints that are obsolete or superseded; removed constraints stay in the task history.
Inputs: risk, tags, objective, writeScope, +5 more.
Update the current Task Passport verification state. A final verdict (passed, failed, or accepted) moves the task lifecycle to verifying; pending or unknown returns it to active. Call after attach_evidence so the verdict is evidence-backed; identical repeated calls are no-ops.
Inputs: status, summary, evidence.
Link Codex/Claude Code session transcripts to a Task Passport so usage_report can report the task by id. Without pick, file, remove or coverage it only lists candidate sessions of the task worktree with requests while the task was current. Show candidates to the user and link only what they confirm: pick links sessions by session id (numbers can shift between calls); client/file/turns links an explicit one. Re-linking a file replaces its selection; remove unlinks a linked file by path or session id (traced sessions are always included). Writes .agentpack/usage/.json only.
Inputs: file, json, note, pick, +6 more.
Report local Codex/Claude Code usage when the user asks about work usage. Pass task (Task Passport id; omit for the current task) to report the sources linked to it; sessions that ran Agentpack for the task (and their subagents) are included automatically; if none are traced or linked, the result lists candidate sessions of the task worktree to link with usage_link. Task reports count only requests made while the task was the current Passport; a subagent counts whole for the task current when it started. Alternatively supply manifest, or client/files for a direct report. Same read-only report as CLI usage report; no collection, rates or ledger writes. Includes estimated Agentpack call overhead, not schema cost or billing. Optional byTurn shows boundaries and turns selects N, N: or N:M in one file. Monetary snapshots are source-session estimates, unavailable for filtered ranges. Supported clients: Codex and Claude Code.
Inputs: to, from, json, task, +5 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 27 tools
Several clusters overlap: load_context and resume are explicitly described as producing the same markdown resume, and task_status, task_audit, and load_context all surface task state with only subtle differences in scope. Likewise bundle_inspect, bundle_import_plan, and bundle_import form a three-way cluster where the read-only vs write distinction must be inferred. The descriptions do include usage guidance ("prefer load_context at task start"), so an attentive agent can separate them, but the boundaries are not self-evident.
Strong noun-prefix grouping with a verb/target pattern: task_* (start, update, list, finalize, park, switch, status, audit, handoff, update_verification), bundle_* (export, inspect, import, import_plan), record_* (decision, dead_end, source), usage_* (report, link). Minor deviations are the bare single-word tools checkpoint, resume, diff, and replay, which break the pattern, plus record_source sitting outside the task_* family. Predictable overall.
At 27 tools the surface is heavy, sitting just over the point where a set becomes hard to scan, and it spans several sub-domains (task lifecycle, ledger records, bundles, usage analytics, release preflight). Niche tools like diff, replay, and release_preflight are defensible but add sprawl. The core of the server is well-scoped; the peripheral features are what push it over.
Lifecycle coverage is excellent: task start/update/verify/finalize/park/switch/list/status/audit/handoff plus checkpoints, resume, and replay cover the full working loop, and bundle export/inspect/plan/import covers the transfer loop symmetrically. The notable gap is that nothing can delete, forget, or prune durable state — no way to remove a stale decision, dead end, evidence item, or task — leaving cleanup as a dead end. There is also no configuration or initialization tool.
MCP server for agentverse documentation, generated by doc2mcp.
LLM Orchestration Agent (Mcp)
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
