agentpack-cli 0.3.1__tar.gz → 0.3.4__tar.gz

agentpack_cli-0.3.1/README.md → agentpack_cli-0.3.4/PKG-INFO

@@ -1,19 +1,60 @@
+Metadata-Version: 2.4
+Name: agentpack-cli
+Version: 0.3.4
+Summary: Local context engine for AI coding agents that ranks relevant files and builds task-focused context packs.
+License: MIT
+License-File: LICENSE
+Keywords: ai,ai-coding-agents,antigravity,ci,claude,claude-code,codex,context,context-engine,context-packing,cursor,developer-tools,llm,mcp,packing,prompt-context,repo-analysis,windsurf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: typer>=0.12.0
+Provides-Extra: all
+Requires-Dist: mcp>=1.0.0; extra == 'all'
+Requires-Dist: watchdog>=4.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: watch
+Requires-Dist: watchdog>=4.0.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
 # AgentPack
 
 [![PyPI version](https://img.shields.io/pypi/v/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
+[![npm version](https://img.shields.io/npm/v/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
+[![npm downloads](https://img.shields.io/npm/dm/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
 [![Python versions](https://img.shields.io/pypi/pyversions/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
 [![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.1).** 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.
+> **Status: alpha (v0.3.4).** 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.
 >
-> **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
+> **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.
 
 **Local context engine for AI coding agents.**
 
-AgentPack builds task-focused context packs for Claude Code, Cursor, Windsurf, Codex, Antigravity, CI jobs, and any LLM workflow that can read markdown. It scans your repo locally, ranks files for the task, compresses the result into a token budget, and keeps the pack fresh through CLI commands, MCP tools, hooks, and agent integrations.
+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 relevant files for a task, and packages them into compact task-focused context packs for CLI and MCP tool workflows.
 
-AgentPack is useful when a repo is too large to paste, but a blank agent session wastes time rediscovering the same code structure. It is a context preparation tool, not a coding agent.
+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, keeps the product boundary explicit, and is a context preparation tool, not a coding agent.
 
 ## Contents
 
@@ -21,6 +62,7 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 - [Install](#install)
 - [Quickstart](#quickstart)
 - [Quality Bar](#quality-bar)
+- [Download Stats](#download-stats)
 - [Debugging Selection](#debugging-selection)
 - [Supported Integrations](#supported-integrations)
 - [Commands](#commands)
@@ -31,8 +73,9 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 
 ## Features
 
-- **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, and repo history.
+- **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, repo history, and deterministic offline summaries.
 - **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
+- **Local code intelligence**: extracts roles, domains, entrypoints, definitions, dependencies, env reads, side effects, and external systems using static analysis.
 - **Semantic repo map**: adds a compact module-level map before file context so agents orient faster.
 - **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, and stale-context warnings.
 - **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
@@ -66,6 +109,27 @@ sudo pacman -S python-pipx
 pipx ensurepath
 ```
 
+If `pipx` is not installed yet:
+
+```bash
+# macOS
+brew install pipx
+
+# Ubuntu/Debian
+sudo apt install pipx
+
+# Fedora
+sudo dnf install pipx
+
+# Arch
+sudo pacman -S python-pipx
+
+# Then ensure pipx apps are on PATH
+pipx ensurepath
+```
+
+`pipx` is the recommended default because it keeps the CLI isolated and avoids many macOS/Linux global `pip install` issues, including PEP 668 `externally-managed-environment` errors. If you prefer `pip`, install inside a virtual environment.
+
 JavaScript-heavy teams can install the npm wrapper:
 
 ```bash
@@ -73,7 +137,7 @@ npm install -g @vishal2612200/agentpack
 agentpack --version
 ```
 
-The npm package is a Node launcher around the Python implementation. It requires Node.js 18+ and Python 3.10+, then installs the matching core `agentpack-cli` package into a per-version virtual environment on first run. The Python package remains the source of truth; npm is the convenience install path for JavaScript-heavy teams. Use the PyPI extras below when you need optional `watch` or `mcp` dependencies.
+The npm package is a Node launcher around the Python implementation. It requires Node.js 18+ and Python 3.10+, then installs the matching core `agentpack-cli` package into a per-version virtual environment on first run. The Python package remains the source of truth; npm is the convenience install path for JavaScript-heavy teams. See the [npm README](https://github.com/vishal2612200/agentpack/blob/main/npm/README.md) for wrapper cache controls and troubleshooting. Use the PyPI extras below when you need optional `watch` or `mcp` dependencies.
 
 ## Quickstart
 
@@ -144,6 +208,24 @@ ItsDangerous, and MarkupSafe by checking out each commit's parent and scoring
 against files actually changed by the commit. Synthetic fixtures are useful
 regression tests, but should not be presented as market proof.
 
+## Download Stats
+
+npm exposes official package download counts through its public registry API and the npm downloads badge above:
+
+```bash
+curl https://api.npmjs.org/downloads/point/last-month/%40vishal2612200%2Fagentpack
+curl https://api.npmjs.org/downloads/point/last-week/%40vishal2612200%2Fagentpack
+```
+
+PyPI does not show official project download counts on package pages. For rough trend data on the Python core package, use third-party mirrors:
+
+```bash
+curl https://pypistats.org/api/packages/agentpack-cli/recent
+```
+
+- PyPI Stats: <https://pypistats.org/packages/agentpack-cli>
+- pepy.tech: <https://pepy.tech/project/agentpack-cli>
+
 ## Debugging Selection
 
 When AgentPack misses a file, the next command should explain the miss:
@@ -502,7 +584,7 @@ agentpack global-install --agent antigravity   # Antigravity
 
 What it does:
 - **Git template hooks** (`~/.git-templates/hooks/`) — git copies these into every repo on `git init` / `git clone`. On `post-commit`, `post-merge`, `post-checkout`: silently repacks **only if `.agentpack/config.toml` exists** — no-op in repos that haven't opted in.
-- **Shell cd hook** (`~/.zshrc` or `~/.bashrc`) — on `cd`, repacks if stale **only in opted-in repos**. Never touches repos without `.agentpack/config.toml`. Never auto-inits.
+- **Shell cd hook** (`~/.zshrc`, `~/.bashrc`, or the PowerShell profile on Windows) — on `cd` or prompt refresh, repacks if stale **only in opted-in repos**. Never touches repos without `.agentpack/config.toml`. Never auto-inits.
 - **Agent config** — same agent-specific files that `agentpack init --agent <x>` or `agentpack install --agent <x>` writes for the current project.
 
 All changes are idempotent, reversible, and non-destructive. Existing hooks and rc files are appended to, never overwritten. Repos you haven't explicitly run `agentpack init` in are never touched.
@@ -748,8 +830,12 @@ Uses `watchdog` if installed, falls back to polling. Context is refreshed whenev
 Install watchdog for better performance:
 ```bash
 pipx inject agentpack-cli watchdog
+PIPX_AGENTPACK="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
+"$PIPX_AGENTPACK" watch
 ```
 
+Use the explicit `pipx` binary path above if you also have the npm wrapper on `PATH`; otherwise `agentpack watch` may still resolve to the Node launcher.
+
 ---
 
 ### `agentpack claude`
@@ -770,9 +856,12 @@ Run AgentPack as an MCP server — exposes context packing as tools that Claude
 
 ```bash
 pipx inject agentpack-cli "agentpack-cli[mcp]"
-agentpack mcp
+PIPX_AGENTPACK="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
+"$PIPX_AGENTPACK" mcp
 ```
 
+Use the explicit `pipx` binary path above if you also have the npm wrapper on `PATH`; otherwise `agentpack mcp` may still resolve to the Node launcher instead of the extras-enabled Python CLI.
+
 Register in Claude Code settings (`~/.claude/settings.json`):
 
 ```json
@@ -1191,7 +1280,8 @@ Works like `.gitignore`. Default rules exclude:
           │                                         │
           │  Summary cache  ── role, imports,       │
           │  (offline)        symbols, side effects, │
-          │                   public API, errors     │
+          │                   public API, naming     │
+          │                   signals, errors        │
           │                                         │
           │  Import graph  ──  Python AST           │
           │  (6 languages)  ─  JS/TS regex          │
@@ -1204,6 +1294,9 @@ Works like `.gitignore`. Default rules exclude:
           │  ast.get_source_segment)   classes,     │
           │                    ── arrow fns w/ =>)  │
           │                                         │
+          │  Naming signals ── public files/symbols │
+          │                  ── env/config/test ids │
+          │                  ── generic-name hints  │
           │  Test detection  ── name heuristics     │
           │  Task keywords   ── stopwords + variants│
           │                  ── concept synonyms    │
@@ -1229,6 +1322,7 @@ Works like `.gitignore`. Default rules exclude:
           │   +70 symbol    +60 content match       │
           │   +50 dep       +40 rev-dep             │
           │   +35 test      +25 config  +20 recent  │
+          │   +20 naming    -6 generic public API   │
           │   -50 large unrelated                   │
           │  History noise penalty from metrics     │
           └────────────────────┬────────────────────┘
@@ -1316,14 +1410,15 @@ src/agentpack/
     rust_imports.py            # use, mod, extern crate
     java_imports.py            # Java import + Kotlin import
     symbols.py                 # AST symbols + body via ast.get_source_segment
+    naming_signals.py          # public-name classification for summaries + ranking boosts
     tests.py                   # source → test file mapping heuristics
-    ranking.py                 # keyword extraction, concept synonyms, scoring
+    ranking.py                 # keyword extraction, concept synonyms, scoring, naming receipts
     monorepo.py                # workspace detection + workspace ownership helpers
     repo_map.py                # compact semantic repo map reserved inside token budget
     task_classifier.py         # coarse task class for freshness/rendering/scoring context
 
   summaries/
-    offline.py                 # zero-API: AST/regex → imports, symbols, role, side effects, API, errors
+    offline.py                 # zero-API: AST/regex → imports, symbols, role, side effects, API, naming signals, errors
     base.py                    # cache-or-build orchestration (parallel, ThreadPool+ProcessPool)
 
   adapters/                    # context rendering only — no installation logic
@@ -1418,7 +1513,7 @@ src/agentpack/
 
 ## Known limitations
 
-- **Windows**: not supported. Git hooks use POSIX shell (`#!/bin/sh`, `>/dev/null 2>&1 &`). The Claude Code session hooks use `python3` and `rm -f`. Contributions welcome.
+- **Windows**: supported with PowerShell plus Git for Windows. AgentPack installs cross-platform Git hook launchers and a PowerShell profile hook for opted-in repos. `cmd.exe` is not a first-class workflow yet.
 - **Monorepos**: workspace-aware ranking supports npm/pnpm, Cargo, and `go.work` layouts. `--workspace` creates filtered per-workspace outputs. Package dependency hints currently come from npm/pnpm `package.json`; Cargo/Go workspace membership is detected, but package-manager dependency edges for Cargo/Go are not yet modeled.
 - **Public benchmark proof**: `benchmarks/public-repos.toml` is a curated smoke suite over real public commits, and `benchmarks/results/2026-05-15-public.md` records the current proof run. Treat it as a floor, not a leaderboard; expand cases before broad external claims.
 - **Symbol extraction**: Python (AST, full) and JavaScript/TypeScript (regex, arrow functions + classes) are well-supported. Go, Rust, Java, Kotlin have import graph traversal but no symbol extraction — they fall back to file-level summaries.
@@ -1453,6 +1548,16 @@ pipx inject agentpack-cli "agentpack-cli[all]"  # watch + mcp
 
 ## Development
 
+## Public Naming And Ranking
+
+AgentPack works better when public surfaces carry domain context. Prefer domain-revealing names for files, exported functions/classes, CLI commands, tests, and config/env identifiers.
+
+- `verify_otp` is better than `handle`
+- `StripeWebhookHandler` is better than `Processor`
+- `session_token_expiry_test` is better than `test_flow`
+
+This is guidance, not a lint rule. Local variable names are out of scope for AgentPack ranking.
+
 Clone and run locally:
 
 ```bash
@@ -1480,7 +1585,7 @@ For npm publish, configure GitHub secret `NPM_TOKEN`. The token must publish to
 Good contribution areas:
 
 - More real-world benchmark fixtures and public repo eval cases
-- Windows support for hooks and session integrations
+- Better Windows ergonomics beyond the supported PowerShell + Git for Windows path
 - Better symbol extraction for Go, Rust, Java, and Kotlin
 - More precise import/dependency resolution for framework-heavy repos
 - Ranking regressions with `expected_files` cases that reproduce misses

agentpack_cli-0.3.1/PKG-INFO → agentpack_cli-0.3.4/README.md

@@ -1,58 +1,21 @@
-Metadata-Version: 2.4
-Name: agentpack-cli
-Version: 0.3.1
-Summary: Task-aware context packing for AI coding agents — Claude, Cursor, Windsurf, Codex, and Antigravity
-License: MIT
-License-File: LICENSE
-Keywords: ai,claude,codex,coding-agent,context,cursor,llm,packing,windsurf
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Build Tools
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
-Requires-Dist: pathspec>=0.12.1
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: tiktoken>=0.7.0
-Requires-Dist: tomli-w>=1.0.0
-Requires-Dist: tomli>=2.0.0; python_version < '3.11'
-Requires-Dist: typer>=0.12.0
-Provides-Extra: all
-Requires-Dist: mcp>=1.0.0; extra == 'all'
-Requires-Dist: watchdog>=4.0.0; extra == 'all'
-Provides-Extra: dev
-Requires-Dist: mypy; extra == 'dev'
-Requires-Dist: pytest; extra == 'dev'
-Requires-Dist: pytest-cov; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
-Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
-Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
-Provides-Extra: watch
-Requires-Dist: watchdog>=4.0.0; extra == 'watch'
-Description-Content-Type: text/markdown
-
 # AgentPack
 
 [![PyPI version](https://img.shields.io/pypi/v/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
+[![npm version](https://img.shields.io/npm/v/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
+[![npm downloads](https://img.shields.io/npm/dm/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
 [![Python versions](https://img.shields.io/pypi/pyversions/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
 [![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.1).** 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.
+> **Status: alpha (v0.3.4).** 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.
 >
-> **Platform note:** macOS and Linux are fully supported. Windows support is not yet implemented (git hooks use POSIX shell; the Claude Code session hooks use `python3`/`rm -f`). Contributions welcome.
+> **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.
 
 **Local context engine for AI coding agents.**
 
-AgentPack builds task-focused context packs for Claude Code, Cursor, Windsurf, Codex, Antigravity, CI jobs, and any LLM workflow that can read markdown. It scans your repo locally, ranks files for the task, compresses the result into a token budget, and keeps the pack fresh through CLI commands, MCP tools, hooks, and agent integrations.
+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 relevant files for a task, and packages them into compact task-focused context packs for CLI and MCP tool workflows.
 
-AgentPack is useful when a repo is too large to paste, but a blank agent session wastes time rediscovering the same code structure. It is a context preparation tool, not a coding agent.
+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, keeps the product boundary explicit, and is a context preparation tool, not a coding agent.
 
 ## Contents
 
@@ -60,6 +23,7 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 - [Install](#install)
 - [Quickstart](#quickstart)
 - [Quality Bar](#quality-bar)
+- [Download Stats](#download-stats)
 - [Debugging Selection](#debugging-selection)
 - [Supported Integrations](#supported-integrations)
 - [Commands](#commands)
@@ -70,8 +34,9 @@ AgentPack is useful when a repo is too large to paste, but a blank agent session
 
 ## Features
 
-- **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, and repo history.
+- **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, repo history, and deterministic offline summaries.
 - **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
+- **Local code intelligence**: extracts roles, domains, entrypoints, definitions, dependencies, env reads, side effects, and external systems using static analysis.
 - **Semantic repo map**: adds a compact module-level map before file context so agents orient faster.
 - **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, and stale-context warnings.
 - **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
@@ -105,6 +70,27 @@ sudo pacman -S python-pipx
 pipx ensurepath
 ```
 
+If `pipx` is not installed yet:
+
+```bash
+# macOS
+brew install pipx
+
+# Ubuntu/Debian
+sudo apt install pipx
+
+# Fedora
+sudo dnf install pipx
+
+# Arch
+sudo pacman -S python-pipx
+
+# Then ensure pipx apps are on PATH
+pipx ensurepath
+```
+
+`pipx` is the recommended default because it keeps the CLI isolated and avoids many macOS/Linux global `pip install` issues, including PEP 668 `externally-managed-environment` errors. If you prefer `pip`, install inside a virtual environment.
+
 JavaScript-heavy teams can install the npm wrapper:
 
 ```bash
@@ -112,7 +98,7 @@ npm install -g @vishal2612200/agentpack
 agentpack --version
 ```
 
-The npm package is a Node launcher around the Python implementation. It requires Node.js 18+ and Python 3.10+, then installs the matching core `agentpack-cli` package into a per-version virtual environment on first run. The Python package remains the source of truth; npm is the convenience install path for JavaScript-heavy teams. Use the PyPI extras below when you need optional `watch` or `mcp` dependencies.
+The npm package is a Node launcher around the Python implementation. It requires Node.js 18+ and Python 3.10+, then installs the matching core `agentpack-cli` package into a per-version virtual environment on first run. The Python package remains the source of truth; npm is the convenience install path for JavaScript-heavy teams. See the [npm README](https://github.com/vishal2612200/agentpack/blob/main/npm/README.md) for wrapper cache controls and troubleshooting. Use the PyPI extras below when you need optional `watch` or `mcp` dependencies.
 
 ## Quickstart
 
@@ -183,6 +169,24 @@ ItsDangerous, and MarkupSafe by checking out each commit's parent and scoring
 against files actually changed by the commit. Synthetic fixtures are useful
 regression tests, but should not be presented as market proof.
 
+## Download Stats
+
+npm exposes official package download counts through its public registry API and the npm downloads badge above:
+
+```bash
+curl https://api.npmjs.org/downloads/point/last-month/%40vishal2612200%2Fagentpack
+curl https://api.npmjs.org/downloads/point/last-week/%40vishal2612200%2Fagentpack
+```
+
+PyPI does not show official project download counts on package pages. For rough trend data on the Python core package, use third-party mirrors:
+
+```bash
+curl https://pypistats.org/api/packages/agentpack-cli/recent
+```
+
+- PyPI Stats: <https://pypistats.org/packages/agentpack-cli>
+- pepy.tech: <https://pepy.tech/project/agentpack-cli>
+
 ## Debugging Selection
 
 When AgentPack misses a file, the next command should explain the miss:
@@ -541,7 +545,7 @@ agentpack global-install --agent antigravity   # Antigravity
 
 What it does:
 - **Git template hooks** (`~/.git-templates/hooks/`) — git copies these into every repo on `git init` / `git clone`. On `post-commit`, `post-merge`, `post-checkout`: silently repacks **only if `.agentpack/config.toml` exists** — no-op in repos that haven't opted in.
-- **Shell cd hook** (`~/.zshrc` or `~/.bashrc`) — on `cd`, repacks if stale **only in opted-in repos**. Never touches repos without `.agentpack/config.toml`. Never auto-inits.
+- **Shell cd hook** (`~/.zshrc`, `~/.bashrc`, or the PowerShell profile on Windows) — on `cd` or prompt refresh, repacks if stale **only in opted-in repos**. Never touches repos without `.agentpack/config.toml`. Never auto-inits.
 - **Agent config** — same agent-specific files that `agentpack init --agent <x>` or `agentpack install --agent <x>` writes for the current project.
 
 All changes are idempotent, reversible, and non-destructive. Existing hooks and rc files are appended to, never overwritten. Repos you haven't explicitly run `agentpack init` in are never touched.
@@ -787,8 +791,12 @@ Uses `watchdog` if installed, falls back to polling. Context is refreshed whenev
 Install watchdog for better performance:
 ```bash
 pipx inject agentpack-cli watchdog
+PIPX_AGENTPACK="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
+"$PIPX_AGENTPACK" watch
 ```
 
+Use the explicit `pipx` binary path above if you also have the npm wrapper on `PATH`; otherwise `agentpack watch` may still resolve to the Node launcher.
+
 ---
 
 ### `agentpack claude`
@@ -809,9 +817,12 @@ Run AgentPack as an MCP server — exposes context packing as tools that Claude
 
 ```bash
 pipx inject agentpack-cli "agentpack-cli[mcp]"
-agentpack mcp
+PIPX_AGENTPACK="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
+"$PIPX_AGENTPACK" mcp
 ```
 
+Use the explicit `pipx` binary path above if you also have the npm wrapper on `PATH`; otherwise `agentpack mcp` may still resolve to the Node launcher instead of the extras-enabled Python CLI.
+
 Register in Claude Code settings (`~/.claude/settings.json`):
 
 ```json
@@ -1230,7 +1241,8 @@ Works like `.gitignore`. Default rules exclude:
           │                                         │
           │  Summary cache  ── role, imports,       │
           │  (offline)        symbols, side effects, │
-          │                   public API, errors     │
+          │                   public API, naming     │
+          │                   signals, errors        │
           │                                         │
           │  Import graph  ──  Python AST           │
           │  (6 languages)  ─  JS/TS regex          │
@@ -1243,6 +1255,9 @@ Works like `.gitignore`. Default rules exclude:
           │  ast.get_source_segment)   classes,     │
           │                    ── arrow fns w/ =>)  │
           │                                         │
+          │  Naming signals ── public files/symbols │
+          │                  ── env/config/test ids │
+          │                  ── generic-name hints  │
           │  Test detection  ── name heuristics     │
           │  Task keywords   ── stopwords + variants│
           │                  ── concept synonyms    │
@@ -1268,6 +1283,7 @@ Works like `.gitignore`. Default rules exclude:
           │   +70 symbol    +60 content match       │
           │   +50 dep       +40 rev-dep             │
           │   +35 test      +25 config  +20 recent  │
+          │   +20 naming    -6 generic public API   │
           │   -50 large unrelated                   │
           │  History noise penalty from metrics     │
           └────────────────────┬────────────────────┘
@@ -1355,14 +1371,15 @@ src/agentpack/
     rust_imports.py            # use, mod, extern crate
     java_imports.py            # Java import + Kotlin import
     symbols.py                 # AST symbols + body via ast.get_source_segment
+    naming_signals.py          # public-name classification for summaries + ranking boosts
     tests.py                   # source → test file mapping heuristics
-    ranking.py                 # keyword extraction, concept synonyms, scoring
+    ranking.py                 # keyword extraction, concept synonyms, scoring, naming receipts
     monorepo.py                # workspace detection + workspace ownership helpers
     repo_map.py                # compact semantic repo map reserved inside token budget
     task_classifier.py         # coarse task class for freshness/rendering/scoring context
 
   summaries/
-    offline.py                 # zero-API: AST/regex → imports, symbols, role, side effects, API, errors
+    offline.py                 # zero-API: AST/regex → imports, symbols, role, side effects, API, naming signals, errors
     base.py                    # cache-or-build orchestration (parallel, ThreadPool+ProcessPool)
 
   adapters/                    # context rendering only — no installation logic
@@ -1457,7 +1474,7 @@ src/agentpack/
 
 ## Known limitations
 
-- **Windows**: not supported. Git hooks use POSIX shell (`#!/bin/sh`, `>/dev/null 2>&1 &`). The Claude Code session hooks use `python3` and `rm -f`. Contributions welcome.
+- **Windows**: supported with PowerShell plus Git for Windows. AgentPack installs cross-platform Git hook launchers and a PowerShell profile hook for opted-in repos. `cmd.exe` is not a first-class workflow yet.
 - **Monorepos**: workspace-aware ranking supports npm/pnpm, Cargo, and `go.work` layouts. `--workspace` creates filtered per-workspace outputs. Package dependency hints currently come from npm/pnpm `package.json`; Cargo/Go workspace membership is detected, but package-manager dependency edges for Cargo/Go are not yet modeled.
 - **Public benchmark proof**: `benchmarks/public-repos.toml` is a curated smoke suite over real public commits, and `benchmarks/results/2026-05-15-public.md` records the current proof run. Treat it as a floor, not a leaderboard; expand cases before broad external claims.
 - **Symbol extraction**: Python (AST, full) and JavaScript/TypeScript (regex, arrow functions + classes) are well-supported. Go, Rust, Java, Kotlin have import graph traversal but no symbol extraction — they fall back to file-level summaries.
@@ -1492,6 +1509,16 @@ pipx inject agentpack-cli "agentpack-cli[all]"  # watch + mcp
 
 ## Development
 
+## Public Naming And Ranking
+
+AgentPack works better when public surfaces carry domain context. Prefer domain-revealing names for files, exported functions/classes, CLI commands, tests, and config/env identifiers.
+
+- `verify_otp` is better than `handle`
+- `StripeWebhookHandler` is better than `Processor`
+- `session_token_expiry_test` is better than `test_flow`
+
+This is guidance, not a lint rule. Local variable names are out of scope for AgentPack ranking.
+
 Clone and run locally:
 
 ```bash
@@ -1519,7 +1546,7 @@ For npm publish, configure GitHub secret `NPM_TOKEN`. The token must publish to
 Good contribution areas:
 
 - More real-world benchmark fixtures and public repo eval cases
-- Windows support for hooks and session integrations
+- Better Windows ergonomics beyond the supported PowerShell + Git for Windows path
 - Better symbol extraction for Go, Rust, Java, and Kotlin
 - More precise import/dependency resolution for framework-heavy repos
 - Ranking regressions with `expected_files` cases that reproduce misses

{agentpack_cli-0.3.1 → agentpack_cli-0.3.4}/pyproject.toml

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

{agentpack_cli-0.3.1 → agentpack_cli-0.3.4}/src/agentpack/__init__.py

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