🧰 agent-stack

One command. Everything set up. Activated. Measured.

A skills-first optimization toolkit for Claude Code (+ Cursor) that takes any repo from zero to a fully optimized, token-efficient agent setup — in under two minutes.

npx @drmahdikazempour/agent-stack init --all

🤖 Paste this into Claude Code

Copy the block below into a Claude Code session at the root of any repo. It installs and activates the full stack, audits the result, baselines token usage, and pushes to main — all in one go.

Set up agent-stack in this repo and ship it. Do all of the following:

1. INSTALL + ACTIVATE the full stack:
   npx -y @drmahdikazempour/agent-stack@latest init --all --yes
   This detects the host, installs the external tools (rtk, code-review-graph,
   graphify, caveman, claude-handoff, gbrain) over the built-in fallbacks,
   generates CLAUDE.md + AGENTS.md with the tool coordinator, wires the hooks,
   and captures a token baseline. If any tool prints "Finish installing"
   guidance (missing toolchain), run that command for me, then continue.

2. AUDIT + LINT the result and summarize:
   npx @drmahdikazempour/agent-stack audit
   npx @drmahdikazempour/agent-stack doctor
   Report the CLAUDE.md token budget, skill/MCP budgets, hook conflicts, and
   which tools are available vs absent.

3. TRACK TOKEN USAGE — explain how it works and show the baseline:
   npx @drmahdikazempour/agent-stack measure --since 7d
   Tell me the baseline tokens/day, where usage is logged
   (.agent-stack/usage.jsonl), and that I should re-run measure after ~a week
   to see the % reduction. The Stop hook logs ccusage every turn automatically.

4. COMMIT + PUSH TO MAIN:
   Stage the generated files, commit with a clear message, and push to main.
   If I'm on a feature branch, open a PR and merge it to main instead.
   Then confirm CI is green.

Walk me through each step's output as you go, and stop to ask me only if a
step genuinely needs my input (e.g. a missing toolchain you can't install).

Tip: prefer init --all (full stack). For a lighter setup, replace step 1 with plain npx -y @drmahdikazempour/agent-stack@latest init --yes.

📖 Table of contents

• Paste this into Claude Code
• Why agent-stack
• Quick start
• How init works
• Built-in token cutters
• Profiles
• Command reference
• Architecture
• How it cuts tokens
• Measuring savings
• Development
• Roadmap
• FAQ
• References

💡 Why agent-stack

The Claude token-optimization ecosystem is fragmented into single-layer point tools — shell-output compressors, context graphs, output styles, measurement, continuity. None of them compose. Setting up a repo today means hand-picking 5–10 tools, reading each install doc, hand-merging hooks, hand-writing CLAUDE.md, mirroring to Cursor, and measuring savings yourself.

[!NOTE] agent-stack does it in one command — and ships the token-cutting machinery built in, so there's nothing fictional to install and nothing to wire by hand.

| Without agent-stack | With agent-stack | | --- | --- | | Hand-pick & install 5–10 tools | npx … init --all | | Hand-write CLAUDE.md | Generated, ≤ 800 tokens, verified | | Manually merge settings.json hooks | Single safe merge, sole writer | | Mirror everything to Cursor by hand | Auto-mirrored, kept in sync | | Guess at savings | Measured with ccusage |

🚀 Quick start

cd your-repo

# Smart defaults (auto-detects host, profile, package manager):
npx @drmahdikazempour/agent-stack init

# …or turn on EVERYTHING at once (max profile):
npx @drmahdikazempour/agent-stack init --all

agent-stack v0.2.0

Detected:
  Host: Claude Code + Cursor
  Repo: TypeScript / Next.js / pnpm
  Profile: max (confidence: high)

Will write:
  20 files → claude, cursor
  .claude/settings.json (2 hooks merged)

Proceed? [Y/n] y

  ✓ Adapters: ccusage(installed)
  ✓ Generated 20 files
  ✓ Wired 2 hooks into settings.json
  ✓ All skills load, all hooks present, CLAUDE.md verified
  ✓ Built code map → .agent-stack/graph.md
  ✓ Baseline: 12,340 tokens/day (ccusage, last 7d avg)

Done.

[!TIP] Install it once globally to get the short agent-stack command everywhere:

npm i -g @drmahdikazempour/agent-stack
agent-stack init --all

⚙️ How init works

One shot, ten steps, fully reversible. --dry-run stops after the plan; --yes skips the single confirm.

  detect ─▶ plan ─▶ confirm ─▶ back up ─▶ install ─▶ generate ─▶ wire hooks
                      │                                                │
            --dry-run ┘ (stop)                                         ▼
                                                                   activate
   summarize ◀── baseline ◀── code map ◀───────────────────────────┘  │
                                                          fails ──▶ roll back

| # | Step | What happens | |---|------|--------------| | 1 | Detect | Host(s), repo type, framework, package manager, existing configs, git state | | 2 | Plan | Prints a one-screen plan (--dry-run stops here) | | 3 | Confirm | A single Proceed? [Y/n] (--yes skips) | | 4 | Back up | Copies any existing config into .agent-stack.bak.<ts>/ | | 5 | Install | ccusage only — everything else is built in | | 6 | Generate | CLAUDE.md, skills, subagents, commands, .claudeignore, Cursor mirror, MCP scaffold | | 7 | Wire hooks | One merged write to .claude/settings.json (sole writer, dedupes, never clobbers yours) | | 8 | Activate | Verifies each skill loads, each hook is present, CLAUDE.md exists — rolls back on failure | | 9 | Code map | Builds the initial .agent-stack/graph.md | | 10 | Baseline | Records a ccusage token snapshot for later comparison |

🔧 Built-in token cutters

These ship inside the package — no external install, nothing fictional. They are what actually reduce tokens:

🗺️ Code map

agent-stack graph refresh        # rebuild .agent-stack/graph.md
agent-stack graph query <symbol> # find where it's defined

A compact index mapping every source file → its exported symbols. The agent greps one small file to find where something lives instead of reading whole directories. Refreshed automatically on SessionStart. Supports TypeScript/JavaScript, Python, Go, and Rust.

# Code map
_142 files, 906 top-level symbols. Grep this to find a symbol before opening source._

- `src/core/detect.ts`: detect
- `src/wire-hooks.ts`: mergeHooks, wireHooks, planHooks, countOurHooks
- …

🗜️ Output compression

npm run build 2>&1 | npx @drmahdikazempour/agent-stack compress

A stdin → stdout filter that strips ANSI codes, folds duplicate lines (line (×42)), and head/tail-elides huge output — ≈ 60 % fewer characters on a 500-line log, so noisy commands cost a fraction of the context.

🪶 Structural savings (always on)

• .claudeignore keeps node_modules, build output, media, and lockfiles out of context.
• CLAUDE.md is generated factual-and-tight — ≤ 800 tokens at startup, verified by doctor.
• Subagents (stack-explorer, stack-reviewer) return conclusions, not file dumps.
• Terse mode (the max profile) enforces minimal-word answers.

🎚️ Profiles

A profile bundles a graph backend + compression + skill set + hook config. init auto-picks one; swap later with profile use.

| Profile | Graph | Compression | Auto-picked when | |---------|-------|-------------|------------------| | 🟢 code (default) | built-in map | built-in | normal code repo | | 🔵 review | built-in map | built-in | > 500 commits and CODEOWNERS | | 🟣 multimodal | built-in map | built-in | ≥ 5 PDFs / video / large images | | 🟡 spec | built-in map | built-in | spec-kit / cc-spex detected | | ⚪ research | none | built-in | --profile research --allow-noncommercial | | 🔴 max | external graph + built-in fallback | built-in + terse + rtk | --all — full external stack on at once |

agent-stack profile use review   # swap & regenerate
agent-stack profile show         # current profile

📟 Command reference

Setup — run once per repo

agent-stack init [--all] [--yes] [--dry-run] [--targets claude,cursor]
                 [--profile <name>] [--no-install] [--allow-noncommercial]
                 [--overwrite] [--force]

Token cutters — standalone, in pipes, or via hooks

agent-stack compress                 # cmd 2>&1 | agent-stack compress
agent-stack graph refresh            # rebuild the code map
agent-stack graph query <term>       # find a symbol / file

Maintenance — post-install, on demand

agent-stack audit                    # token counts + budget report
agent-stack optimize                 # apply audit fixes (with approval)
agent-stack doctor                   # lint everything (exit 1 on issues)
agent-stack measure [--since 7d]     # ccusage baseline vs current
agent-stack profile use <name>       # swap profile; regenerate
agent-stack graph use <name>         # swap to an external graph (if installed)
agent-stack handoff write|resume     # continuity across sessions
agent-stack sync                     # regenerate Cursor mirror from CLAUDE.md
agent-stack uninstall                # restore backup, remove generated files

| Flag | Effect | |------|--------| | --all | Full external stack at once (the max profile): rtk + code-review-graph + graphify + caveman + claude-handoff + gbrain | | --yes | Skip the single confirm prompt | | --dry-run | Print the plan, write nothing | | --targets claude,cursor | Force the host list (Cursor gets the portable subset: rtk + MCP graph tools) | | --profile <name> | Force a profile (code review multimodal spec research max) | | --no-install | Write configs only; print install guidance instead of installing | | --overwrite | Replace existing files instead of merging (still backs up) | | --force | Re-run even if already installed |

🏗️ Architecture

One source of truth, two faces, zero runtime dependencies.

                  @drmahdikazempour/agent-stack
   ┌──────────────────────────────────────────────────────┐
   │  CLI  (src/)                                           │
   │    builtin/    graph (code map) · compress             │
   │    generate/   claude · cursor · mcp                   │
   │    wire-hooks  ← sole writer of settings.json          │
   │    activate    ← verify, or roll back on failure       │
   │  skills/       5 Agent Skills                          │
   └───────────────┬──────────────────────┬────────────────┘
            writes  │               mirrors │
                    ▼                       ▼
         🟠 Claude Code              🔵 Cursor
         CLAUDE.md                   .cursor/rules/*.mdc
         .claude/skills · agents     AGENTS.md
         commands · settings.json
         .claudeignore · graph.md

Skills decide when; the CLI decides how. Skills call the CLI under the hood; you normally run init once and never touch the CLI again.

agent-stack/
├── bin/agent-stack.js          # npx entrypoint
├── src/
│   ├── cli.ts                  # arg parsing + command dispatch
│   ├── constants.ts            # all spec values (token budgets, limits)
│   ├── core/                   # detect · plan · safe-writer · backup · token estimator
│   ├── builtin/                # graph (code map) · compress (output compression)
│   ├── generate/               # claude · cursor · mcp · coordinator file builders
│   ├── adapters/               # registry · detect-tools · install · hooks
│   ├── wire-hooks.ts           # SOLE writer of settings.json hooks
│   ├── activate.ts             # post-write verification chain
│   ├── audit.ts                # token-budget linting
│   └── commands/               # init + maintenance commands
├── skills/                     # 5 Agent Skills (stack-bootstrap, -doctor, …)
├── integrations/               # profiles.json · tools.json
├── templates/                  # generation notes
└── test/                       # vitest: unit · golden · e2e init in a tmpdir

📉 How it cuts tokens

The savings come from changing what enters the context window, not from a black box:

   ❌ Before                          ✅ After (agent-stack)
   ─────────────────────────         ─────────────────────────────────
   read 12 files to find       ──▶   grep graph.md → open 1 file
   one function
   paste a 500-line log        ──▶   pipe through compress → ~60% smaller
   verbose CLAUDE.md +         ──▶   ≤800-token CLAUDE.md + .claudeignore
   node_modules noise

| Lever | Mechanism | Typical effect | |-------|-----------|----------------| | Code map | grep graph.md instead of reading files | fewer, smaller file reads | | Compression | fold/elide large command output | ≈ 60 % fewer chars on big logs | | .claudeignore | exclude junk from context | no node_modules/build noise | | Tight CLAUDE.md | factual root ≤ 800 tokens | lower fixed startup cost | | Subagents | return summaries, not dumps | bounded sub-task context |

📊 Measuring savings

Savings are measured, never claimed — via the neutral ccusage tool.

# init already stored a baseline. After ~a week of work:
agent-stack measure --since 7d

agent-stack measure (since 7d)

  Current:  7,180 input tokens/day  (ccusage)
  Baseline: 12,340 input tokens/day (captured 2026-05-24)

  −41.8% input-token reduction vs baseline (target ≥ 40%)

🛠️ Development

git clone https://github.com/drmahdikazempour/agent-stack
cd agent-stack
npm install

npm run build        # tsup → dist/ (ESM + CJS + d.ts)
npm test             # vitest: unit + golden + e2e init in a tmpdir
npm run typecheck
node bin/agent-stack.js doctor --skills-only   # lint shipped skills

[!IMPORTANT] CI runs typecheck → build → skill lint → tests → a license guard (fails if src/ imports a non-permissive adapter). Publishing is tag-triggered and idempotent (skips if the version is already on npm). Releases use Changesets.

🗺️ Roadmap

• [x] v0.1 — one-shot init, profiles, hook merger, generators, 5 skills, maintenance commands, tests, CI
• [x] v0.2 — built-in code map + output compression, max profile / --all, honest install model, robust publish CI
• [ ] v0.3 — Claude plugin wrapper, real third-party graph adapters auto-detected, deeper optimize codemods
• [ ] future — offline LLMLingua/DSPy compression pass, long-term memory tier

❓ FAQ

No. Only ccusage (the genuine Claude Code usage tool) is auto-installed. Graph and compression are built in. Third-party tools are used only if their real binary is already on your PATH — never installed by name.

No. Everything is backed up to .agent-stack.bak.<ts>/ first, CLAUDE.md is merged, and the hook merger only adds its own entries (tagged + deduped) — your hooks are preserved.

Yes — init is idempotent. A matching prior install is a no-op unless you pass --force.

agent-stack uninstall restores the pre-init backup and removes the generated files.

🙏 Credits & prior art

agent-stack composes a permissive, real tool stack. It vendors none of it — its built-in code map and compression are original MIT code that act as the fallback when a tool isn't installed. Every integrated tool is MIT or Apache-2.0; nothing non-permissive is wired in. Tools are detected first, then installed via their own toolchains (cargo / uv / pipx / bun / claude plugin), with guidance when a toolchain is missing. Full, transparent attribution with licenses and exact install commands lives in CREDITS.md and integrations/tools.json.

The max profile (init --all) activates, all at once:

| Tool | License | Integration | Job | |---|---|---|---| | ccusage | MIT | npm binary | Token-usage measurement (always on) | | rtk | Apache-2.0 | PATH binary | Command proxy — cut heavy command output 60-90% | | code-review-graph | MIT | MCP server | Primary code map (graph with edges + impact radius) | | graphify | MIT | CLI / skill | Knowledge graph for whole-repo, multi-file-type questions | | caveman | MIT | Claude Code plugin | Terse-output mode | | claude-handoff | MIT | Claude Code plugin | Session continuity (/handoff:*) | | gbrain | MIT | Bun CLI / plugin | Persistent cross-session memory |

The generated CLAUDE.md and AGENTS.md carry a tool coordinator that routes each job to the right tool, with the built-ins named as the explicit fallback. Cursor gets only the portable subset (rtk + the MCP/CLI graph tools). Inspiration (not integrated): claude-token-optimizer, superpowers, vercel-labs/skills, gstack.

🔗 References

• 📦 npm — @drmahdikazempour/agent-stack
• 🐙 GitHub — drmahdikazempour/agent-stack
• 🙏 Credits — CREDITS.md
• 📚 Claude Code docs — docs.anthropic.com/claude-code
• 🤖 Agent Skills — Claude Agent Skills
• 📐 Cursor rules — docs.cursor.com
• 📊 ccusage — github.com/ryoppippi/ccusage

MIT licensed · Built for people who'd rather ship than wire configs.

Made with Claude Code.