agentpack-cli 0.3.20__tar.gz → 0.3.21__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (153) hide show
  1. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/PKG-INFO +90 -66
  2. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/README.md +89 -65
  3. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/pyproject.toml +1 -1
  4. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/__init__.py +1 -1
  5. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/ranking.py +410 -19
  6. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/symbols.py +4 -0
  7. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/application/pack_service.py +52 -30
  8. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/benchmark.py +1010 -24
  9. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/diagnose_selection.py +1 -1
  10. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/explain.py +11 -6
  11. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/guard.py +4 -3
  12. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/init.py +14 -16
  13. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/migrate.py +4 -3
  14. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/pack.py +6 -5
  15. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/quickstart.py +5 -3
  16. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/stats.py +2 -2
  17. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/tune.py +1 -1
  18. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/config.py +8 -4
  19. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/context_pack.py +419 -38
  20. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/models.py +4 -2
  21. agentpack_cli-0.3.21/src/agentpack/core/modes.py +23 -0
  22. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/mcp_server.py +2 -2
  23. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/renderers/markdown.py +2 -0
  24. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/summaries/base.py +6 -2
  25. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/.gitignore +0 -0
  26. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/LICENSE +0 -0
  27. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/adapters/__init__.py +0 -0
  28. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/adapters/antigravity.py +0 -0
  29. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/adapters/base.py +0 -0
  30. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/adapters/claude.py +0 -0
  31. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/adapters/codex.py +0 -0
  32. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/adapters/cursor.py +0 -0
  33. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/adapters/detect.py +0 -0
  34. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/adapters/generic.py +0 -0
  35. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/adapters/windsurf.py +0 -0
  36. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/__init__.py +0 -0
  37. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/dependency_graph.py +0 -0
  38. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/go_imports.py +0 -0
  39. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/java_imports.py +0 -0
  40. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/js_ts_imports.py +0 -0
  41. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/monorepo.py +0 -0
  42. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/naming_signals.py +0 -0
  43. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/python_ast.py +0 -0
  44. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/python_imports.py +0 -0
  45. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/repo_map.py +0 -0
  46. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/role_inference.py +0 -0
  47. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/rust_imports.py +0 -0
  48. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/task_classifier.py +0 -0
  49. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/analysis/tests.py +0 -0
  50. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/application/__init__.py +0 -0
  51. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/cli.py +0 -0
  52. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/__init__.py +0 -0
  53. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/_shared.py +0 -0
  54. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/ci_cmd.py +0 -0
  55. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/claude_cmd.py +0 -0
  56. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/compress_output.py +0 -0
  57. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/dashboard.py +0 -0
  58. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/dev_check.py +0 -0
  59. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/diff.py +0 -0
  60. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/doctor.py +0 -0
  61. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/eval_cmd.py +0 -0
  62. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/hook_cmd.py +0 -0
  63. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/ignore_cmd.py +0 -0
  64. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/install.py +0 -0
  65. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/learn.py +0 -0
  66. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/mcp_cmd.py +0 -0
  67. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/memory.py +0 -0
  68. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/monitor.py +0 -0
  69. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/next_cmd.py +0 -0
  70. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/perf.py +0 -0
  71. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/release_check.py +0 -0
  72. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/release_cmd.py +0 -0
  73. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/repair.py +0 -0
  74. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/retrieve.py +0 -0
  75. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/route.py +0 -0
  76. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/scan.py +0 -0
  77. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/skills.py +0 -0
  78. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/start_cmd.py +0 -0
  79. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/state_cmd.py +0 -0
  80. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/status.py +0 -0
  81. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/summarize.py +0 -0
  82. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/task_cmd.py +0 -0
  83. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/threads.py +0 -0
  84. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/verify_wheel.py +0 -0
  85. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/watch.py +0 -0
  86. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/workflow_cmd.py +0 -0
  87. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/commands/wrap.py +0 -0
  88. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/__init__.py +0 -0
  89. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/bootstrap.py +0 -0
  90. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/cache.py +0 -0
  91. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/changed_paths.py +0 -0
  92. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/diff.py +0 -0
  93. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/evals.py +0 -0
  94. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/execution_state.py +0 -0
  95. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/git.py +0 -0
  96. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/git_hooks.py +0 -0
  97. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/global_install.py +0 -0
  98. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/ignore.py +0 -0
  99. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/loop_protocol.py +0 -0
  100. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/merkle.py +0 -0
  101. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/pack_registry.py +0 -0
  102. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/redactor.py +0 -0
  103. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/scanner.py +0 -0
  104. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/snapshot.py +0 -0
  105. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/task_freshness.py +0 -0
  106. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/thread_context.py +0 -0
  107. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/token_estimator.py +0 -0
  108. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/core/vscode_tasks.py +0 -0
  109. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/dashboard/__init__.py +0 -0
  110. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/dashboard/collectors.py +0 -0
  111. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/dashboard/models.py +0 -0
  112. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/dashboard/renderers.py +0 -0
  113. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/data/agentpack.md +0 -0
  114. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/installers/__init__.py +0 -0
  115. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/installers/antigravity.py +0 -0
  116. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/installers/claude.py +0 -0
  117. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/installers/codex.py +0 -0
  118. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/installers/cursor.py +0 -0
  119. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/installers/windsurf.py +0 -0
  120. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/integrations/__init__.py +0 -0
  121. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/integrations/agents.py +0 -0
  122. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/integrations/git_hooks.py +0 -0
  123. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/integrations/global_install.py +0 -0
  124. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/integrations/platform.py +0 -0
  125. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/integrations/vscode_tasks.py +0 -0
  126. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/learning/__init__.py +0 -0
  127. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/learning/collector.py +0 -0
  128. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/learning/extractor.py +0 -0
  129. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/learning/feedback.py +0 -0
  130. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/learning/lesson_ranker.py +0 -0
  131. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/learning/models.py +0 -0
  132. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/learning/provider.py +0 -0
  133. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/learning/quality.py +0 -0
  134. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/learning/renderers.py +0 -0
  135. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/learning/skill_map.py +0 -0
  136. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/output_compression/__init__.py +0 -0
  137. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/output_compression/core.py +0 -0
  138. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/renderers/__init__.py +0 -0
  139. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/renderers/compact.py +0 -0
  140. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/renderers/receipts.py +0 -0
  141. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/router/__init__.py +0 -0
  142. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/router/discovery.py +0 -0
  143. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/router/models.py +0 -0
  144. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/router/parser.py +0 -0
  145. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/router/prompt_builder.py +0 -0
  146. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/router/scoring.py +0 -0
  147. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/router/service.py +0 -0
  148. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/router/skills_index.py +0 -0
  149. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/session/__init__.py +0 -0
  150. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/session/events.py +0 -0
  151. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/session/state.py +0 -0
  152. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/summaries/__init__.py +0 -0
  153. {agentpack_cli-0.3.20 → agentpack_cli-0.3.21}/src/agentpack/summaries/offline.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agentpack-cli
3
- Version: 0.3.20
3
+ Version: 0.3.21
4
4
  Summary: Local MCP context router for Claude Code, Codex, Cursor, and AI coding agents.
5
5
  License: MIT
6
6
  License-File: LICENSE
@@ -49,14 +49,17 @@ Description-Content-Type: text/markdown
49
49
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
50
50
  [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
51
51
 
52
- **Local MCP context router for AI coding agents.**
52
+ **Local context router for AI coding agents.**
53
53
 
54
- Claude Code, Codex, Cursor, and other coding agents can waste tool calls rediscovering your repo before they make the edit you asked for.
54
+ AgentPack gives Claude Code, Codex, Cursor, and other coding agents a ranked starting map before they burn tool calls rediscovering your repo.
55
55
 
56
- 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.
56
+ One workflow matters:
57
57
 
58
- How it works: AgentPack compresses repo context into ranked packs, caches scans/summaries/pack metadata for fast refreshes, and retrieves exact file or symbol blocks later when an agent needs more detail. Rendered packs also put stable instructions before volatile task, timestamp, git, and file sections so provider prompt-prefix caches can reuse the front of repeated refreshes. No cloud indexing, embeddings, or API calls are required for scan, summarize, rank, pack, stats, or benchmark. See [How AgentPack works](docs/how-agentpack-works.md) for the full scan, rank, compress, cache, retrieve, route, and benchmark flow.
59
- Try the read-only task router without writing context files:
58
+ ```text
59
+ route -> pack -> agent acts -> benchmark captures miss
60
+ ```
61
+
62
+ First route the task to likely files, tests, rules, and skills:
60
63
 
61
64
  ```bash
62
65
  pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
@@ -64,68 +67,72 @@ pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
64
67
 
65
68
  ![AgentPack route demo](docs/assets/agentpack-route-demo.svg)
66
69
 
67
- > **Status: alpha (v0.3.20).** 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.
70
+ > **Status: alpha (v0.3.21).** 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.
68
71
  >
69
72
  > **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.
70
73
  >
71
74
  > **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.
72
75
 
73
- ## What's New in 0.3.20
76
+ ## What's New in 0.3.21
74
77
 
75
- `0.3.20` adds a dedicated "How AgentPack works" guide for scan, rank, compress,
76
- cache, retrieve, route, stable-prefix caching, and skill keyword quality. It
77
- also polishes the local dashboard and expands skill-routing benchmark guidance
78
- for `expected_skills`, `avoid_skills`, recall, precision, MRR, and noise.
78
+ `0.3.21` is a benchmark trust release. It keeps the current honest expanded
79
+ public-suite baseline at **57.0% recall / 50.6% token precision**, removes the
80
+ legacy minimal-mode surface in favor of `balanced`, improves benchmark
81
+ diagnostics and public-suite methodology, and documents the next release target:
82
+ **65%+ recall while holding 50%+ token precision**.
79
83
 
80
- ## Before vs After
84
+ ## Core Workflow
81
85
 
82
- Without AgentPack, a cold coding-agent session often starts with manual repo orientation:
86
+ ### 1. Route
83
87
 
84
- ```text
85
- Task: fix auth token expiry
88
+ Use the read-only router when you want quick orientation without writing files:
86
89
 
87
- Agent:
88
- - searches for auth files
89
- - opens nearby middleware and config
90
- - may miss related tests
91
- - spends early turns building a repo map
90
+ ```bash
91
+ agentpack route --task "fix auth token expiry"
92
92
  ```
93
93
 
94
- With AgentPack:
94
+ ### 2. Pack
95
95
 
96
96
  ```bash
97
- agentpack route --task "fix auth token expiry"
97
+ agentpack task set "fix auth token expiry"
98
+ agentpack pack --task auto
98
99
  ```
99
100
 
100
- ```text
101
- Task:
102
- fix auth token expiry
101
+ AgentPack writes `.agentpack/context.md` with selected files, omitted-file
102
+ receipts, task freshness, token stats, and suggested checks.
103
103
 
104
- Relevant files:
105
- - tests/test_auth.py
106
- - src/app/auth.py
107
- - src/app/users.py
104
+ ### 3. Agent Acts
108
105
 
109
- Suggested commands:
110
- - pytest tests/test_auth.py -q
106
+ Point the agent at the pack or use MCP tools. Agent still verifies code before
107
+ editing; AgentPack is map, not correctness proof.
108
+
109
+ ### 4. Benchmark Captures Miss
110
+
111
+ After a task, capture the files that actually changed:
112
+
113
+ ```bash
114
+ agentpack benchmark capture --since main --task "fix auth token expiry"
115
+ agentpack benchmark --misses
111
116
  ```
112
117
 
118
+ Miss diagnostics show whether a required file was ignored, scored too low,
119
+ ranked but cut by budget, or absent from scan.
120
+
113
121
  ## Features
114
122
 
115
- - **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, repo history, and deterministic offline summaries.
116
- - **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
117
- - **Rendered-token accounting and reserve buckets**: budgets against actual markdown while protecting changed files, tests, docs, and dependencies.
118
- - **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.
119
- - **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.
120
- - **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.
121
- - **Reversible registry and learning layer**: retrieves packed context by block ID, writes developer lessons, and feeds bounded selected-file miss feedback into future ranking.
122
- - **Runtime scorecard and output compression**: `perf --history` tracks activity, while `compress-output` preserves failures, paths, diffs, and search hits from noisy logs.
123
- - **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
124
- - **Local and measurable**: no API calls for scan, summarize, rank, pack, stats, or benchmark; quality is measured with expected-file evals.
123
+ - **Route**: read-only task map with relevant files, tests, rules, skills, commands, and warnings.
124
+ - **Pack**: budgeted context with `full`, `diff`, `symbols`, `skeleton`, or `summary` file views.
125
+ - **Act**: CLI, markdown, MCP, and agent integrations for Claude Code, Codex, Cursor, Windsurf, Antigravity, and generic agents.
126
+ - **Benchmark**: expected-file recall, token precision, miss diagnostics, public commit suites, and E2E A/B reports.
127
+ - **Local**: no cloud indexing, embeddings, or API calls for scan, summarize, rank, pack, stats, or benchmark.
125
128
 
126
129
  ## Benchmark Proof
127
130
 
128
- Latest public release gate: 8 real commits from Pallets Click, ItsDangerous, and MarkupSafe, scored against files actually changed by each commit.
131
+ Latest published v0.3.20 release table: 8 pinned public commits from Pallets
132
+ Click, ItsDangerous, and MarkupSafe, scored against files actually changed by
133
+ each commit. The public manifest now also supports 100+ sampled historical
134
+ commits across Python, TypeScript, Go, Java, and monorepo repos for broader
135
+ release runs.
129
136
 
130
137
  | Metric | Result |
131
138
  |---|---:|
@@ -134,19 +141,48 @@ Latest public release gate: 8 real commits from Pallets Click, ItsDangerous, and
134
141
  | Pack p50 | 1,450 tokens |
135
142
  | Pack p95 | 3,805 tokens |
136
143
 
137
- 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`.
144
+ Full v0.3.20 table: [`benchmarks/results/2026-06-11-public.md`](benchmarks/results/2026-06-11-public.md). This is scoped benchmark evidence, not a universal quality claim.
145
+ The expanded 109-case public suite is the current optimization baseline:
146
+ **57.0% recall / 50.6% token precision**. It is broader and harder than the
147
+ 8-case published table, and recall remains the active improvement target.
148
+ Reproduce the expanded public suite:
149
+
150
+ ```bash
151
+ agentpack benchmark --public-suite --reproduce v0.3.20
152
+ ```
153
+
154
+ Benchmark methodology lives under [`benchmarks/results/v0.3.20/`](benchmarks/results/v0.3.20/methodology.md).
155
+
156
+ ### Next Release Benchmark Target
157
+
158
+ The next benchmark release target is to raise the expanded public suite from the
159
+ current **57.0% recall / 50.6% token precision** baseline to **65%+ recall**
160
+ while keeping token precision at **50%+**. The target should be measured on the
161
+ same 100+ public historical-commit suite, with per-language slices published so
162
+ precision gains are not hiding TypeScript, Go, Java, or monorepo regressions.
163
+
164
+ Decision gate for the next public table:
165
+
166
+ - full-suite recall is at least 65.0%
167
+ - full-suite token precision is at least 50.0%
168
+ - no major language or task slice loses more than 2 recall points
169
+ - Vite/TypeScript, Gin/Go, and NestJS monorepo misses are reported separately
170
+ - any AgentPack-vs-no-AgentPack A/B claim includes task success, tool calls,
171
+ token cost, and time-to-first-correct-file
172
+
173
+ ## Trust
174
+
175
+ AgentPack is MIT licensed, local-first, and uses PyPI Trusted Publishing plus
176
+ npm provenance for release artifacts. See [`SECURITY.md`](SECURITY.md),
177
+ [`docs/privacy.md`](docs/privacy.md), [`docs/threat-model.md`](docs/threat-model.md),
178
+ and [`docs/data-flow.md`](docs/data-flow.md).
138
179
 
139
180
  ## Use Cases
140
181
 
141
- - [Claude Code context engine](docs/claude-code-context-engine.md)
142
- - [MCP context engine](docs/mcp-context-engine.md)
143
- - [Cursor context packing](docs/cursor-context-packing.md)
144
- - [AI coding agent context packing](docs/ai-coding-agent-context.md)
145
- - [Reduce Claude Code token usage](docs/reduce-claude-code-token-usage.md)
146
- - [How AgentPack works](docs/how-agentpack-works.md)
147
- - [AgentPack vs Repomix](docs/agentpack-vs-repomix.md)
148
- - [AgentPack vs Augment Context Engine](docs/agentpack-vs-augment-context-engine.md)
149
- - [Docs index](docs/index.md)
182
+ Start with the [docs index](docs/index.md), or jump to guides for
183
+ [Claude Code](docs/claude-code-context-engine.md), [MCP](docs/mcp-context-engine.md),
184
+ [Cursor](docs/cursor-context-packing.md), [token usage](docs/reduce-claude-code-token-usage.md),
185
+ and [how AgentPack works](docs/how-agentpack-works.md).
150
186
 
151
187
  ## Install
152
188
 
@@ -274,7 +310,7 @@ budget = 8000
274
310
  output = ".agentpack/context.md"
275
311
  ```
276
312
 
277
- Use `agentpack pack --mode lite` when you want a cheap ranked map before deeper file reads. Use `minimal`, `balanced`, or `deep` when you want progressively more file content in the generated pack.
313
+ Use `agentpack pack --mode lite` when you want a cheap ranked map before deeper file reads. Use the default `balanced` mode for normal agent work and benchmark claims. Use `deep` when the task needs broader docs and source context.
278
314
 
279
315
  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.
280
316
 
@@ -391,18 +427,6 @@ THREAD=codex-local make context-thread
391
427
  AGENTPACK_THREAD_ID=codex-local make context-thread
392
428
  ```
393
429
 
394
- ## Benchmark Proof
395
-
396
- AgentPack is best treated as a ranked starting map. It can reduce repeated orientation work, but the agent and reviewer still own correctness.
397
-
398
- Use real repo evals instead of trusting compression numbers:
399
-
400
- ```bash
401
- agentpack benchmark --release-gate
402
- ```
403
-
404
- 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.
405
-
406
430
  ## What A Pack Contains
407
431
 
408
432
  Rendered packs are meant to be readable by humans and directly useful to agents. A typical pack includes:
@@ -8,14 +8,17 @@
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
9
  [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
10
10
 
11
- **Local MCP context router for AI coding agents.**
11
+ **Local context router for AI coding agents.**
12
12
 
13
- Claude Code, Codex, Cursor, and other coding agents can waste tool calls rediscovering your repo before they make the edit you asked for.
13
+ AgentPack gives Claude Code, Codex, Cursor, and other coding agents a ranked starting map before they burn tool calls rediscovering your repo.
14
14
 
15
- 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.
15
+ One workflow matters:
16
16
 
17
- How it works: AgentPack compresses repo context into ranked packs, caches scans/summaries/pack metadata for fast refreshes, and retrieves exact file or symbol blocks later when an agent needs more detail. Rendered packs also put stable instructions before volatile task, timestamp, git, and file sections so provider prompt-prefix caches can reuse the front of repeated refreshes. No cloud indexing, embeddings, or API calls are required for scan, summarize, rank, pack, stats, or benchmark. See [How AgentPack works](docs/how-agentpack-works.md) for the full scan, rank, compress, cache, retrieve, route, and benchmark flow.
18
- Try the read-only task router without writing context files:
17
+ ```text
18
+ route -> pack -> agent acts -> benchmark captures miss
19
+ ```
20
+
21
+ First route the task to likely files, tests, rules, and skills:
19
22
 
20
23
  ```bash
21
24
  pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
@@ -23,68 +26,72 @@ pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry"
23
26
 
24
27
  ![AgentPack route demo](docs/assets/agentpack-route-demo.svg)
25
28
 
26
- > **Status: alpha (v0.3.20).** 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.
29
+ > **Status: alpha (v0.3.21).** 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.
27
30
  >
28
31
  > **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.
29
32
  >
30
33
  > **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.
31
34
 
32
- ## What's New in 0.3.20
35
+ ## What's New in 0.3.21
33
36
 
34
- `0.3.20` adds a dedicated "How AgentPack works" guide for scan, rank, compress,
35
- cache, retrieve, route, stable-prefix caching, and skill keyword quality. It
36
- also polishes the local dashboard and expands skill-routing benchmark guidance
37
- for `expected_skills`, `avoid_skills`, recall, precision, MRR, and noise.
37
+ `0.3.21` is a benchmark trust release. It keeps the current honest expanded
38
+ public-suite baseline at **57.0% recall / 50.6% token precision**, removes the
39
+ legacy minimal-mode surface in favor of `balanced`, improves benchmark
40
+ diagnostics and public-suite methodology, and documents the next release target:
41
+ **65%+ recall while holding 50%+ token precision**.
38
42
 
39
- ## Before vs After
43
+ ## Core Workflow
40
44
 
41
- Without AgentPack, a cold coding-agent session often starts with manual repo orientation:
45
+ ### 1. Route
42
46
 
43
- ```text
44
- Task: fix auth token expiry
47
+ Use the read-only router when you want quick orientation without writing files:
45
48
 
46
- Agent:
47
- - searches for auth files
48
- - opens nearby middleware and config
49
- - may miss related tests
50
- - spends early turns building a repo map
49
+ ```bash
50
+ agentpack route --task "fix auth token expiry"
51
51
  ```
52
52
 
53
- With AgentPack:
53
+ ### 2. Pack
54
54
 
55
55
  ```bash
56
- agentpack route --task "fix auth token expiry"
56
+ agentpack task set "fix auth token expiry"
57
+ agentpack pack --task auto
57
58
  ```
58
59
 
59
- ```text
60
- Task:
61
- fix auth token expiry
60
+ AgentPack writes `.agentpack/context.md` with selected files, omitted-file
61
+ receipts, task freshness, token stats, and suggested checks.
62
62
 
63
- Relevant files:
64
- - tests/test_auth.py
65
- - src/app/auth.py
66
- - src/app/users.py
63
+ ### 3. Agent Acts
67
64
 
68
- Suggested commands:
69
- - pytest tests/test_auth.py -q
65
+ Point the agent at the pack or use MCP tools. Agent still verifies code before
66
+ editing; AgentPack is map, not correctness proof.
67
+
68
+ ### 4. Benchmark Captures Miss
69
+
70
+ After a task, capture the files that actually changed:
71
+
72
+ ```bash
73
+ agentpack benchmark capture --since main --task "fix auth token expiry"
74
+ agentpack benchmark --misses
70
75
  ```
71
76
 
77
+ Miss diagnostics show whether a required file was ignored, scored too low,
78
+ ranked but cut by budget, or absent from scan.
79
+
72
80
  ## Features
73
81
 
74
- - **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, repo history, and deterministic offline summaries.
75
- - **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
76
- - **Rendered-token accounting and reserve buckets**: budgets against actual markdown while protecting changed files, tests, docs, and dependencies.
77
- - **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.
78
- - **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.
79
- - **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.
80
- - **Reversible registry and learning layer**: retrieves packed context by block ID, writes developer lessons, and feeds bounded selected-file miss feedback into future ranking.
81
- - **Runtime scorecard and output compression**: `perf --history` tracks activity, while `compress-output` preserves failures, paths, diffs, and search hits from noisy logs.
82
- - **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
83
- - **Local and measurable**: no API calls for scan, summarize, rank, pack, stats, or benchmark; quality is measured with expected-file evals.
82
+ - **Route**: read-only task map with relevant files, tests, rules, skills, commands, and warnings.
83
+ - **Pack**: budgeted context with `full`, `diff`, `symbols`, `skeleton`, or `summary` file views.
84
+ - **Act**: CLI, markdown, MCP, and agent integrations for Claude Code, Codex, Cursor, Windsurf, Antigravity, and generic agents.
85
+ - **Benchmark**: expected-file recall, token precision, miss diagnostics, public commit suites, and E2E A/B reports.
86
+ - **Local**: no cloud indexing, embeddings, or API calls for scan, summarize, rank, pack, stats, or benchmark.
84
87
 
85
88
  ## Benchmark Proof
86
89
 
87
- Latest public release gate: 8 real commits from Pallets Click, ItsDangerous, and MarkupSafe, scored against files actually changed by each commit.
90
+ Latest published v0.3.20 release table: 8 pinned public commits from Pallets
91
+ Click, ItsDangerous, and MarkupSafe, scored against files actually changed by
92
+ each commit. The public manifest now also supports 100+ sampled historical
93
+ commits across Python, TypeScript, Go, Java, and monorepo repos for broader
94
+ release runs.
88
95
 
89
96
  | Metric | Result |
90
97
  |---|---:|
@@ -93,19 +100,48 @@ Latest public release gate: 8 real commits from Pallets Click, ItsDangerous, and
93
100
  | Pack p50 | 1,450 tokens |
94
101
  | Pack p95 | 3,805 tokens |
95
102
 
96
- 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`.
103
+ Full v0.3.20 table: [`benchmarks/results/2026-06-11-public.md`](benchmarks/results/2026-06-11-public.md). This is scoped benchmark evidence, not a universal quality claim.
104
+ The expanded 109-case public suite is the current optimization baseline:
105
+ **57.0% recall / 50.6% token precision**. It is broader and harder than the
106
+ 8-case published table, and recall remains the active improvement target.
107
+ Reproduce the expanded public suite:
108
+
109
+ ```bash
110
+ agentpack benchmark --public-suite --reproduce v0.3.20
111
+ ```
112
+
113
+ Benchmark methodology lives under [`benchmarks/results/v0.3.20/`](benchmarks/results/v0.3.20/methodology.md).
114
+
115
+ ### Next Release Benchmark Target
116
+
117
+ The next benchmark release target is to raise the expanded public suite from the
118
+ current **57.0% recall / 50.6% token precision** baseline to **65%+ recall**
119
+ while keeping token precision at **50%+**. The target should be measured on the
120
+ same 100+ public historical-commit suite, with per-language slices published so
121
+ precision gains are not hiding TypeScript, Go, Java, or monorepo regressions.
122
+
123
+ Decision gate for the next public table:
124
+
125
+ - full-suite recall is at least 65.0%
126
+ - full-suite token precision is at least 50.0%
127
+ - no major language or task slice loses more than 2 recall points
128
+ - Vite/TypeScript, Gin/Go, and NestJS monorepo misses are reported separately
129
+ - any AgentPack-vs-no-AgentPack A/B claim includes task success, tool calls,
130
+ token cost, and time-to-first-correct-file
131
+
132
+ ## Trust
133
+
134
+ AgentPack is MIT licensed, local-first, and uses PyPI Trusted Publishing plus
135
+ npm provenance for release artifacts. See [`SECURITY.md`](SECURITY.md),
136
+ [`docs/privacy.md`](docs/privacy.md), [`docs/threat-model.md`](docs/threat-model.md),
137
+ and [`docs/data-flow.md`](docs/data-flow.md).
97
138
 
98
139
  ## Use Cases
99
140
 
100
- - [Claude Code context engine](docs/claude-code-context-engine.md)
101
- - [MCP context engine](docs/mcp-context-engine.md)
102
- - [Cursor context packing](docs/cursor-context-packing.md)
103
- - [AI coding agent context packing](docs/ai-coding-agent-context.md)
104
- - [Reduce Claude Code token usage](docs/reduce-claude-code-token-usage.md)
105
- - [How AgentPack works](docs/how-agentpack-works.md)
106
- - [AgentPack vs Repomix](docs/agentpack-vs-repomix.md)
107
- - [AgentPack vs Augment Context Engine](docs/agentpack-vs-augment-context-engine.md)
108
- - [Docs index](docs/index.md)
141
+ Start with the [docs index](docs/index.md), or jump to guides for
142
+ [Claude Code](docs/claude-code-context-engine.md), [MCP](docs/mcp-context-engine.md),
143
+ [Cursor](docs/cursor-context-packing.md), [token usage](docs/reduce-claude-code-token-usage.md),
144
+ and [how AgentPack works](docs/how-agentpack-works.md).
109
145
 
110
146
  ## Install
111
147
 
@@ -233,7 +269,7 @@ budget = 8000
233
269
  output = ".agentpack/context.md"
234
270
  ```
235
271
 
236
- Use `agentpack pack --mode lite` when you want a cheap ranked map before deeper file reads. Use `minimal`, `balanced`, or `deep` when you want progressively more file content in the generated pack.
272
+ Use `agentpack pack --mode lite` when you want a cheap ranked map before deeper file reads. Use the default `balanced` mode for normal agent work and benchmark claims. Use `deep` when the task needs broader docs and source context.
237
273
 
238
274
  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.
239
275
 
@@ -350,18 +386,6 @@ THREAD=codex-local make context-thread
350
386
  AGENTPACK_THREAD_ID=codex-local make context-thread
351
387
  ```
352
388
 
353
- ## Benchmark Proof
354
-
355
- AgentPack is best treated as a ranked starting map. It can reduce repeated orientation work, but the agent and reviewer still own correctness.
356
-
357
- Use real repo evals instead of trusting compression numbers:
358
-
359
- ```bash
360
- agentpack benchmark --release-gate
361
- ```
362
-
363
- 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.
364
-
365
389
  ## What A Pack Contains
366
390
 
367
391
  Rendered packs are meant to be readable by humans and directly useful to agents. A typical pack includes:
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "agentpack-cli"
3
- version = "0.3.20"
3
+ version = "0.3.21"
4
4
  description = "Local MCP context router for Claude Code, Codex, Cursor, and AI coding agents."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
@@ -1,3 +1,3 @@
1
1
  """AgentPack — task-aware context packing for AI coding agents."""
2
2
 
3
- __version__ = "0.3.20"
3
+ __version__ = "0.3.21"