agentpack-cli 0.3.12

Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs.

AgentPack

Status: alpha (v0.3.12). Works, tested, used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Public benchmark proof exists for the current suite, but broader repo coverage is still growing. API may change before 1.0.

Platform note: macOS, Linux, and Windows are supported. Windows support targets PowerShell plus Git for Windows. cmd.exe and bare Git setups are not a supported path yet.

Local context engine for AI coding agents.

AgentPack gives Claude Code, Codex, Cursor, Windsurf, Antigravity, CI jobs, and other agent workflows a better starting point. It analyzes your repo locally, finds the files most relevant to a task, and packages them into compact context packs for CLI and MCP workflows.

Use AgentPack when a repo is too large to paste and you want faster, more consistent context preparation before an agent starts working. It works offline and is a context preparation tool, not a coding agent.

Features

• Task-focused packing: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, repo history, and deterministic offline summaries.
• Budget-aware compression: emits full, diff, symbols, skeleton, or summary views instead of all-or-nothing file dumps.
• Rendered-token accounting: budgets against the actual markdown context, not only file payloads.
• Reserve buckets: changed files, tests, docs, and dependencies each get protected selection capacity so one dirty area cannot starve the others.
• Execution state: optional task state files and git-derived fallback status show whether work is planned, in progress, blocked, done, committed, or committed but not pushed.
• Thread-scoped context: explicit --thread <id> or --thread auto isolates task/context files for multiple agents in one repo and warns on same-branch file overlap.
• Task router: MCP and CLI surfaces route a task to relevant files, scoped rules, installed skills, suggested commands, and safety warnings without executing skills automatically.
• Agent integrations: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
• Local and measurable: no API calls for scan, summarize, rank, pack, stats, or benchmark; quality is measured with expected-file evals.

Benchmark Proof

Latest public release gate: 8 real commits from Pallets Click, ItsDangerous, and MarkupSafe, scored against files actually changed by each commit.

Metric	Result
Avg recall	79.2%
Avg token precision	51.2%
Pack p50	1,450 tokens
Pack p95	3,805 tokens

Full table: benchmarks/results/2026-05-27-public.md. This is public smoke proof, not a claim of universal ranking quality; expand cases for your own repo with agentpack benchmark capture.

Install

pipx install agentpack-cli
agentpack --version

Requires Python 3.10+. The PyPI package is agentpack-cli; the command is agentpack. Use pipx for normal installs because many macOS/Linux Python distributions block global pip install with PEP 668's externally-managed-environment error. If you prefer pip, install inside a virtual environment.

Install pipx first if needed:

# macOS
brew install pipx

# Ubuntu/Debian
sudo apt install pipx

# Fedora
sudo dnf install pipx

# Arch
sudo pacman -S python-pipx

pipx ensurepath

For JavaScript/TypeScript projects you can use the npm wrapper:

npx @vishal2612200/agentpack --version
npx @vishal2612200/agentpack init --yes
npx @vishal2612200/agentpack pack

Quickstart

cd your-repo
agentpack init --yes
agentpack work "fix auth token expiry"

Then read .agentpack/context.md or the agent-specific context file listed in the output. AgentPack also integrates with MCP so agents can call tools directly instead of reading markdown artifacts.

A good explicit workflow is:

agentpack task set "fix billing webhook retry handling in app/api/billing/route.ts" --guard
agentpack next --fix-all-safe
agentpack status
agentpack finish --since main

Use agentpack quickstart --task "..." --write when you want AgentPack to print the next commands and write the task file for you. Use agentpack start "..." --pack-only when you want only a fresh pack and not the guard path.

Agent Setup

AgentPack can install repo-local instructions and hooks for the coding agent you use. The installer is idempotent and merges with existing config where possible.

agentpack init --agent claude
agentpack init --agent codex
agentpack init --agent cursor
agentpack init --agent windsurf
agentpack init --agent antigravity
agentpack init --agent generic

What each integration writes:

Agent	Files
Claude Code	CLAUDE.md, .claude/settings.json, .mcp.json
Codex	AGENTS.md, .codex/hooks.json, git hooks
Cursor	.cursorrules, .cursor/rules/agentpack.mdc, .vscode/tasks.json, git hooks
Windsurf	.windsurfrules, .vscode/tasks.json, git hooks
Antigravity	GEMINI.md, .vscode/tasks.json, git hooks
Generic	no agent-specific files; use context.md directly

MCP-capable agents should prefer AgentPack MCP tools over reading markdown files directly. The markdown context files remain useful for manual review, CI, non-MCP agents, and logs.

Generated instructions keep thread mode explicit. They recommend AGENTPACK_THREAD_ID=<stable-id> agentpack ... --thread auto when you want scoped state, but plain installed hooks continue using global .agentpack/task.md and .agentpack/context.md.

Configuration Snapshot

agentpack init creates .agentpack/config.toml. Most projects can use the defaults:

[context]
default_mode = "balanced"
default_budget = 40000

[agents.generic]
output = ".agentpack/context.md"

Use .agentignore to remove generated output, vendored code, large exports, or files that repeatedly appear as ranking noise. AgentPack imports obvious generated/noisy entries from gitignore sources during init, but repository-specific outputs should still be added by hand.

Use scoring weights only after measuring a real miss:

agentpack benchmark --misses
agentpack explain --file path/to/missed_file.py
agentpack diagnose-selection
agentpack ignore suggest

Configuration detail: docs/configuration.md.

Common Workflows

Debug Selection

agentpack explain --task auto
agentpack explain --file src/auth/session.py
agentpack explain --omitted
agentpack stats
agentpack diagnose-selection

MCP-First Agent Flow

1. Call start_task(task) when a new task begins. AgentPack writes .agentpack/task.md, packs context, and returns ranked markdown.
2. Call get_context() when you need the latest pack. It blocks for one refresh if .agentpack/task.md or the repo snapshot changed since the last pack.
3. Use route_task(task) for a lightweight route: relevant files, rules, skills, commands, and safety warnings without writing a full context file.

Multiple Agent Threads

Plain agentpack pack, agentpack status, and agentpack guard keep legacy global behavior and ignore ambient host thread env vars. Use thread mode only when you explicitly ask for it:

agentpack pack --thread codex-local
AGENTPACK_THREAD_ID=codex-local agentpack pack --thread auto
agentpack threads --active
agentpack state show --thread codex-local

Thread mode writes under .agentpack/threads/<id>/ and appends .agentpack/thread_index.jsonl. Same-worktree, same-branch overlap is warning-only; separate worktrees or branches remain the safest workflow for concurrent edits.

Release Validation

agentpack dev-check
agentpack release-check
agentpack verify-wheel
agentpack release prepare
agentpack ci init

The Makefile remains maintainer convenience, but the CLI commands above are the package-user source of truth. agentpack benchmark --release-gate runs the public proof path: public repos, proved target files, misses, and public table output. --sample-fixtures remains a regression smoke path, not the release gate.

Commands

Command	Purpose
agentpack init --yes	Create local config and ignore files
agentpack work "task"	Initialize if needed, start task, refresh context, show next steps
agentpack start "task"	Write task and run the guard/refresh workflow
agentpack finish --since main	Diagnose, capture benchmark case, run checks, mark done
`agentpack task show	set
agentpack pack	Generate a ranked context pack for .agentpack/task.md
agentpack next --fix-all-safe	Ask AgentPack what command or safe repair should happen next
agentpack guard --repair-stale --refresh-context	Check freshness, repair stale rules, refresh context
agentpack status	Show context freshness and git/task state
agentpack stats	Show pack size, token savings, and top files
agentpack explain --task auto	Debug selected and omitted files
agentpack diagnose-selection	Turn latest pack/benchmark signals into concrete tuning actions
`agentpack ignore suggest	apply`
agentpack route --task "..."	Get lightweight task routing without a full context file
agentpack threads [--active] [--conflicts]	Inspect thread-scoped context state
`agentpack state show	set
agentpack benchmark capture --since <ref>	Add a benchmark case from changed files
agentpack benchmark --release-gate	Run public benchmark evidence path
agentpack dev-check	Run docs, lint, pytest, and npm wrapper checks
agentpack verify-wheel	Install built wheel in a temp venv and run benchmark gate
agentpack release-check	Run version, changelog, tests, build, and benchmark checks
agentpack release prepare	Run full release prep, public table, and wheel verification
agentpack ci init	Generate a GitHub Actions workflow for AgentPack checks

Full command reference: docs/commands.md.

Make Shortcuts

Run make help for the current list. The main targets are:

Target	Wraps
make test	pytest -q
make lint	python -m ruff check src tests
make npm-test	npm wrapper/version tests
make docs-check	README/docs link smoke + git diff --check
make benchmark	agentpack benchmark --release-gate --no-public-table
make benchmark-publish	agentpack benchmark --release-gate
make release-fast	agentpack release-check --skip-benchmark --skip-build
make release	agentpack release-check
make verify-wheel	build wheel, install in temp venv, run benchmark gate

make context uses legacy global context. For scoped context, run:

THREAD=codex-local make context-thread
AGENTPACK_THREAD_ID=codex-local make context-thread

Benchmark Proof

AgentPack is best treated as a ranked starting map. It should reduce repeated orientation work, but the agent and reviewer still own correctness.

Use real repo evals instead of trusting compression numbers:

agentpack benchmark --release-gate

Current public benchmark evidence is documented in benchmarks/README.md and the generated public table under benchmarks/results/.

What A Pack Contains

Rendered packs are meant to be readable by humans and directly useful to agents. A typical pack includes:

• freshness metadata with task source, generated time, git branch, SHA, and snapshot hash
• execution state with task status, checklist counts, git dirty/ahead/behind counts, and Docker/Compose availability
• concurrent-context warnings when another active thread overlaps files on the same branch and worktree
• token stats and largest token consumers
• semantic repo map grouped by subsystem
• selected-file table with include mode and reason
• compressed context receipts showing why files were included or excluded
• file context in full, diff, symbols, skeleton, or summary mode

The pack is a starting map. Agents should still verify the selected files against actual code before editing.

Local Files

AgentPack writes local artifacts under .agentpack/:

Path	Purpose
.agentpack/task.md	current global task summary
.agentpack/task_state.md	optional global execution state
.agentpack/context.md	generic/Codex/Cursor/Windsurf fallback context
.agentpack/context.claude.md	Claude-flavored fallback context
.agentpack/pack_metadata.json	freshness and pack metadata
.agentpack/cache/	offline file summaries keyed by hash
.agentpack/snapshots/	repo snapshot hashes
.agentpack/thread_index.jsonl	append-only thread activity index
.agentpack/threads/<id>/	scoped task, state, context, and metadata for explicit thread mode

Generated context, cache, snapshots, and thread state are local operational files. The root .agentpack/config.toml and .agentignore are usually worth committing; generated context artifacts usually are not.

Troubleshooting

If AgentPack selects too much:

agentpack diagnose-selection
agentpack stats
agentpack explain --omitted
agentpack explain --budget-plan
agentpack ignore suggest

If a required file is missing:

agentpack explain --file path/to/file.py
agentpack benchmark --misses
agentpack benchmark capture --since HEAD~1 --task "describe the task"

If context looks stale:

agentpack status --deep
agentpack guard --agent auto --repair-stale --refresh-context

If multiple agents are editing the same project:

agentpack threads --active
agentpack threads --conflicts
agentpack state show --thread codex-local

If package release checks fail:

agentpack release-check --json
agentpack release-check --skip-benchmark

Use the skip flags only for local iteration. The final release proof should include the build and public benchmark gate.

Documentation

• docs/architecture.md: pipeline, data flow, package layout, thread/execution state, rendered-budget accounting.
• docs/commands.md: full CLI command reference.
• docs/configuration.md: config, scoring weights, .agentignore, and git integration.
• docs/integrations.md: agent setup, MCP workflow, hooks, and native integration status.
• docs/benchmarking.md: quality bar, release gate, sample fixtures, and public artifacts.
• docs/development.md: local development, release checklist, naming/ranking, and contribution notes.
• docs/limitations.md: project scope, honest token framing, known limitations, and roadmap.

Limitations

• AgentPack prepares context; it does not edit code, run tests for the agent, or prove correctness.
• Ranking is deterministic and local, but it can still miss files. Use agentpack explain, agentpack benchmark --misses, and normal code review.
• Thread coordination is warning-based, not locking-based. It helps agents notice collisions but does not enforce ownership.
• Language support is strongest for Python and JavaScript/TypeScript. Other languages still benefit from filenames, git signals, and summaries.
• Token estimates are approximate, even with rendered-budget accounting. Treat them as operational guidance, not provider billing truth.

More detail: docs/limitations.md.

License

MIT