Lean Agent Kit

Persistent context & skills for AI coding agents.

Give your coding agent the context, memory, and skills it needs to be an expert in your codebase, conventions, current work, and hard-won lessons — so it gets productive faster and stays on track. Free and open source forever (MIT).

A small Markdown core plus optional packs for specs, stacks, guardrails, and integrations — only when you enable them. Works with Cursor, Claude Code, Copilot, ChatGPT, Aider, Cline, and other file-reading agents. No account, subscription, or lock-in.

Docs: renatoxm.github.io/leanagentkit · Why Lean Agent Kit?

The problem

Every new session starts cold. The agent does not know your codebase, conventions, what you are working on, or what the last session discovered. It re-searches familiar files, burns context, and can repeat mistakes your team has already solved.

The fix (core)

Lean Agent Kit installs a small, persistent project memory:

| File | Role | | ------------------------------- | ---------------------------------------------- | | AGENTS.md | Project facts, commands, conventions, never-dos | | docs/CODEBASE_MAP.md | Navigation index | | docs/memory/ACTIVE_CONTEXT.md | Current focus + resume note | | docs/memory/LEARNINGS.md | Discoveries & avoidable mistakes → promote to AGENTS.md | | .agent/skills/ | Check, handoff, optional session wrappers, packs |

Map-first, not map-only: start from the map; use narrow search when needed. Do not dump the whole repo to re-orient.

Install

Pin @latest so you do not run a stale cached package.

npm create lean-agent-kit@latest
# or
npx create-lean-agent-kit@latest .
pnpm dlx create-lean-agent-kit@latest .

In a TTY, the CLI runs a guided installer:

1. If Lean Agent Kit is already present — skip update, update, or delete and clean install
2. Empty / freshly cleaned folder — optional framework intent (installs the stacks pack; the agent runs the scaffolder)
3. Multi-select optional packs — ↑/↓ move · Space select/unselect · Enter confirm

Non-TTY / CI installs stay core only (or use flags below). After install, follow the printed agent prompt (usually bootstrap; with a framework intent it points at leanagentkit-scaffold first).

Non-interactive flags

npx create-lean-agent-kit@latest . --with spec,stacks   # packs on first scaffold
npx create-lean-agent-kit@latest . --enable-pack practice
npx create-lean-agent-kit@latest . --upgrade            # additive; preserves memory
npx create-lean-agent-kit@latest . --prune-to-core      # archive pack files; re-enable what you need

Clean install (guided only): warns that all kit files and memories will be removed, then asks whether to back up or permanently delete before reinstalling.

See Migration 1.0.

Workflow sizes

| Size | When | Loop | | --------------- | ----------------- | ------------------------------------------------------------------------- | | Trivial | Typo, rename, Q&A | Just do it | | Normal | Typical coding | Ambient work → check → finalize | | Substantial | New/fuzzy feature | Needs spec pack: grill → new-spec → implement-spec → check → finalize |

Optional packs

| Pack | Purpose | | --------------- | --------------------------------------- | | spec | Grill, specs, implement, ADRs, progress | | stacks | Stack detect + greenfield scaffolders | | practice | Review, debug, TDD, security, … | | architecture | CA/DDD decomposition (needs spec) | | backlog | Backlog.md board sync (needs spec) | | git-lifecycle | Branch/commit/PR offers (needs spec) | | trevor | Reminders / concierge | | caveman | Terse commits & review comments | | authoring | Distill / create project skills | | imaginary | Resize/crop/convert via h2non/imaginary |

Full catalog: Packs.

Honest costs

• Memory stays useful only if ACTIVE_CONTEXT is refreshed on focus/edit milestones (ambient) and finalize runs when packs need PROGRESS/hooks.
• Stale maps hurt; narrow search is allowed and expected.
• More packs → more skills on disk and more ceremony. Prefer core until you feel the gap.

Built-in stack support (stacks pack)

When the stacks pack is installed, detection uses .agent/stacks/registry.md (Cloudflare, Hono, Astro, Svelte, React/Next, Python, Go, Postgres ORMs, …). See Stacks.

Repo layout (this repository)

bin/cli.mjs       # npx entry (zero deps)
template/core/    # default install payload
template/packs/   # opt-in overlays + manifest.json
docs/             # VitePress site (not shipped on npm)

Developing

npm install
node bin/cli.mjs /tmp/test-target
npm test

License

MIT — free and open source forever. Use it, inspect it, adapt it, and share it without paying for access.