getting started · 01Install

Pakka is a Claude Code plugin. It piggybacks on your existing Claude Code auth, so there are no API keys to provision and no service to run.

# inside any Claude Code session
$ /plugin marketplace add amargautam/pakka-marketplace
$ /plugin install pakka@pakka-marketplace

✓ installed · zero-config · uses claude code auth

Verify the install by running /pakka with no arguments — you should see the harness summary with the shipped badge.

First run

From a Claude Code session inside any repo, type a feature request as you normally would. Pakka watches the conversation and auto-invokes the relevant primitives.

> add rate limiting to /webhook endpoint

  ⟶ /pakka:plan   PRD published to issue #47
  ⟶ /pakka:review   reviewer + security + architect + performance queued
  ⟶ ✗ blocked.     2 fixes proposed

Auth & permissions

Pakka inherits Claude Code's OAuth session. It needs read access to the repo it is run in, and write access to .pakka/ (the local recall store). It does not require any GitHub token unless you opt in to /pakka:plan publishing PRDs to issues.

---

commands · 01/pakka:plan

Design hub. Infers mode from context — writes a spec, challenges your plan, probes assumptions, or slices into tickets. Always writes to docs/specs/. Never chains to build automatically.

Modes

Signal	Mode	What it does
"design X", "we need to", "add feature"	spec	Full design session → spec file in docs/specs/
"challenge this", "poke holes"	challenge	Cross-examines plan against decisions + existing code
"probe me", "what am I missing"	probe	One targeted question per turn until all branches resolved
"break into tickets", "slice this"	slice	Decomposes spec into vertical slices, publishes as GitHub issues

Usage

> /pakka:plan                  # infers mode from context
> /pakka:plan add rate limiting # explicit feature description

commands · 02/pakka:build

Implementation hub. Checks for a spec in docs/specs/ before starting. Infers TDD, debug, map, or audit mode from context.

Modes

Signal	Mode	What it does
"write tests", "TDD", "test first"	tdd	One failing test → minimal code → repeat. Vertical slices only.
"broken", "failing", "debug", "fix this bug"	debug	Reproduce failure first. No fixes without a signal.
"how does X work", "explain this module"	map	Map all callers + dependencies before touching anything.
"coupling", "hard to test", "refactor"	audit	Find shallow modules. Produce refactor proposal. User approves before changes.

commands · 03/pakka:review

Quality gate hub. Runs reviewer + security + architect + performance against the current diff. Returns a verdict and zero or more findings. Also handles incoming review feedback and branch landing.

Usage

> /pakka:review                        # verify + review staged diff
> /pakka:review --base=main            # diff against base branch
> /pakka:review --spec docs/specs/x.md # use specific spec file
> /pakka:review --receive              # handle incoming reviewer feedback
> /pakka:review --finish               # structured branch landing
> /pakka:review --install-hook         # install commit-gate hook

Exit codes

Code	Meaning
0	All reviewers passed; ship.
2	Blocking findings or infra error.

commands · 04/pakka:recall

Query the local audit trail with a natural-language question. Searches the FTS5 index over all session entries. Returns matching turns with citations.

> /pakka:recall                        # last 10 entries
> /pakka:recall why redis              # natural language query
> /pakka:recall idempotency key shape  # any free-form text

commands · 05/pakka:compress

Set or read the compression level. No argument shows current status.

> /pakka:compress               # show current level + stats
> /pakka:compress super-ultra   # default
> /pakka:compress strict        # conservative
> /pakka:compress lite          # minimal
> /pakka:compress restore       # restore .original.md backups

commands · 06/pakka:setup

One-time init. Detects stack, applies permissions overlay, installs the status-line wrapper, writes statusLine block to ~/.claude/settings.json.

> /pakka:setup         # full init
> /pakka:setup guard   # install commit guard hook only

commands · 07/pakka:triage

Issue triage hub. Classifies issues, reproduces bugs, writes agent briefs, manages the issue workflow. Takes an issue number, or blank to show the queue.

> /pakka:triage        # show the queue
> /pakka:triage 47     # triage a specific issue

commands · 08/pakka:help

Shows pakka status — what's on, what you can run.

> /pakka:help          # status + available commands

---

configuration · 01Config files

Pakka has no project-level config file. Settings are stored in two locations:

Path	What it stores
~/.config/pakka/config.json	Default compression level (defaultLevel)
~/.claude/.pakka-level	Per-session level override (written by /pakka:compress)
$CLAUDE_PLUGIN_DATA/recall.db	Recall FTS5 index (survives plugin updates)

# ~/.config/pakka/config.json
{
  "defaultLevel": "super-ultra"
}

Modes

The defaultLevel dial governs how aggressively compress condenses the conversation. See the compress page for token math; /pakka:compress for runtime overrides.

Mode	Reduction	When to use
lite	~27%	Near-zero behavioural change; short sessions.
strict	~33%	Trims tool output noise; recommended default.
ultra	~55%	Turn-level summarization; sessions over six turns.
super-ultra	~66%	Default. Long sessions, decisions auto-extracted.

Recall storage

Recall indexes everything automatically at session end. The FTS5 database lives at $CLAUDE_PLUGIN_DATA/recall.db — it survives plugin reinstalls and does not need to be in your repo. Query it any time with /pakka:recall.

---

reference · 01Exit codes

Code	Source	Meaning
0	any	OK / review passed.
2	review	Blocking finding(s) or infra timeout.

reference · 02Env vars

Var	Set by	Used for
CLAUDE_PLUGIN_ROOT	Claude Code	Path to installed plugin; pakka uses it to invoke bin/run
CLAUDE_PLUGIN_DATA	Claude Code	Plugin-local persistent storage; recall DB lives here
CLAUDE_CONFIG_DIR	Claude Code	Claude config directory; compression level flag stored at .pakka-level

reference · 03Troubleshooting

Review keeps timing out

The architect agent is the slowest of the four; large repos can push it past the default timeout. If review consistently times out, check that pakka-core binary is reachable via ${CLAUDE_PLUGIN_ROOT}/bin/run and your repo is within a git worktree.

Recall returns nothing

The index runs automatically at each session end. If you have entries from earlier sessions that aren't surfacing, start a new session — the SessionEnd hook will reindex. If the DB is missing entirely, run /pakka:recall once to trigger a fresh index.

Compress is too aggressive

Drop the mode to lite with /pakka:compress lite.