agentpack-cli 0.3.12__tar.gz → 0.3.14__tar.gz

{agentpack_cli-0.3.12 → agentpack_cli-0.3.14}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: agentpack-cli
-Version: 0.3.12
-Summary: Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs.
+Version: 0.3.14
+Summary: Local MCP context router for Claude Code, Codex, Cursor, and AI coding agents.
 License: MIT
 License-File: LICENSE
-Keywords: ai,ai-coding-agents,antigravity,ci,codex,context,context-engine,context-packing,cursor,developer-tools,llm,mcp,packing,prompt-context,repo-analysis,windsurf
+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,mcp,mcp-context-engine,packing,prompt-context,reduce-token-usage,repo-analysis,repo-context,windsurf
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -47,15 +47,60 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **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.
+**Local MCP context router for AI coding agents.**
+
+Claude Code, Codex, Cursor, and other coding agents can waste tool calls rediscovering your repo before they make the edit you asked for.
+
+AgentPack gives them a ranked map of likely relevant files, tests, rules, and skills for each task. It analyzes your repo locally and packages compact context for CLI and MCP workflows.
+
+No cloud indexing. No embeddings required. No API calls for scan, summarize, rank, pack, stats, or benchmark. AgentPack is a context preparation tool, not a coding agent.
+
+Try the read-only task router without writing context files:
+
+```bash
+pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
+```
+
+![AgentPack route demo](docs/assets/agentpack-route-demo.svg)
+
+> **Status: alpha (v0.3.14).** Works, tested, and used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Current benchmarks are useful regression checks, not broad proof that AgentPack improves coding-agent success. 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.
+>
+> **Name note:** PyPI package is `agentpack-cli`, npm package is `@vishal2612200/agentpack`, and the command is `agentpack`. This project is unrelated to AgentPack dataset papers or other repos with the same name.
+
+## Before vs After
+
+Without AgentPack, a cold coding-agent session often starts with manual repo orientation:
+
+```text
+Task: fix auth token expiry
+
+Agent:
+- searches for auth files
+- opens nearby middleware and config
+- may miss related tests
+- spends early turns building a repo map
+```
+
+With AgentPack:
 
-**Local context engine for AI coding agents.**
+```bash
+agentpack route --task "fix auth token expiry"
+```
 
-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.
+```text
+Task:
+fix auth token expiry
 
-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.
+Relevant files:
+- tests/test_auth.py
+- src/app/auth.py
+- src/app/users.py
+
+Suggested commands:
+- pytest tests/test_auth.py -q
+```
 
 ## Features
 
@@ -66,6 +111,7 @@ Use AgentPack when a repo is too large to paste and you want faster, more consis
 - **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.
+- **Learning layer**: turns task diffs into developer learning notes, skill evidence, and compact lessons future agents can reuse.
 - **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.
 
@@ -82,6 +128,17 @@ Latest public release gate: 8 real commits from Pallets Click, ItsDangerous, and
 
 Full table: [`benchmarks/results/2026-05-27-public.md`](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`.
 
+## Use Cases
+
+- [Claude Code context engine](docs/claude-code-context-engine.md)
+- [MCP context engine](docs/mcp-context-engine.md)
+- [Cursor context packing](docs/cursor-context-packing.md)
+- [AI coding agent context packing](docs/ai-coding-agent-context.md)
+- [Reduce Claude Code token usage](docs/reduce-claude-code-token-usage.md)
+- [AgentPack vs Repomix](docs/agentpack-vs-repomix.md)
+- [AgentPack vs Augment Context Engine](docs/agentpack-vs-augment-context-engine.md)
+- [Docs index](docs/index.md)
+
 ## Install
 
 ```bash
@@ -138,6 +195,27 @@ 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.
 
+### Learn from AI-assisted work
+
+Generate local post-task learning artifacts from `.agentpack/task.md` and git changes:
+
+```bash
+agentpack learn
+agentpack learn --today
+agentpack learn --since main
+agentpack learn --json
+agentpack learn --llm-prompt --pr-comment
+agentpack learn --provider-preview
+agentpack learn --provider-command "python scripts/learn_provider.py"
+agentpack learn --dashboard --team-export
+agentpack learn --skills
+agentpack learn --drills
+agentpack learn --ci
+agentpack learn --feedback helpful --feedback-target "skill:CLI design" --feedback-note "Useful review prompts"
+```
+
+AgentPack writes developer notes to `.agentpack/learning.md` or `.agentpack/daily-summary.md`, updates a local skill memory in `.agentpack/skills-progress.json`, writes ranked `.agentpack/agent-lessons.md` for future coding agents, and can emit `.agentpack/learning.prompt.md`, `.agentpack/pr-learning-comment.md`, `.agentpack/learning-dashboard.html`, or `.agentpack/team-lessons.md`. Learn is local-first by default: `--provider-preview` shows the bounded payload for optional external refinement without making a network call, `--provider-command` runs only the local command you provide, and feedback stays in `.agentpack/learning-feedback.jsonl`.
+
 ## 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.
@@ -247,6 +325,7 @@ gate.
 | `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 learn` | Generate developer learning notes, skill memory, feedback-aware drills, and future-agent lessons |
 | `agentpack task show|set|clear` | Manage global or thread-scoped task files |
 | `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 |
@@ -294,7 +373,7 @@ 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.
+AgentPack is best treated as a ranked starting map. It can reduce repeated orientation work, but the agent and reviewer still own correctness.
 
 Use real repo evals instead of trusting compression numbers:
 
@@ -302,7 +381,7 @@ Use real repo evals instead of trusting compression numbers:
 agentpack benchmark --release-gate
 ```
 
-Current public benchmark evidence is documented in [`benchmarks/README.md`](benchmarks/README.md) and the generated public table under `benchmarks/results/`.
+Current benchmark evidence is documented in [`benchmarks/README.md`](benchmarks/README.md) and the generated tables under `benchmarks/results/`. Treat these as scoped evidence for the included cases, not a universal performance claim.
 
 ## What A Pack Contains
 
@@ -329,6 +408,13 @@ AgentPack writes local artifacts under `.agentpack/`:
 | `.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/learning.md` | local post-task developer learning notes |
+| `.agentpack/daily-summary.md` | local daily learning rollup from `agentpack learn --today` |
+| `.agentpack/skills-progress.json` | local skill evidence map from task work |
+| `.agentpack/agent-lessons.md` | compact repo-specific lessons injected into future packs |
+| `.agentpack/learning.prompt.md` | optional source-backed prompt for external LLM refinement |
+| `.agentpack/pr-learning-comment.md` | optional PR-comment-ready learning summary |
+| `.agentpack/learning-feedback.jsonl` | optional local helpful/not-helpful feedback records |
 | `.agentpack/pack_metadata.json` | freshness and pack metadata |
 | `.agentpack/cache/` | offline file summaries keyed by hash |
 | `.agentpack/snapshots/` | repo snapshot hashes |

{agentpack_cli-0.3.12 → agentpack_cli-0.3.14}/README.md

@@ -8,15 +8,60 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
 
-> **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.
+**Local MCP context router for AI coding agents.**
+
+Claude Code, Codex, Cursor, and other coding agents can waste tool calls rediscovering your repo before they make the edit you asked for.
+
+AgentPack gives them a ranked map of likely relevant files, tests, rules, and skills for each task. It analyzes your repo locally and packages compact context for CLI and MCP workflows.
+
+No cloud indexing. No embeddings required. No API calls for scan, summarize, rank, pack, stats, or benchmark. AgentPack is a context preparation tool, not a coding agent.
+
+Try the read-only task router without writing context files:
+
+```bash
+pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
+```
+
+![AgentPack route demo](docs/assets/agentpack-route-demo.svg)
+
+> **Status: alpha (v0.3.14).** Works, tested, and used in real sessions. Python and JavaScript/TypeScript are the best-supported languages. Current benchmarks are useful regression checks, not broad proof that AgentPack improves coding-agent success. 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.
+>
+> **Name note:** PyPI package is `agentpack-cli`, npm package is `@vishal2612200/agentpack`, and the command is `agentpack`. This project is unrelated to AgentPack dataset papers or other repos with the same name.
+
+## Before vs After
+
+Without AgentPack, a cold coding-agent session often starts with manual repo orientation:
+
+```text
+Task: fix auth token expiry
+
+Agent:
+- searches for auth files
+- opens nearby middleware and config
+- may miss related tests
+- spends early turns building a repo map
+```
+
+With AgentPack:
 
-**Local context engine for AI coding agents.**
+```bash
+agentpack route --task "fix auth token expiry"
+```
 
-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.
+```text
+Task:
+fix auth token expiry
 
-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.
+Relevant files:
+- tests/test_auth.py
+- src/app/auth.py
+- src/app/users.py
+
+Suggested commands:
+- pytest tests/test_auth.py -q
+```
 
 ## Features
 
@@ -27,6 +72,7 @@ Use AgentPack when a repo is too large to paste and you want faster, more consis
 - **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.
+- **Learning layer**: turns task diffs into developer learning notes, skill evidence, and compact lessons future agents can reuse.
 - **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.
 
@@ -43,6 +89,17 @@ Latest public release gate: 8 real commits from Pallets Click, ItsDangerous, and
 
 Full table: [`benchmarks/results/2026-05-27-public.md`](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`.
 
+## Use Cases
+
+- [Claude Code context engine](docs/claude-code-context-engine.md)
+- [MCP context engine](docs/mcp-context-engine.md)
+- [Cursor context packing](docs/cursor-context-packing.md)
+- [AI coding agent context packing](docs/ai-coding-agent-context.md)
+- [Reduce Claude Code token usage](docs/reduce-claude-code-token-usage.md)
+- [AgentPack vs Repomix](docs/agentpack-vs-repomix.md)
+- [AgentPack vs Augment Context Engine](docs/agentpack-vs-augment-context-engine.md)
+- [Docs index](docs/index.md)
+
 ## Install
 
 ```bash
@@ -99,6 +156,27 @@ 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.
 
+### Learn from AI-assisted work
+
+Generate local post-task learning artifacts from `.agentpack/task.md` and git changes:
+
+```bash
+agentpack learn
+agentpack learn --today
+agentpack learn --since main
+agentpack learn --json
+agentpack learn --llm-prompt --pr-comment
+agentpack learn --provider-preview
+agentpack learn --provider-command "python scripts/learn_provider.py"
+agentpack learn --dashboard --team-export
+agentpack learn --skills
+agentpack learn --drills
+agentpack learn --ci
+agentpack learn --feedback helpful --feedback-target "skill:CLI design" --feedback-note "Useful review prompts"
+```
+
+AgentPack writes developer notes to `.agentpack/learning.md` or `.agentpack/daily-summary.md`, updates a local skill memory in `.agentpack/skills-progress.json`, writes ranked `.agentpack/agent-lessons.md` for future coding agents, and can emit `.agentpack/learning.prompt.md`, `.agentpack/pr-learning-comment.md`, `.agentpack/learning-dashboard.html`, or `.agentpack/team-lessons.md`. Learn is local-first by default: `--provider-preview` shows the bounded payload for optional external refinement without making a network call, `--provider-command` runs only the local command you provide, and feedback stays in `.agentpack/learning-feedback.jsonl`.
+
 ## 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.
@@ -208,6 +286,7 @@ gate.
 | `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 learn` | Generate developer learning notes, skill memory, feedback-aware drills, and future-agent lessons |
 | `agentpack task show|set|clear` | Manage global or thread-scoped task files |
 | `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 |
@@ -255,7 +334,7 @@ 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.
+AgentPack is best treated as a ranked starting map. It can reduce repeated orientation work, but the agent and reviewer still own correctness.
 
 Use real repo evals instead of trusting compression numbers:
 
@@ -263,7 +342,7 @@ Use real repo evals instead of trusting compression numbers:
 agentpack benchmark --release-gate
 ```
 
-Current public benchmark evidence is documented in [`benchmarks/README.md`](benchmarks/README.md) and the generated public table under `benchmarks/results/`.
+Current benchmark evidence is documented in [`benchmarks/README.md`](benchmarks/README.md) and the generated tables under `benchmarks/results/`. Treat these as scoped evidence for the included cases, not a universal performance claim.
 
 ## What A Pack Contains
 
@@ -290,6 +369,13 @@ AgentPack writes local artifacts under `.agentpack/`:
 | `.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/learning.md` | local post-task developer learning notes |
+| `.agentpack/daily-summary.md` | local daily learning rollup from `agentpack learn --today` |
+| `.agentpack/skills-progress.json` | local skill evidence map from task work |
+| `.agentpack/agent-lessons.md` | compact repo-specific lessons injected into future packs |
+| `.agentpack/learning.prompt.md` | optional source-backed prompt for external LLM refinement |
+| `.agentpack/pr-learning-comment.md` | optional PR-comment-ready learning summary |
+| `.agentpack/learning-feedback.jsonl` | optional local helpful/not-helpful feedback records |
 | `.agentpack/pack_metadata.json` | freshness and pack metadata |
 | `.agentpack/cache/` | offline file summaries keyed by hash |
 | `.agentpack/snapshots/` | repo snapshot hashes |

{agentpack_cli-0.3.12 → agentpack_cli-0.3.14}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "agentpack-cli"
-version = "0.3.12"
-description = "Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs."
+version = "0.3.14"
+description = "Local MCP context router for Claude Code, Codex, Cursor, and AI coding agents."
 readme = "README.md"
 requires-python = ">=3.10"
 license = {text = "MIT"}
-keywords = ["ai-coding-agents", "developer-tools", "repo-analysis", "context-engine", "context-packing", "prompt-context", "mcp", "ci", "codex", "cursor", "windsurf", "antigravity", "ai", "llm", "context", "packing"]
+keywords = ["ai-coding-agents", "coding-agent", "ai-agent", "claude-code", "developer-tools", "repo-analysis", "repo-context", "context-engine", "mcp-context-engine", "context-router", "context-packing", "prompt-context", "reduce-token-usage", "mcp", "ci", "codex", "cursor", "windsurf", "antigravity", "ai", "llm", "context", "packing"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",

{agentpack_cli-0.3.12 → agentpack_cli-0.3.14}/src/agentpack/__init__.py

@@ -1,3 +1,3 @@
 """AgentPack — task-aware context packing for AI coding agents."""
 
-__version__ = "0.3.12"
+__version__ = "0.3.14"

{agentpack_cli-0.3.12 → agentpack_cli-0.3.14}/src/agentpack/analysis/dependency_graph.py

@@ -11,6 +11,8 @@ from agentpack.analysis.go_imports import extract_imports as go_imports
 from agentpack.analysis.rust_imports import extract_imports as rust_imports
 from agentpack.analysis.java_imports import extract_imports as java_imports
 
+_GRAPH_CACHE: dict[tuple[tuple[tuple[str, str | None], ...], bool], DependencyGraph] = {}
+
 
 def build(
     files: list[FileInfo],
@@ -28,6 +30,14 @@ def build(
         DependencyGraph with typed DependencyNode entries. Caller fills tests
         via find_related_tests after construction.
     """
+    cache_key = (
+        tuple(sorted((fi.path, fi.hash) for fi in files)),
+        bool(summaries),
+    )
+    cached_graph = _GRAPH_CACHE.get(cache_key)
+    if cached_graph is not None:
+        return cached_graph.model_copy(deep=True)
+
     graph = DependencyGraph(
         nodes={fi.path: DependencyNode(path=fi.path) for fi in files}
     )
@@ -66,6 +76,7 @@ def build(
             if dep in graph:
                 graph.nodes[dep].imported_by.append(fi.path)
 
+    _GRAPH_CACHE[cache_key] = graph.model_copy(deep=True)
     return graph