Kamma

A lightweight plan-do-review-finalize process for your CLI agents.

Supported Tools

Claude Code, Antigravity (IDE + agy CLI), OpenCode, Kilo Code, Codex CLI, Qwen Code

Gemini CLI was removed — Google is sunsetting it for consumer tiers (free, Google AI Pro/Ultra) on 18 June 2026 in favour of Antigravity; Standard and Enterprise subscriptions continue past that date. Install Antigravity (or the agy CLI) and Kamma syncs to it automatically.

Quick Install

Mac/Linux:

curl -sSL https://raw.githubusercontent.com/bdhrs/kamma/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/bdhrs/kamma/main/install.ps1 | iex

Downloads the latest version to ~/kamma and syncs to all installed AI tools. Re-run any time to update.

Requires uv. If missing, the script will prompt to install it, or install it automatically if run in a non-interactive (e.g. agent) environment.

Manual & Agent Install

If you have cloned this repository or want to run setup automatically via an AI agent, use the commands below.

# Optional: Ensure uv is installed (runs non-interactively)
command -v uv &>/dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# Sync prompt configs to all supported tools.
# Use --create to force-create the tool folders if they don't exist yet.
./sync.sh --create

Alternatively with just:

just sync --create

The sync tool copies the prompts to each supported AI tool's config directory. If --create is omitted, unsupported or missing/unstarted tools are skipped.

Commands

Command	Description
/kamma	Plan, do, review, and finalize a thread in a single run
/kamma:quick	Same single run for a small change — no spec or plan files
/kamma:0-setup	Scaffold a project with project.md, tech.md, workflow.md
/kamma:1-plan	Create a new thread (feature, bug fix, chore) with spec + plan
/kamma:loop	Create a standing loop thread for repeated cycles of work
/kamma:2-do	Work through the selected thread, or run one loop cycle
/kamma:3-review	Review finished work or a loop cycle, ideally in a fresh tool or session
/kamma:4-finalize	Finish a reviewed thread or completed loop, update docs, and clean up
/kamma:5-status	Show where things stand across all threads
/kamma:improve	Consolidate recurring lessons across repos into kamma framework improvements

Workflow

Standard

1. /kamma:0-setup — initialize Kamma in your project
2. /kamma:1-plan — create a thread spec and implementation plan
3. /kamma:2-do — implement until ready for review
4. /kamma:3-review — review, ideally in a fresh session or different tool
5. /kamma:4-finalize — mark complete, update docs, clean up

/kamma

/kamma runs the full cycle in a single session. It stops twice: to confirm the plan, and to ask you to test. If testing passes, it reviews and finalizes automatically.

/kamma:quick

/kamma:quick is the lightweight sibling for small, self-contained changes. It runs the same single session with the same two stops, review, detailed commit message, and reflect step — but skips the spec.md/plan.md files and thread directory. Reach for it when the change fits in your head; use /kamma when it needs a durable spec or spans multiple phases.

Loop threads

For ongoing work that runs in repeated cycles (issue triage, exporter analysis, log monitoring) rather than finishing once, use /kamma:loop. It plans a standing thread whose spec.md and plan.md stay stable while work advances through cycles:

1. /kamma:loop — define the loop's domain, scope, validation standards, and completion condition
2. /kamma:2-do — run one cycle: Report → Analyze → Approval (HARD STOP) → Implement → Validate
3. /kamma:3-review — review the latest cycle; the loop stays open
4. Repeat 2-do/3-review per cycle; /kamma:4-finalize only when you declare the loop complete

Each cycle is recorded in the thread's cycles/ directory, and a curated learnings.md carries lessons forward between cycles. Every cycle stops for explicit approval before any source edits.

Antigravity

Antigravity is served two ways, and a single just sync installs both (detected when ~/.gemini/antigravity or ~/.gemini/antigravity-cli exists):

• Skills → ~/.gemini/skills/. Read by both the Antigravity IDE and the agy CLI (whose / menu lists skills). kamma/ is the full single-run cycle; each step is its own skill (kamma-1-plan/, kamma-2-do/, …), so they show up as /kamma, /kamma-1-plan, /kamma-3-review, … and auto-activate semantically.
• Workflows → ~/.gemini/antigravity/global_workflows/. The same /kamma-* slash commands for the IDE (the agy CLI uses skills, not workflows).

All paths live under ~/.gemini on macOS, Linux, and Windows (%USERPROFILE%\.gemini).

Development

If you are contributing to Kamma, please install the pre-commit hooks to ensure code quality:

uv tool install pre-commit
pre-commit install

The hooks run Ruff (lint + format) and Pyright on staged Python files. Both tools are pinned in the project's dev dependencies and run via uv run, so the same versions are used everywhere.

---

Kamma is a Pāḷi word for action, work, doing.

Inspired by Conductor.