Skip to content

README.md

Latest commit

 

History

History
485 lines (356 loc) · 20.4 KB

README.md

File metadata and controls

485 lines (356 loc) · 20.4 KB
Raw

🧰 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.

npm version CI license node zero deps

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

💡 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
What you'll see (click to expand) 
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
init flags in detail
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.

Repository layout 
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

  • v0.1 — one-shot init, profiles, hook merger, generators, 5 skills, maintenance commands, tests, CI
  • 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

Does it install a bunch of random binaries?

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.

Will it clobber my existing CLAUDE.md / settings.json?

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.

Is it safe to run twice?

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

How do I undo it?

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

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

Made with Claude Code.