@vishal2612200/agentpack 0.3.1 → 0.3.4

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 (3) hide show
  1. package/README.md +72 -12
  2. package/bin/agentpack.js +13 -17
  3. package/package.json +17 -7
package/README.md CHANGED
@@ -1,10 +1,32 @@
1
1
  # AgentPack
2
2
 
3
- Task-aware context packing for AI coding agents.
3
+ [![npm version](https://img.shields.io/npm/v/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@vishal2612200/agentpack.svg)](https://www.npmjs.com/package/@vishal2612200/agentpack)
5
+ [![PyPI core](https://img.shields.io/pypi/v/agentpack-cli.svg)](https://pypi.org/project/agentpack-cli/)
6
+ [![CI](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml/badge.svg)](https://github.com/vishal2612200/agentpack/actions/workflows/ci.yml)
4
7
 
5
- 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.
8
+ > **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.
9
+ >
10
+ > **Platform note:** macOS, Linux, and Windows are supported. Windows support targets PowerShell plus Git for Windows.
6
11
 
7
- 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.
12
+ **Local context engine for AI coding agents.**
13
+
14
+ AgentPack analyzes your repo locally, finds the relevant files for a task, and packages compact task-focused context packs for Claude Code, Codex, Cursor, Windsurf, Antigravity, MCP tools and workflows, CI jobs, and other agent workflows.
15
+
16
+ Use it when the repo is too large to paste and you want faster, more consistent context around the files, routes, services, tests, configs, and recent changes that actually matter.
17
+
18
+ This npm package is a launcher and wrapper for the Python CLI [`agentpack-cli`](https://pypi.org/project/agentpack-cli/), giving JavaScript-heavy teams a familiar install path while keeping the Python implementation as the source of truth.
19
+
20
+ AgentPack is a context preparation tool, not a coding agent. It stays local, deterministic, and explainable: no hosted LLM calls, no embeddings, and no vector database for scan, summarize, rank, pack, stats, or benchmark.
21
+
22
+ ## Features
23
+
24
+ - **Task-focused packing**: ranks files from git changes, task terms, symbols, imports, related tests, configs, churn, repo history, and deterministic offline summaries.
25
+ - **Budget-aware compression**: emits `full`, `diff`, `symbols`, `skeleton`, or `summary` views instead of all-or-nothing file dumps.
26
+ - **Local code intelligence**: extracts roles, domains, entrypoints, definitions, dependencies, env reads, side effects, and external systems using static analysis.
27
+ - **Agent integrations**: installs Claude Code, Cursor, Windsurf, Codex, Antigravity, VS Code tasks, git hooks, and MCP configuration.
28
+ - **Freshness and deltas**: records task source, git state, snapshot hashes, selected-file deltas, and stale-context warnings.
29
+ - **Measurable quality**: benchmark expected-file recall, token efficiency, misses, and public smoke suites.
8
30
 
9
31
  ## What this npm package is
10
32
 
@@ -30,9 +52,7 @@ Requirements:
30
52
 
31
53
  - Node.js 18+
32
54
  - Python 3.10+
33
- - macOS or Linux
34
-
35
- Windows is not supported directly yet. Use WSL, or install `agentpack-cli` inside a Linux environment.
55
+ - macOS, Linux, or Windows with PowerShell plus Git for Windows
36
56
 
37
57
  ## First project
38
58
 
@@ -61,6 +81,45 @@ For a guided setup:
61
81
  agentpack quickstart --task "fix auth token expiry"
62
82
  ```
63
83
 
84
+ ## Project scope
85
+
86
+ AgentPack is:
87
+
88
+ - A local context engine for building task-focused packs for AI coding agents.
89
+ - A CLI, MCP server, hook runner, and integration layer.
90
+ - A summary cache, import graph, ranking engine, semantic repo map, and token-budget selector.
91
+ - An eval harness for measuring whether selected files match files you actually changed.
92
+
93
+ AgentPack is not:
94
+
95
+ - A coding agent.
96
+ - A hosted service.
97
+ - A semantic code search engine.
98
+ - A replacement for normal source inspection on critical changes.
99
+ - Proven across a large public benchmark suite yet.
100
+
101
+ ## Quality bar
102
+
103
+ AgentPack is best treated as a ranked starting map. It should reduce repeated orientation work, but the agent and reviewer still own correctness.
104
+
105
+ | Signal | What good looks like |
106
+ |---|---|
107
+ | Token reduction | 90-99% smaller than raw repo text on large repos |
108
+ | Pack size | Usually 8k-25k tokens for a specific task |
109
+ | Pack time | Seconds on a warm cache; first summarize pass is slower |
110
+ | Recall | Expected files appear near the top; validate with `agentpack benchmark --misses` |
111
+ | Precision | Good enough to reduce exploration; summaries and repo maps may still include noise |
112
+ | Freshness | Stale packs are clearly marked by task, git, and snapshot checks |
113
+
114
+ Use real repo evals instead of trusting compression numbers:
115
+
116
+ ```bash
117
+ agentpack benchmark --init
118
+ # add historical tasks and files actually changed
119
+ agentpack benchmark --compare --misses --public-table
120
+ agentpack benchmark --public-repos --prove-targets --misses --public-table
121
+ ```
122
+
64
123
  ## Daily workflow
65
124
 
66
125
  ```bash
@@ -86,17 +145,18 @@ The `watch` and `mcp` commands use optional Python dependencies. If you need tho
86
145
  ```bash
87
146
  pipx install agentpack-cli
88
147
  pipx inject agentpack-cli "agentpack-cli[all]"
89
- agentpack watch
90
- agentpack mcp
148
+ PIPX_AGENTPACK="$(pipx environment --value PIPX_BIN_DIR)/agentpack"
149
+ "$PIPX_AGENTPACK" watch
150
+ "$PIPX_AGENTPACK" mcp
91
151
  ```
92
152
 
93
153
  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`.
94
154
 
95
- The npm wrapper still works well for the core setup, pack, status, doctor, explain, repair, and benchmark commands.
155
+ Use the explicit `pipx` binary path above for `watch` and `mcp` so those commands do not resolve back to the npm wrapper on PATH. The npm wrapper still works well for the core setup, pack, status, doctor, explain, repair, and benchmark commands.
96
156
 
97
157
  ## Python selection
98
158
 
99
- By default, the wrapper tries `python3` and then `python`. To force a specific interpreter:
159
+ By default, the wrapper tries the Windows `py -3` launcher on `win32`, then `python3`, then `python`. To force a specific interpreter:
100
160
 
101
161
  ```bash
102
162
  AGENTPACK_PYTHON=/opt/homebrew/bin/python3 agentpack --version
@@ -128,7 +188,7 @@ To force a clean reinstall of the Python CLI for this npm package version, remov
128
188
 
129
189
  `agentpack npm wrapper: Python >=3.10 is required.`
130
190
 
131
- Install Python 3.10+ or set `AGENTPACK_PYTHON=/path/to/python3`.
191
+ Install Python 3.10+ or set `AGENTPACK_PYTHON=/path/to/python3` (or `python.exe` on Windows).
132
192
 
133
193
  `failed to install agentpack-cli==<version>`
134
194
 
@@ -148,7 +208,7 @@ Install `pipx` with your OS package manager first if needed: `brew install pipx`
148
208
  Make sure your global npm bin directory is on `PATH`:
149
209
 
150
210
  ```bash
151
- npm bin -g
211
+ printf '%s/bin\n' "$(npm prefix -g)"
152
212
  ```
153
213
 
154
214
  ## Security and privacy
package/bin/agentpack.js CHANGED
@@ -6,7 +6,7 @@ const fs = require("node:fs");
6
6
  const os = require("node:os");
7
7
  const path = require("node:path");
8
8
 
9
- const PACKAGE_VERSION = "0.3.1";
9
+ const PACKAGE_VERSION = "0.3.4";
10
10
  const PYPI_PACKAGE = `agentpack-cli==${PACKAGE_VERSION}`;
11
11
 
12
12
  function compareVersions(left, right) {
@@ -35,7 +35,8 @@ function fail(message, code = 1) {
35
35
  }
36
36
 
37
37
  function pythonVersion(python) {
38
- const result = run(python, [
38
+ const result = run(python.command, [
39
+ ...python.args,
39
40
  "-c",
40
41
  "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')",
41
42
  ]);
@@ -47,15 +48,16 @@ function pythonVersion(python) {
47
48
 
48
49
  function findPython() {
49
50
  const candidates = [
50
- process.env.AGENTPACK_PYTHON,
51
- "python3",
52
- "python",
51
+ process.env.AGENTPACK_PYTHON ? { command: process.env.AGENTPACK_PYTHON, args: [] } : null,
52
+ process.platform === "win32" ? { command: "py", args: ["-3"] } : null,
53
+ { command: "python3", args: [] },
54
+ { command: "python", args: [] },
53
55
  ].filter(Boolean);
54
56
 
55
57
  for (const candidate of candidates) {
56
58
  const version = pythonVersion(candidate);
57
59
  if (version && compareVersions(version, "3.10") >= 0) {
58
- return { command: candidate, version };
60
+ return { ...candidate, version };
59
61
  }
60
62
  }
61
63
  return null;
@@ -65,7 +67,9 @@ function cacheRoot() {
65
67
  if (process.env.AGENTPACK_NPM_CACHE_DIR) {
66
68
  return process.env.AGENTPACK_NPM_CACHE_DIR;
67
69
  }
68
- const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
70
+ const base = process.platform === "win32"
71
+ ? (process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"))
72
+ : (process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"));
69
73
  return path.join(base, "agentpack-npm", PACKAGE_VERSION);
70
74
  }
71
75
 
@@ -80,12 +84,6 @@ function venvPaths(root) {
80
84
  };
81
85
  }
82
86
 
83
- function ensureSupportedPlatform() {
84
- if (process.platform === "win32") {
85
- fail("Windows is not supported yet. Please use macOS/Linux or install agentpack-cli directly in WSL.");
86
- }
87
- }
88
-
89
87
  function installOrUpdateVenv(systemPython, paths) {
90
88
  const marker = fs.existsSync(paths.marker) ? fs.readFileSync(paths.marker, "utf8").trim() : "";
91
89
  if (marker === PACKAGE_VERSION && fs.existsSync(paths.agentpack)) {
@@ -94,7 +92,7 @@ function installOrUpdateVenv(systemPython, paths) {
94
92
 
95
93
  fs.mkdirSync(path.dirname(paths.marker), { recursive: true });
96
94
 
97
- let result = run(systemPython, ["-m", "venv", paths.venv], { stdio: "inherit" });
95
+ let result = run(systemPython.command, [...systemPython.args, "-m", "venv", paths.venv], { stdio: "inherit" });
98
96
  if (result.status !== 0) {
99
97
  fail(`failed to create Python virtual environment at ${paths.venv}`);
100
98
  }
@@ -126,11 +124,9 @@ function main(argv = process.argv.slice(2)) {
126
124
  return;
127
125
  }
128
126
 
129
- ensureSupportedPlatform();
130
-
131
127
  const python = findPython();
132
128
  if (!python) {
133
- fail("Python >=3.10 is required. Install Python, or set AGENTPACK_PYTHON=/path/to/python.");
129
+ fail("Python >=3.10 is required. Install Python, set AGENTPACK_PYTHON=/path/to/python, or use the Windows py launcher.");
134
130
  }
135
131
 
136
132
  installOrUpdateVenv(python.command, paths);
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@vishal2612200/agentpack",
3
- "version": "0.3.1",
4
- "description": "Task-aware context packing for AI coding agents. npm wrapper for the Python AgentPack CLI.",
3
+ "version": "0.3.4",
4
+ "description": "npm launcher for the Python AgentPack CLI, a local context engine for AI coding agents that ranks relevant files and builds task-focused context packs.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/vishal2612200/agentpack#readme",
7
7
  "repository": {
@@ -28,15 +28,25 @@
28
28
  "node": ">=18"
29
29
  },
30
30
  "keywords": [
31
- "ai",
32
- "cli",
33
- "claude",
31
+ "ai-coding-agents",
32
+ "developer-tools",
33
+ "repo-analysis",
34
+ "context-engine",
35
+ "context-packing",
36
+ "prompt-context",
37
+ "mcp",
38
+ "ci",
39
+ "claude-code",
34
40
  "codex",
35
- "context",
36
41
  "cursor",
42
+ "windsurf",
37
43
  "antigravity",
44
+ "ai",
38
45
  "llm",
46
+ "context",
39
47
  "packing",
40
- "windsurf"
48
+ "claude",
49
+ "npm",
50
+ "cli"
41
51
  ]
42
52
  }