██╗ ██╗ █████╗ ██████╗ ██╗ ███╗ ███╗ ██████╗
██║ ██╔╝ ██╔══██╗ ██╔══██╗ ██║ ████╗ ████║ ██╔═══██╗
█████╔╝ ███████║ ██████╔╝ ██║ ██╔████╔██║ ██║ ██║
██╔═██╗ ██╔══██║ ██╔══██╗ ██║ ██║╚██╔╝██║ ██║ ██║
██║ ██╗ ██║ ██║ ██║ ██║ ██║ ██║ ╚═╝ ██║ ╚██████╔╝
╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝
PRD-driven autonomous agent orchestration harness plug-in 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
Foundation Decomposition Orchestration
| 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
| Document | Description |
|---|---|
| Getting Started | Installation walkthrough |
| Commands | Full command reference |
| Architecture | System design, agents, feature breakdown |
| Phases | Adoption phases explained |
| Safeguards | Code integrity & security |
| Hooks | Lifecycle hooks (Slack, Jira, etc.) |
| Context Architecture | Token-efficient context layering |
| Compound Learning | How agents get smarter over time |
FAQ
Can I run without automated review?
Yes. Review is optional (Phase 2). PRD interviews, execution, and PRs all work out of the box.
Do I need to use a feature branch?
No. KARIMO supports two modes configured via /karimo:configure: feature branch mode (tasks branch from a feature branch) or main mode (tasks branch directly from main). Choose what fits your workflow.
Can I run multiple sessions at once?
Yes, but be careful when running multiple feature branches with worktrees simultaneously. Typically when a feature branch and work trees are kicked off for a PRD, you only want to be doing research and planning on main. With Claude Opus 4.6, we've seen occasional conflicts. For best results, let one orchestration complete before starting another.
Do I need to use Greptile?
No. You can use manual review, Claude Code Review, or any other review mechanism. Greptile is one option for automated review in Phase 2, but it's entirely optional.
Is KARIMO modular? What can I configure?
Yes — modularity was a core design goal. Nearly every decision point is configurable:
| Aspect | Options |
|---|---|
| Review gates | Manual, Claude Code Review, Greptile, or skip entirely |
| Branch strategy | PRs to main directly, or PRs to a feature branch first |
| Model routing | Sonnet for speed, Opus for complexity, or always escalate |
| Boundaries | never_touch files agents can't modify, require_review files that get flagged |
| Templates | PRD structure, task briefs, commit messages — all editable |
| Agents & skills | Modify behavior, add domain-specific skills, or create new agents |
| Research tools | Firecrawl, other MCP servers, or your own integrations |
| Learnings | Project-specific patterns and anti-patterns agents learn from |
Run /karimo:configure to customize, or edit .karimo/config.yaml directly.
Can I use other tools for research?
Yes. We use Firecrawl MCP for deeper web research capability. You can integrate any MCP servers or tools that fit your workflow.
Can I customize for my use case?
Yes. You can modify your local installation directly or fork the repository for more extensive customization. Agent definitions, templates, and skills are all editable.
Having issues?
Run /karimo:doctor to diagnose. Still stuck? hello@opensession.co
Contributing
See CONTRIBUTING.md
License
Built with Claude Code by Open Session