Metadata-Version: 2.4
Name: agentpack-cli
Version: 0.4.1
Summary: Local context engine for AI coding agents that ranks relevant repo files and builds compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, MCP, and CI workflows.
Project-URL: Homepage, https://github.com/vishal2612200/agentpack
Project-URL: Documentation, https://vishal2612200.github.io/agentpack/
Project-URL: Repository, https://github.com/vishal2612200/agentpack
Project-URL: Issues, https://github.com/vishal2612200/agentpack/issues
Project-URL: Changelog, https://github.com/vishal2612200/agentpack/blob/main/CHANGELOG.md
License: AGPL-3.0-only
License-File: LICENSE
Keywords: ai,ai-agent,ai-coding-agents,antigravity,ci,claude-code,codex,coding-agent,context,context-engine,context-packing,context-router,cursor,developer-tools,llm,local-first,mcp,mcp-context-engine,packing,prompt-context,reduce-token-usage,repo-analysis,repo-context,repo-map,task-focused-context,windsurf
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: pathspec>=0.12.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: tree-sitter-language-pack>=0.7.4
Requires-Dist: tree-sitter>=0.23.2
Requires-Dist: typer>=0.12.0
Requires-Dist: watchdog>=4.0.0
Provides-Extra: all
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: tree-sitter-language-pack>=0.7.4; extra == 'all'
Requires-Dist: tree-sitter>=0.23.2; extra == 'all'
Requires-Dist: watchdog>=4.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: jsonschema>=4.20.0; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pillow>=10.0.0; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: tree-sitter
Provides-Extra: watch
Requires-Dist: watchdog>=4.0.0; extra == 'watch'
Description-Content-Type: text/markdown
# AgentPack
Make AI coding work easier to understand, verify, and continue.
AgentPack is the local, agent-neutral reliability layer for AI software development.
It gives the coding agents you already use task-aware project context, visible workflow state,
validation guidance, review evidence, and continuity across sessions.
Get started
·
Technical docs
task-aware context
workflow state
cited review
local memory
agent-neutral
One local project workspace connecting outcomes, initiatives, tasks, health, knowledge, and engineering evidence.
## The Missing Project Layer
AI coding models can generate code, but a software project is more than the
files in a repository. The work also depends on the current task, ownership
boundaries, project rules, prior decisions, expected tests, current changes,
and review state. Those details do not automatically follow work between
agents or sessions.
That gap matters because an agent can produce plausible code while starting
from stale task state, overlooking a nearby test, missing a local rule, or
continuing assumptions from an earlier session. More model capability does not
by itself make the surrounding project evidence consistent or inspectable.
AgentPack keeps that evidence in one local system and presents a task-relevant
view around the agent you choose. It prepares context, tracks workflow state,
exposes validation and review evidence, and carries structured handoffs
forward. It is not a coding agent, a hosted context index, or a correctness
oracle.
## One Product Across the Workflow
AgentPack connects the work before an edit, while it is active, during review,
and when another session needs to continue it. These are not separate products
or isolated command families. They share the same local repository, task,
session, context, evidence, and memory state.
Normal development uses one four-command loop:
```bash
agentpack work ""
agentpack learn --json
agentpack finish
agentpack doctor
```
`learn` turns the same local work, project, and assessment memory into up to
three evidence-backed topics: what matters now, how the system fits together,
and a scored weak spot when one exists. `--global` explicitly ranks topics
across registered AgentPack projects; the coding-agent host teaches the chosen
topic and records the developer's result locally.
### Prepare with project evidence
AgentPack starts from a concrete task and the repository as it exists now. It
ranks likely relevant files and tests, applies repository rules and matching
skills, surfaces useful commands and warnings, and maps semantic relationships
where language support is available.
Selection receipts explain why files were included or omitted. Token guidance
keeps the starting context bounded, while targeted retrieval lets an agent ask
for more evidence when the initial map is not enough. The result is an
inspectable starting point, not a guarantee that every selected file is right.
### Coordinate active work
Task and session state, context freshness, token guidance, and same-worktree
overlap warnings stay connected. The local dashboard makes the project the
primary object: user-owned outcomes lead to confirmed initiatives, tasks, and
bounded evidence. Independent Delivery, Validation, Architecture, Release,
Context, and Knowledge signals keep missing evidence visible as unknown rather
than hiding it inside a composite score.
Summary and Engineering lenses present the same local project state for
different audiences. Deterministic status briefs can be copied or downloaded
without writing repository files, and project reads can aggregate accessible
worktrees while mutations stay scoped to the current one.
Overview leads with an evidence-ranked Now section. The five stable project
views are Overview, Roadmap, Work, Health, and Knowledge; Activity and advanced
repository tools remain available from Overview, Explore, and the `Cmd+K` /
`Ctrl+K` command palette. A redacted seven-day browser snapshot provides a
read-only last-known project status when the local server is unavailable.
Structured handoffs carry acceptance criteria, completed and remaining work,
decisions, blockers, changed files, and validation evidence into another
supported session. A handoff transfers bounded project state; it does not
pretend to recreate the original host conversation.
### Verify with source-backed evidence
AgentPack links context to focused validation guidance and review evidence. Its
staged PR review separates repository understanding, candidate findings,
criticism, and publishing so unsupported findings can be rejected before they
become inline comments.
The PR comment resolution workflow follows a validate, plan, fix, verify, and
reply loop. Plans and replies require source citations, validation status, and
the current PR head, making it harder to close a comment with an unsupported
claim or stale location.
### Continue without turning memory into truth
AgentPack records local task events, episodes, reusable procedures, learning
feedback, and observer signals. Those records can explain why a file was
selected, suggest relevant prior work, or surface repeated weak spots in the
dashboard.
Skill review extends the same reliability approach to agent instructions. It
audits a skill and generates balanced trigger and non-trigger evaluation cases
so activation behavior can be checked instead of assumed.
AgentPack does not edit source code or replace the developer's chosen agent.
The agent still reads the code, makes the change, runs the checks, and exercises
judgment. AgentPack makes the surrounding project state explicit and
inspectable.
## How AgentPack Fits Around Existing Tools
AgentPack is a project layer around tools that already own important parts of
software delivery. It connects their evidence without claiming to replace
them.
| Existing surface | AgentPack's role |
|---|---|
| Coding agents | Prepare task-aware context, workflow state, and evidence for the agent that will reason and edit. |
| IDE and repository search | Provide a ranked starting map and related-file evidence; direct search remains available for verification and exploration. |
| Git, tests, and CI | Surface likely validation paths and record results; the underlying diff and test output remain authoritative. |
| Pull requests | Prepare cited review artifacts and comment-resolution evidence against an immutable base and head. |
| Team trackers | Carry local task and handoff context without replacing planning, ownership, approval, or governance systems. |
This separation is deliberate. AgentPack can improve how project evidence is
prepared and carried forward, but correctness still comes from source
inspection, testing, runtime behavior, and human or agent judgment.
## For Developers and Teams
### For developers
AgentPack gives an individual developer a concrete starting map, visible task
state, focused validation guidance, and a structured way to continue work in a
later session. It is especially useful when the repository is large enough
that orientation, ownership, and test discovery are part of the task.
The workflow remains compatible with normal engineering habits. Developers can
use direct search, inspect any source file, ignore an advisory suggestion, run
different checks, or stop using AgentPack for a task where the exact change is
already obvious.
### For technical leads and teams
Technical leads and teams can inspect consistent local task context, freshness,
overlap warnings, validation evidence, and cited review artifacts across
supported agent entry points. That makes the state around AI-assisted work more
visible without claiming that every host has the same integration depth.
AgentPack coordination is advisory. It does not assign people, enforce policy,
approve changes, or provide hard multi-agent locks. Existing ownership,
security, review, and release processes remain in control.
### Where it fits best
AgentPack is most useful when:
- a repository or monorepo has enough structure that file and test discovery are non-trivial;
- work moves between multiple agent sessions or supported hosts;
- local rules and reusable skills should follow the task;
- PR review needs reproducible understanding, citations, and validation evidence;
- teams want local continuity without uploading the repository to a hosted index.
For a tiny repository, a one-shot read-only question, or a task where the exact
files are already known, AgentPack can remain a light preflight or stay out of
the way.
## Works With Existing Agents
AgentPack supports Codex, Claude Code, Cursor, Windsurf, Antigravity, MCP
clients, CI, and generic Markdown workflows. Integration depth varies by host;
each surface is an entry point into the same local CLI and MCP engine rather
than a separate product.
| Entry point | Product role |
|---|---|
| MCP-capable agents | Pull readiness, current context, deltas, related files, task maps, and cited PR evidence as needed. |
| Agent rules and hooks | Keep task setup, freshness checks, and repository guidance near the host workflow. |
| Local CLI | Own setup, diagnostics, explicit workflows, CI integration, and human inspection. |
| Dashboard | Present repository state, active work, proof, semantic relationships, memory influence, and handoffs visually. |
| Markdown artifacts | Provide a portable, auditable fallback for non-MCP agents, CI logs, and manual review. |
See [integrations](docs/integrations.md) for setup, capabilities, and explicit
advisory-versus-enforced status by host. Plugin and IDE surfaces remain thin
entry points into AgentPack rather than independent implementations of context
or review logic.
## Evidence Through Review
A reliability layer should expose why it made a recommendation and what proved
the resulting change. AgentPack keeps evidence visible at several points:
- selection receipts record why context candidates were included or omitted;
- freshness metadata ties context to the active task and repository snapshot;
- citation manifests connect packed claims to source locations and hashes;
- review artifacts keep understanding, findings, criticism, and approved output separate;
- resolution artifacts connect comment dispositions, fixes, validation, and cited replies;
- benchmark artifacts show the exact scope and limits of published quality claims.
These artifacts are inputs to engineering judgment, not replacements for it.
They are designed to be inspected, checked, regenerated, or discarded when the
repository has moved.
## Local and Auditable
### Core local path
Core scan, route, pack, stats, explain, and benchmark operations do not require
hosted indexing, embeddings, or model API calls. Generated context, receipts,
task state, snapshots, and memory are stored locally under `.agentpack/` so
they can be inspected or removed.
Repository ignore rules, redaction, and bounded packs help control what enters
generated context. Context packs can still contain source excerpts, task text,
paths, hashes, and repository metadata, so they should be reviewed before being
shared outside the machine.
### Explicit network paths
AgentPack does not require repository upload for its core analysis. Explicit
GitHub operations, optional issue enrichment, package and release checks, and
workflows that invoke external agents or providers can use the network. Those
actions are separate from the local context engine and should be evaluated
under the credentials and policies of the external system they call.
### Trust order
Generated context, memory, observer state, and integration hints are advisory.
Source files, diffs, tests, runtime evidence, and PR state remain the source of
truth. Native host integrations are also advisory unless a host provides a
blocking API that can enforce behavior before an edit.
Read the [privacy model](docs/privacy.md), [technical architecture](docs/architecture.md),
[data flow](docs/data-flow.md), [threat model](docs/threat-model.md), and
[known limitations](docs/limitations.md).
## Proof, Not Promises
AgentPack's current public benchmark measures file selection against files
changed in historical public commits. Each sampled case checks out the parent
commit, uses the commit subject as the task, and compares selected context with
the files that were actually changed.
It is evidence for the quality of a ranked starting map, not a measurement of
downstream agent outcomes.
| Public file-selection signal | Current result |
|---|---:|
| Historical commit cases | 107 |
| Average recall | 67.2% |
| Average token precision | 50.6% |
Source: [`benchmarks/results/2026-07-06-public.md`](benchmarks/results/2026-07-06-public.md).
Methodology: [benchmarking guide](docs/benchmarking.md).
### What this evidence supports
The public artifact supports a narrow claim: AgentPack can be evaluated as a
ranked file-selection system against historical repository changes. It also
exposes misses and slice-level regressions so ranking changes can be compared
against the same corpus.
### What it does not support
These results do not establish reduced tool calls, lower cost, faster
completion, or improved task success. No public AgentPack-versus-no-AgentPack
E2E outcome report is published yet; progress is tracked in the
[E2E A/B status](benchmarks/results/e2e-ab-status.md).
## Get Started
AgentPack requires Python 3.10 or newer. Install the CLI with `pipx`, then
activate it inside a repository:
```bash
pipx install agentpack-cli
agentpack quickstart
agentpack start "fix auth token expiry"
agentpack next
```
`quickstart` initializes the local project layer, `start` records the active
task, and `next` asks AgentPack for the current safe action. MCP-capable agents
can use the same local state directly after integration setup.
The activation path creates local project state and connects the detected agent
integration. From there, the agent can pull current context, inspect focused
evidence, and continue with normal source reads and tests. The full command and
integration surfaces remain in the technical documentation.
Watch the MP4 demo
## Technical Docs
| Need | Start here |
|---|---|
| Product internals and data flow | [Architecture](docs/architecture.md) and [how AgentPack works](docs/how-agentpack-works.md) |
| Setup across agents and hosts | [Integrations](docs/integrations.md) and [agent plugins](docs/agent-plugins.md) |
| CLI and MCP behavior | [Command reference](docs/commands.md) and [MCP context engine](docs/mcp-context-engine.md) |
| Dashboard contracts | [Dashboard v2](docs/dashboard-v2.md) |
| Runtime state, handoffs, and memory | [Runtime loop](docs/runtime-loop.md) |
| Privacy and security | [Privacy](docs/privacy.md), [data flow](docs/data-flow.md), and [threat model](docs/threat-model.md) |
| Quality evidence | [Benchmarking](docs/benchmarking.md) and [limitations](docs/limitations.md) |
Start at the [technical documentation home](docs/index.md) for the complete
guide.
## Status
Alpha: `0.4.1`.
Python and JavaScript/TypeScript currently have the strongest support. APIs may
change before 1.0. Platform targets are macOS, Linux, and Windows PowerShell
with Git for Windows.
PyPI package: `agentpack-cli`. npm package: `@vishal2612200/agentpack`. CLI
command: `agentpack`. This project is unrelated to AgentPack dataset papers or
other repositories with the same name.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, validation, and pull request
expectations. Community behavior is covered by
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
New contributors can start with
[`good first issue`](https://github.com/vishal2612200/agentpack/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22),
[`help wanted`](https://github.com/vishal2612200/agentpack/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22),
or [`first-timers-only`](https://github.com/vishal2612200/agentpack/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22first-timers-only%22)
issues.
## License
GNU Affero General Public License v3.0