@vishal2612200/agentpack 0.2.2 → 0.3.1

package/README.md

@@ -1,33 +1,102 @@
-# AgentPack npm wrapper
+# AgentPack
 
 Task-aware context packing for AI coding agents.
 
-This npm package is a thin wrapper around the Python package
-[`agentpack-cli`](https://pypi.org/project/agentpack-cli/). On first run it:
+AgentPack scans a repository locally, ranks the files that matter for the current task, and writes a compact markdown context pack for tools such as Claude Code, Cursor, Windsurf, Codex, Antigravity, CI jobs, and generic LLM workflows.
+
+Use it when the repo is too large to paste, but a blank agent session keeps wasting time rediscovering routes, services, tests, configs, and recent changes.
+
+## What this npm package is
+
+`@vishal2612200/agentpack` is a Node launcher for the Python package [`agentpack-cli`](https://pypi.org/project/agentpack-cli/).
+
+On first run it:
 
 1. Finds Python 3.10+.
-2. Creates a per-version virtual environment under your user cache directory.
-3. Installs the matching PyPI package version.
-4. Proxies all arguments to the real `agentpack` CLI.
+2. Creates a per-version virtual environment in your user cache directory.
+3. Installs the matching `agentpack-cli` version from PyPI.
+4. Proxies every command to the real `agentpack` CLI.
+
+The Python CLI remains the source of truth. The npm package exists so JavaScript-heavy teams can install AgentPack with the toolchain they already use. This wrapper installs the core CLI; optional Python extras such as `watch` and `mcp` are documented below.
+
+## Install
 
 ```bash
 npm install -g @vishal2612200/agentpack
-agentpack quickstart --task "fix auth token expiry"
+agentpack --version
 ```
 
-## Requirements
+Requirements:
 
 - Node.js 18+
 - Python 3.10+
 - macOS or Linux
 
-Windows is not supported by AgentPack yet. Use WSL or install the Python package
-directly inside a Linux environment.
+Windows is not supported directly yet. Use WSL, or install `agentpack-cli` inside a Linux environment.
+
+## First project
+
+```bash
+cd your-project
+agentpack init --agent codex
+printf '%s\n' "fix auth token expiry" > .agentpack/task.md
+agentpack pack
+```
+
+Use the agent that matches your editor or CLI:
+
+```bash
+agentpack init --agent claude
+agentpack init --agent cursor
+agentpack init --agent windsurf
+agentpack init --agent codex
+agentpack init --agent antigravity
+```
+
+`agentpack init` creates local `.agentpack/` state and installs the selected integration when supported. `agentpack pack` reads `.agentpack/task.md`, ranks relevant files, and writes the adapter-specific context output.
+
+For a guided setup:
+
+```bash
+agentpack quickstart --task "fix auth token expiry"
+```
+
+## Daily workflow
+
+```bash
+printf '%s\n' "describe the task you are about to work on" > .agentpack/task.md
+agentpack pack
+agentpack stats
+```
+
+## Useful commands
+
+```bash
+agentpack status
+agentpack doctor --agent all
+agentpack explain --file path/to/file.py
+agentpack benchmark --sample-fixtures --misses
+agentpack repair --agent all
+```
+
+## Optional watch and MCP workflows
+
+The `watch` and `mcp` commands use optional Python dependencies. If you need those workflows today, add the Python extras to a `pipx` install or use a virtual environment. Avoid global `pip3 install` on system-managed Python: many macOS/Linux distributions block it with PEP 668's `externally-managed-environment`.
+
+```bash
+pipx install agentpack-cli
+pipx inject agentpack-cli "agentpack-cli[all]"
+agentpack watch
+agentpack mcp
+```
+
+Install `pipx` with your OS package manager first if needed: `brew install pipx`, `sudo apt install pipx`, `sudo dnf install pipx`, or `sudo pacman -S python-pipx`; then run `pipx ensurepath`.
+
+The npm wrapper still works well for the core setup, pack, status, doctor, explain, repair, and benchmark commands.
 
 ## Python selection
 
-By default, the wrapper tries `python3` and then `python`. To force a specific
-interpreter:
+By default, the wrapper tries `python3` and then `python`. To force a specific interpreter:
 
 ```bash
 AGENTPACK_PYTHON=/opt/homebrew/bin/python3 agentpack --version
@@ -47,12 +116,48 @@ or, if `XDG_CACHE_HOME` is unset:
 ~/.cache/agentpack-npm/<version>/
 ```
 
-Override with:
+Override the cache path with:
 
 ```bash
 AGENTPACK_NPM_CACHE_DIR=/tmp/agentpack-cache agentpack --version
 ```
 
-## Upstream
+To force a clean reinstall of the Python CLI for this npm package version, remove the matching cache directory and run `agentpack --version` again.
+
+## Troubleshooting
+
+`agentpack npm wrapper: Python >=3.10 is required.`
+
+Install Python 3.10+ or set `AGENTPACK_PYTHON=/path/to/python3`.
+
+`failed to install agentpack-cli==<version>`
+
+Check that Python can reach PyPI. Corporate networks may need standard package index or proxy configuration. Avoid global `pip3 install` on system-managed Python; many macOS/Linux distributions block it with PEP 668's `externally-managed-environment`. Use `pipx` or a virtual environment for direct Python installs.
+
+Optional Python `watch` and `mcp` extras can be added to a `pipx` install:
+
+```bash
+pipx install agentpack-cli
+pipx inject agentpack-cli "agentpack-cli[all]"
+```
+
+Install `pipx` with your OS package manager first if needed: `brew install pipx`, `sudo apt install pipx`, `sudo dnf install pipx`, or `sudo pacman -S python-pipx`; then run `pipx ensurepath`.
+
+`agentpack: command not found`
+
+Make sure your global npm bin directory is on `PATH`:
+
+```bash
+npm bin -g
+```
+
+## Security and privacy
+
+AgentPack scans, summarizes, ranks, and packs locally. It does not call an LLM API for the core pack flow. Context files are written into your repository under `.agentpack/` and integration-specific local files.
+
+## Links
 
-Full docs: <https://github.com/vishal2612200/agentpack>
+- Full docs: <https://github.com/vishal2612200/agentpack>
+- PyPI package: <https://pypi.org/project/agentpack-cli/>
+- npm package: <https://www.npmjs.com/package/@vishal2612200/agentpack>
+- Issues: <https://github.com/vishal2612200/agentpack/issues>

package/bin/agentpack.js

@@ -6,7 +6,7 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 
-const PACKAGE_VERSION = "0.2.2";
+const PACKAGE_VERSION = "0.3.1";
 const PYPI_PACKAGE = `agentpack-cli==${PACKAGE_VERSION}`;
 
 function compareVersions(left, right) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vishal2612200/agentpack",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Task-aware context packing for AI coding agents. npm wrapper for the Python AgentPack CLI.",
   "license": "MIT",
   "homepage": "https://github.com/vishal2612200/agentpack#readme",