vishal2612200/agentpack

1. What this repository is

AgentPack is a local-first context engine for coding agents. Its core job is to scan a repository, score what matters for a task, and emit a compact “pack” of files, tests, rules, warnings, and provenance that another agent can consume before editing code.

2. Primary runtime and delivery shape

The main implementation is a Python CLI package under src/agentpack. That engine is the source of truth for scanning, ranking, packaging, routing, review prep, and diagnostics. Around it are thin distribution layers: an npm wrapper in npm/, native integration stubs in native-integrations/, and CLI/IDE plugin assets stored under src/agentpack/data/ and the repo root.

3. Core orchestration layer

src/agentpack/application/pack_service.py is the central orchestration boundary for “pack” creation. It sits above analysis, caching, rendering, and provenance, and is the main application-service layer that turns raw repo signals into a usable context artifact.

4. Repository analysis subsystem

src/agentpack/analysis/ contains the signal extraction and scoring inputs: import parsing for Python/JS/TS/Go/Java/Rust, symbol extraction, dependency graphs, monorepo detection, naming signals, task classification, role inference, repo maps, and broad-context detection. This layer is responsible for understanding the repository structure before any context is selected.

5. Task routing subsystem

src/agentpack/router/ decides which skill, rule, prompt, or workflow best fits the task. It includes discovery, parsing, scoring, prompt building, and skills indexing. In architecture terms, this is the “task-to-workflow matcher” that converts a user intent like “fix auth expiry” into an actionable local route.

6. Context packing and representation

src/agentpack/core/context_pack.py, snapshot.py, structured_format.py, citations.py, token_estimator.py, redactor.py, and related files implement the pack assembly pipeline. This layer handles budgeted selection, token accounting, file receipts, freshness checks, citation-backed provenance, and redaction/safety before rendering output.

7. State, cache, and repository lifecycle

src/agentpack/core/cache.py, execution_state.py, task_freshness.py, changed_paths.py, git.py, ignore.py, scanner.py, and pack_registry.py provide persistence and repo-awareness. They track what changed, what was already summarized, what should be ignored, and whether a prior pack is stale relative to task or git state.

8. Rendering and output formats

src/agentpack/renderers/ converts the internal pack model into consumable artifacts such as compact text, markdown, receipts, and TOON format. src/agentpack/output_compression/ is a separate output-shaping layer for shrinking or normalizing command output. This is the boundary between internal selection logic and what humans or agents actually read.

9. CLI command surface

src/agentpack/commands/ is the user-facing shell API. Commands cover packing, routing, review, learning, benchmarking, diagnostics, installation, init/doctor/scan/status/watch, memory/state, CI helpers, and integrations. The CLI is the main entrypoint that stitches together application services, analysis, and renderers.

10. Agent and editor integrations

src/agentpack/adapters/ and src/agentpack/installers/ encode platform-specific behavior for Claude, Codex, Cursor, Windsurf, Antigravity, and generic flows. src/agentpack/integrations/ and native-integrations/ hold the glue for Git hooks, VS Code tasks, global install handling, platform detection, and editor-extension shells. These are intentionally thin boundaries over the core engine.

11. Learning, evaluation, and routing intelligence

src/agentpack/learning/ and src/agentpack/summaries/ support reusable memory, lesson extraction, feedback loops, quality ranking, and offline summaries. src/agentpack/core/evals.py, e2e_benchmark.py, and src/agentpack/analysis/ranking.py connect this intelligence to measured pack quality. The architecture treats learning as local metadata that improves future routing and ranking, not as a cloud model service.

12. Session and review workflows

src/agentpack/session/ and src/agentpack/core/pack_handoff.py manage thread context, references, and event/state continuity across agent interactions. Review-oriented artifacts in src/agentpack/data/review/ and the review commands build staged PR-review bundles rather than a single prompt, separating “understand” from “judge” to make review outputs more reproducible.

13. MCP and plugin distribution

src/agentpack/mcp_server.py exposes the local engine as MCP tools, so external agents can call the same repository-analysis and packing workflow through a standard tool interface. The repo also ships plugin metadata and generated assets under src/agentpack/data/codex_plugin/ and the root .codex-plugin, .cursor, .windsurf, etc., which are distribution surfaces rather than core logic.

14. Test and fixture architecture

tests/ is broad and integration-heavy, with fixtures for Python/FastAPI, Django REST, Go services, Rails, Next.js, mixed-language repos, and secret-repo cases. Those fixtures reflect the engine’s real architecture concern: selecting and ranking repo context across heterogeneous codebases, not just one framework.

15. End-to-end data flow

The main flow is: CLI/agent request → scan and repo signals → task classification/routing → ranking and freshness checks → pack assembly with citations and receipts → renderer/output artifact → optional MCP/plugin consumption. Most boundaries are local and file-system based, with Git and editor hooks as the main external interfaces; there is no cloud index in the core architecture.