# vishal2612200/agentpack architecture

> Architecture diagram of the GitHub repository vishal2612200/agentpack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vishal2612200/agentpack
- Repository: https://github.com/vishal2612200/agentpack

## Overview

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.

Main entry points: [`src/agentpack/application/pack_service.py`](https://github.com/vishal2612200/agentpack/blob/main/src/agentpack/application/pack_service.py) (Pack service), [`src/agentpack/commands`](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/commands) (Commands), [`src/agentpack/core/context_pack.py`](https://github.com/vishal2612200/agentpack/blob/main/src/agentpack/core/context_pack.py) (Context pack), [`src/agentpack/analysis`](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/analysis) (Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core Engine"]
  node_node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_node_pack_service["Pack service<br/>orchestrator<br/>[pack_service.py]"]
  node_node_analysis["Analysis<br/>signal extraction"]
  node_node_router["Router<br/>task matcher"]
  node_node_context_pack["Context pack<br/>pack model<br/>[context_pack.py]"]
  node_node_state[("Repo state<br/>state/cache")]
  node_node_renderers["Renderers<br/>output formats"]
  node_node_compression["Compression<br/>output shaping"]
  node_node_commands["Commands"]
  node_node_learning["Learning<br/>feedback memory"]
  node_node_session[("Session<br/>thread state")]
  node_node_dashboard["Dashboard<br/>reports"]
end

subgraph group_group_integrations["Integrations"]
  node_node_mcp["MCP server<br/>tool server<br/>[mcp_server.py]"]
  node_node_adapters["Adapters"]
  node_node_installers["Installers<br/>deployment"]
  node_node_integrations["Hooks & platform<br/>integration glue"]
end

subgraph group_group_distribution["Distribution"]
  node_node_native["Native plugins<br/>editor extensions"]
  node_node_npm["npm wrapper<br/>node package"]
  node_node_plugin_assets["Plugin assets<br/>packaging assets"]
end

subgraph group_group_ops["Docs & Ops"]
  node_node_docs["Docs<br/>documentation"]
  node_node_benchmarks["Benchmarks<br/>evaluation data"]
end

subgraph group_group_tests["Tests"]
  node_node_tests["Tests"]
  node_node_fixtures["Fixtures<br/>sample repos"]
end

node_node_cli -->|"dispatches"| node_node_commands
node_node_commands -->|"packs"| node_node_pack_service
node_node_commands -->|"routes"| node_node_router
node_node_commands -->|"learns"| node_node_learning
node_node_commands -->|"reports"| node_node_dashboard
node_node_pack_service -->|"analyzes"| node_node_analysis
node_node_pack_service -->|"selects"| node_node_router
node_node_pack_service -->|"assembles"| node_node_context_pack
node_node_context_pack -->|"checks freshness"| node_node_state
node_node_context_pack -->|"renders"| node_node_renderers
node_node_context_pack -->|"shrinks"| node_node_compression
node_node_analysis -->|"feeds signals"| node_node_router
node_node_analysis -->|"ranks"| node_node_learning
node_node_state -->|"persists"| node_node_session
node_node_session -->|"handoffs"| node_node_pack_service
node_node_learning -->|"improves"| node_node_router
node_node_learning -->|"evaluates"| node_node_benchmarks
node_node_renderers -->|"consumes"| node_node_adapters
node_node_mcp -->|"exposes"| node_node_pack_service
node_node_adapters -->|"configures"| node_node_installers
node_node_installers -->|"hooks"| node_node_integrations
node_node_native -->|"wraps"| node_node_adapters
node_node_npm -->|"launches"| node_node_cli
node_node_plugin_assets -->|"ships"| node_node_native
node_node_tests -->|"uses"| node_node_fixtures
node_node_tests -->|"verifies"| node_node_pack_service
node_node_docs -->|"documents"| node_node_commands
node_node_benchmarks -->|"measures"| node_node_analysis

click node_node_cli "https://github.com/vishal2612200/agentpack/blob/main/src/agentpack/cli.py"
click node_node_pack_service "https://github.com/vishal2612200/agentpack/blob/main/src/agentpack/application/pack_service.py"
click node_node_analysis "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/analysis"
click node_node_router "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/router"
click node_node_context_pack "https://github.com/vishal2612200/agentpack/blob/main/src/agentpack/core/context_pack.py"
click node_node_state "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/core"
click node_node_renderers "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/renderers"
click node_node_compression "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/output_compression"
click node_node_commands "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/commands"
click node_node_learning "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/learning"
click node_node_session "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/session"
click node_node_dashboard "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/dashboard"
click node_node_mcp "https://github.com/vishal2612200/agentpack/blob/main/src/agentpack/mcp_server.py"
click node_node_adapters "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/adapters"
click node_node_installers "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/installers"
click node_node_integrations "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/integrations"
click node_node_native "https://github.com/vishal2612200/agentpack/tree/main/native-integrations"
click node_node_npm "https://github.com/vishal2612200/agentpack/tree/main/npm"
click node_node_plugin_assets "https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/data/codex_plugin"
click node_node_docs "https://github.com/vishal2612200/agentpack/tree/main/docs"
click node_node_benchmarks "https://github.com/vishal2612200/agentpack/tree/main/benchmarks"
click node_node_tests "https://github.com/vishal2612200/agentpack/tree/main/tests"
click node_node_fixtures "https://github.com/vishal2612200/agentpack/tree/main/tests/fixtures"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cli,node_node_pack_service,node_node_analysis,node_node_router,node_node_context_pack,node_node_state,node_node_renderers,node_node_compression,node_node_commands,node_node_learning,node_node_session,node_node_dashboard toneBlue
class node_node_mcp,node_node_adapters,node_node_installers,node_node_integrations toneAmber
class node_node_native,node_node_npm,node_node_plugin_assets toneMint
class node_node_docs,node_node_benchmarks toneRose
class node_node_tests,node_node_fixtures toneIndigo
```

## Components

### Core Engine

Main Python implementation for scanning, routing, packing, rendering, and repo state.

- [CLI](https://github.com/vishal2612200/agentpack/blob/main/src/agentpack/cli.py): entrypoint · User-facing command surface that dispatches into application services and subsystem commands. · `src/agentpack/cli.py`
- [Pack service](https://github.com/vishal2612200/agentpack/blob/main/src/agentpack/application/pack_service.py): orchestrator · Central application boundary that coordinates pack creation end to end. · `src/agentpack/application/pack_service.py`
- [Analysis](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/analysis): signal extraction · Repository understanding layer: imports, symbols, dependency graphs, repo maps, task intent, and ranking signals. · `src/agentpack/analysis`
- [Router](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/router): task matcher · Selects the best skill, rule, prompt, or workflow for a task. · `src/agentpack/router`
- [Context pack](https://github.com/vishal2612200/agentpack/blob/main/src/agentpack/core/context_pack.py): pack model · Builds the budgeted pack with selection, freshness, citations, redaction, and token accounting. · `src/agentpack/core/context_pack.py`
- [Repo state](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/core): state/cache · Tracks cache, git changes, ignore rules, execution state, and pack registry freshness. · `src/agentpack/core`
- [Renderers](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/renderers): output formats · Formats the internal pack into compact text, markdown, receipts, and TOON. · `src/agentpack/renderers`
- [Compression](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/output_compression): output shaping · Normalizes or shrinks command output before it reaches the user or agent. · `src/agentpack/output_compression`
- [Commands](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/commands): cli subcommands · Pack, route, review, diagnose, install, scan, status, watch, learn, benchmark, and maintenance commands. · `src/agentpack/commands`
- [Learning](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/learning): feedback memory · Collects lessons, feedback, quality signals, and reusable skill memory for future routing and ranking. · `src/agentpack/learning`
- [Session](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/session): thread state · Maintains thread context, references, and event continuity across interactions. · `src/agentpack/session`
- [Dashboard](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/dashboard): reports · Collects and renders operational metrics and pack-related views. · `src/agentpack/dashboard`

### Integrations

Thin boundaries for agents, editors, hooks, and MCP exposure.

- [MCP server](https://github.com/vishal2612200/agentpack/blob/main/src/agentpack/mcp_server.py): tool server · Exposes the local engine as MCP tools for external agents. · `src/agentpack/mcp_server.py`
- [Adapters](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/adapters): agent adapters · Agent-specific behavior for Claude, Codex, Cursor, Windsurf, Antigravity, and generic flows. · `src/agentpack/adapters`
- [Installers](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/installers): deployment · Platform-specific installation and setup logic for editor and agent environments. · `src/agentpack/installers`
- [Hooks & platform](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/integrations): integration glue · Git hooks, global install handling, platform detection, and VS Code task helpers. · `src/agentpack/integrations`

### Distribution

Non-Python delivery surfaces and plugin packaging.

- [Native plugins](https://github.com/vishal2612200/agentpack/tree/main/native-integrations): editor extensions · Cursor and Windsurf extension shells that wrap the Python core. · `native-integrations`
- [npm wrapper](https://github.com/vishal2612200/agentpack/tree/main/npm): node package · JavaScript launcher and package metadata for CLI distribution. · `npm`
- [Plugin assets](https://github.com/vishal2612200/agentpack/tree/main/src/agentpack/data/codex_plugin): packaging assets · Published plugin metadata, skills, and agent-specific assets shipped with the repo. · `src/agentpack/data/codex_plugin`

### Docs & Ops

Repository documentation, benchmarks, and release/workflow assets.

- [Docs](https://github.com/vishal2612200/agentpack/tree/main/docs): documentation · Architecture, usage, integrations, threat model, and benchmark documentation. · `docs`
- [Benchmarks](https://github.com/vishal2612200/agentpack/tree/main/benchmarks): evaluation data · Public-repo benchmark definitions and result history for pack quality and routing. · `benchmarks`

### Tests

Integration-heavy validation and fixture repositories.

- [Tests](https://github.com/vishal2612200/agentpack/tree/main/tests): integration tests · Broad validation suite covering adapters, routing, packing, learning, and runtime flows. · `tests`
- [Fixtures](https://github.com/vishal2612200/agentpack/tree/main/tests/fixtures): sample repos · Representative Python, Go, Rails, Next.js, mixed-language, and secret-repo fixtures. · `tests/fixtures`

## Connections

- CLI → Commands: dispatches · CLI entrypoint routes subcommands into command handlers.
- Commands → Pack service: packs · Pack-related commands invoke the orchestration boundary.
- Commands → Router: routes · Route-oriented commands use the task matcher.
- Commands → Learning: learns · Learning, review, and refresh commands update local memory.
- Commands → Dashboard: reports · Dashboard and stats commands assemble operational views.
- Pack service → Analysis: analyzes · Pack creation depends on repository signals and scoring.
- Pack service → Router: selects · Task intent is resolved into a workflow or skill path.
- Pack service → Context pack: assembles · Selected signals become a bounded context artifact.
- Context pack → Repo state: checks freshness · Uses cache, git, ignored paths, and prior packs to decide what is stale.
- Context pack → Renderers: renders · Internal pack representation is converted into consumable formats.
- Context pack → Compression: shrinks · Output shaping can reduce or normalize command output.
- Analysis → Router: feeds signals · Task classification and repo understanding inform routing decisions.
- Analysis → Learning: ranks · Scoring and quality signals help prioritize lessons and context.
- Repo state → Session: persists · Execution state and thread context support continuity across runs.
- Session → Pack service: handoffs · Session references and thread continuity can influence pack construction.
- Learning → Router: improves · Lessons and skill maps refine future route selection.
- Learning → Benchmarks: evaluates · Offline benchmarking and quality measures validate learning effects.
- Renderers → Adapters: consumes · Rendered artifacts are tailored for specific agent environments.
- MCP server → Pack service: exposes · MCP tools call the same pack orchestration pipeline.
- Adapters → Installers: configures · Agent-specific adapters pair with install/setup flows.
- Installers → Hooks & platform: hooks · Installers rely on platform and hook integration helpers.
- Native plugins → Adapters: wraps · Editor extension shells provide thin runtime integration around adapters.
- npm wrapper → CLI: launches · Node wrapper launches the Python CLI package.
- Plugin assets → Native plugins: ships · Packaged plugin metadata and skills are distributed with editor integrations.
- Tests → Fixtures: uses · Integration tests exercise the engine against representative repositories.
- Tests → Pack service: verifies · End-to-end tests validate the main pack pipeline.
- Docs → Commands: documents · Docs explain CLI commands, runtime flow, and integrations.
- Benchmarks → Analysis: measures · Benchmark results track ranking and selection quality.