karimo

██╗  ██╗   █████╗   ██████╗   ██╗  ███╗   ███╗   ██████╗
██║ ██╔╝  ██╔══██╗  ██╔══██╗  ██║  ████╗ ████║  ██╔═══██╗
█████╔╝   ███████║  ██████╔╝  ██║  ██╔████╔██║  ██║   ██║
██╔═██╗   ██╔══██║  ██╔══██╗  ██║  ██║╚██╔╝██║  ██║   ██║
██║  ██╗  ██║  ██║  ██║  ██║  ██║  ██║ ╚═╝ ██║  ╚██████╔╝
╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝     ╚═╝   ╚═════╝

PRD-driven autonomous development for Claude Code.

You are the architect, agents are the builders.

---

See It In Action

Want to see exactly how KARIMO works? Check out the interactive demo to understand why it was built and how it works in detail.

---

How It Works

┌──────────┐   ┌──────┐   ┌───────┐   ┌────────┐   ┌─────────────┐   ┌─────────┐
│ RESEARCH │──▸│ PLAN │──▸│ TASKS │──▸│ REVIEW │──▸│ ORCHESTRATE │──▸│ INSPECT │
└──────────┘   └──────┘   └───────┘   └────────┘   └─────────────┘   └─────────┘
      │            │           │              │                 │              │
      └────────────┘           └──────────────┘                 └──────────────┘
          Loop 1                    Loop 2                           Loop 3
          Human                     Claude                        Configurable

Step	What Happens
Research	Discover patterns, libraries, gaps
Plan	Structured interview captures requirements
Tasks	Generate task briefs from research + PRD
Review	Claude validates briefs against codebase
Orchestrate	Execute in waves (parallel tasks, sequential waves)
Inspect	Review each PR (manual, Code Review, or Greptile)

---

Commands

Command	Purpose
/karimo:research "feature"	Start here — Create PRD folder + research
/karimo:plan --prd {slug}	Interactive PRD creation
/karimo:run --prd {slug}	Brief generation → review → execution
/karimo:merge --prd {slug}	Final PR to main
/karimo:dashboard	Monitor progress
/karimo:feedback	Capture learnings
/karimo:doctor	Diagnose issues

Full reference: COMMANDS.md

---

What KARIMO Adds

KARIMO builds on Claude Code's native APIs with custom orchestration:

Capability	Claude Code (Native)	KARIMO (Custom)
Isolation	Worktree per agent	+ Branch identity verification
Execution	Task spawning	+ Wave-ordered parallelism
Models	Static model: param	+ Complexity routing + escalation
Recovery	Worktree persistence	+ Git state reconciliation
Quality	—	+ Semantic loop detection

Why custom? Claude Code provides foundations (worktrees, sub-agents, hooks) but doesn't coordinate task dependencies, detect stuck loops, or recover from crashes. KARIMO adds these as a coordination layer.

Details: Feature Architecture

---

Adoption Phases

Phase	What You Get
Phase 1	PRD interviews, agent execution, worktrees, PRs — works out of the box
Phase 2	Automated review via Greptile ($30/mo) or Claude Code Review
Phase 3	CLI dashboard with velocity metrics

Details: PHASES.md

---

Installation

Via Claude Code marketplace (recommended)

/plugin marketplace add opensesh/KARIMO
/plugin install karimo@karimo
/reload-plugins

Once Anthropic accepts KARIMO into the official marketplace (in review), this becomes:

/plugin install karimo@claude-plugins-official

Via install script (legacy)

git clone https://github.com/opensesh/KARIMO
bash KARIMO/.karimo/install.sh ./my-project

If you previously used .karimo/update.sh to sync files into your project's .claude/plugins/karimo/, it continues to work but is no longer the recommended path. Plugin-managed installs benefit from Claude Code's built-in update, reload, and scope management.

Your First Feature

/karimo:research "feature-name"   # Creates PRD folder + runs research
/karimo:plan --prd {slug}         # Interactive PRD creation (~10 min)
/karimo:run --prd {slug}          # Execute tasks in waves
/karimo:merge --prd {slug}        # Final PR to main

Prerequisites: Claude Code, GitHub CLI (gh auth login), Git 2.5+

---

Documentation