{
  "markdown": "```\n██╗  ██╗   █████╗   ██████╗   ██╗  ███╗   ███╗   ██████╗\n██║ ██╔╝  ██╔══██╗  ██╔══██╗  ██║  ████╗ ████║  ██╔═══██╗\n█████╔╝   ███████║  ██████╔╝  ██║  ██╔████╔██║  ██║   ██║\n██╔═██╗   ██╔══██║  ██╔══██╗  ██║  ██║╚██╔╝██║  ██║   ██║\n██║  ██╗  ██║  ██║  ██║  ██║  ██║  ██║ ╚═╝ ██║  ╚██████╔╝\n╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝  ╚═╝     ╚═╝   ╚═════╝\n```\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Version](https://img.shields.io/badge/version-v9.9.1-blue)]()\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-blueviolet.svg)]()\n\n**PRD-driven autonomous agent orchestration harness plug-in for Claude Code.**\n\n> You are the architect, agents are the builders.\n\n---\n\n## See It In Action\n\n<p align=\"center\">\n  <img src=\"assets/demo.gif\" alt=\"KARIMO Demo\" width=\"800\">\n</p>\n\nWant to see exactly how KARIMO works? Check out the [interactive demo](https://karimo-overview.vercel.app/) to understand why it was built and how it works in detail.\n\n---\n\n## How It Works\n\n```\n┌──────────┐   ┌──────┐   ┌───────┐   ┌────────┐   ┌─────────────┐   ┌─────────┐\n│ RESEARCH │──▸│ PLAN │──▸│ TASKS │──▸│ REVIEW │──▸│ ORCHESTRATE │──▸│ INSPECT │\n└──────────┘   └──────┘   └───────┘   └────────┘   └─────────────┘   └─────────┘\n      │            │           │             │            │              │\n      └────────────┘           └─────────────┘            └──────────────┘\n          Loop 1                   Loop 2                      Loop 3\n        Foundation              Decomposition               Orchestration\n```\n\n| Step | What Happens |\n|------|--------------|\n| **Research** | Discover patterns, libraries, gaps |\n| **Plan** | Structured interview captures requirements |\n| **Tasks** | Generate task briefs from research + PRD |\n| **Review** | Claude validates briefs against codebase |\n| **Orchestrate** | Execute in waves (parallel tasks, sequential waves) |\n| **Inspect** | Review each PR (manual, Code Review, or Greptile) |\n\n---\n\n## Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/karimo:research \"feature\"` | **Start here** — Create PRD folder + research |\n| `/karimo:plan --prd {slug}` | Interactive PRD creation |\n| `/karimo:run --prd {slug}` | Brief generation → review → execution |\n| `/karimo:merge --prd {slug}` | Final PR to main |\n| `/karimo:dashboard` | Monitor progress |\n| `/karimo:feedback` | Capture learnings |\n| `/karimo:doctor` | Diagnose issues |\n\nFull reference: [COMMANDS.md](.karimo/docs/COMMANDS.md)\n\n---\n\n## What KARIMO Adds\n\nKARIMO builds on Claude Code's native APIs with custom orchestration:\n\n| Capability | Claude Code (Native) | KARIMO (Custom) |\n|------------|---------------------|-----------------|\n| **Isolation** | Worktree per agent | + Branch identity verification |\n| **Execution** | Task spawning | + Wave-ordered parallelism |\n| **Models** | Static `model:` param | + Complexity routing + escalation |\n| **Recovery** | Worktree persistence | + Git state reconciliation |\n| **Quality** | — | + Semantic loop detection |\n\n**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.\n\nDetails: [Feature Architecture](.karimo/docs/ARCHITECTURE.md#feature-architecture)\n\n---\n\n## Adoption Phases\n\n| Phase | What You Get |\n|-------|--------------|\n| **Phase 1** | PRD interviews, agent execution, worktrees, PRs — works out of the box |\n| **Phase 2** | Automated review via Greptile ($30/mo) or Claude Code Review |\n| **Phase 3** | CLI dashboard with velocity metrics |\n\nDetails: [PHASES.md](.karimo/docs/PHASES.md)\n\n---\n\n## Installation\n\n### Via Claude Code marketplace (recommended)\n\n```\n/plugin marketplace add opensesh/KARIMO\n/plugin install karimo@karimo\n/reload-plugins\n```\n\nOnce Anthropic accepts KARIMO into the official marketplace (in review), this becomes:\n\n```\n/plugin install karimo@claude-plugins-official\n```\n\n### Via install script (legacy)\n\n```bash\ngit clone https://github.com/opensesh/KARIMO\nbash KARIMO/.karimo/install.sh ./my-project\n```\n\nIf 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.\n\n### Your First Feature\n\n```bash\n/karimo:research \"feature-name\"   # Creates PRD folder + runs research\n/karimo:plan --prd {slug}         # Interactive PRD creation (~10 min)\n/karimo:run --prd {slug}          # Execute tasks in waves\n/karimo:merge --prd {slug}        # Final PR to main\n```\n\n**Prerequisites:** [Claude Code](https://claude.ai/code), [GitHub CLI](https://cli.github.com/) (`gh auth login`), Git 2.5+\n\n---\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Getting Started](.karimo/docs/GETTING-STARTED.md) | Installation walkthrough |\n| [Commands](.karimo/docs/COMMANDS.md) | Full command reference |\n| [Architecture](.karimo/docs/ARCHITECTURE.md) | System design, agents, feature breakdown |\n| [Phases](.karimo/docs/PHASES.md) | Adoption phases explained |\n| [Safeguards](.karimo/docs/SAFEGUARDS.md) | Code integrity & security |\n| [Hooks](.karimo/hooks/README.md) | Lifecycle hooks (Slack, Jira, etc.) |\n| [Context Architecture](.karimo/docs/CONTEXT-ARCHITECTURE.md) | Token-efficient context layering |\n| [Compound Learning](.karimo/docs/COMPOUND-LEARNING.md) | How agents get smarter over time |\n\n---\n\n## FAQ\n\n<details>\n<summary><strong>Can I run without automated review?</strong></summary>\n\nYes. Review is optional (Phase 2). PRD interviews, execution, and PRs all work out of the box.\n\n</details>\n\n<details>\n<summary><strong>Do I need to use a feature branch?</strong></summary>\n\nNo. 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.\n\n</details>\n\n<details>\n<summary><strong>Can I run multiple sessions at once?</strong></summary>\n\nYes, 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.\n\n</details>\n\n<details>\n<summary><strong>Do I need to use Greptile?</strong></summary>\n\nNo. 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.\n\n</details>\n\n<details>\n<summary><strong>Is KARIMO modular? What can I configure?</strong></summary>\n\nYes — modularity was a core design goal. Nearly every decision point is configurable:\n\n| Aspect | Options |\n|--------|---------|\n| **Review gates** | Manual, Claude Code Review, Greptile, or skip entirely |\n| **Branch strategy** | PRs to main directly, or PRs to a feature branch first |\n| **Model routing** | Sonnet for speed, Opus for complexity, or always escalate |\n| **Boundaries** | `never_touch` files agents can't modify, `require_review` files that get flagged |\n| **Templates** | PRD structure, task briefs, commit messages — all editable |\n| **Agents & skills** | Modify behavior, add domain-specific skills, or create new agents |\n| **Research tools** | Firecrawl, other MCP servers, or your own integrations |\n| **Learnings** | Project-specific patterns and anti-patterns agents learn from |\n\nRun `/karimo:configure` to customize, or edit `.karimo/config.yaml` directly.\n\n</details>\n\n<details>\n<summary><strong>Can I use other tools for research?</strong></summary>\n\nYes. We use Firecrawl MCP for deeper web research capability. You can integrate any MCP servers or tools that fit your workflow.\n\n</details>\n\n<details>\n<summary><strong>Can I customize for my use case?</strong></summary>\n\nYes. You can modify your local installation directly or fork the repository for more extensive customization. Agent definitions, templates, and skills are all editable.\n\n</details>\n\n<details>\n<summary><strong>Having issues?</strong></summary>\n\nRun `/karimo:doctor` to diagnose. Still stuck? [hello@opensession.co](mailto:hello@opensession.co)\n\n</details>\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## License\n\n[Apache 2.0](LICENSE)\n\n---\n\n*Built with Claude Code by [Open Session](https://opensession.co)*\n",
  "bytes": 8565,
  "sha": "56dbba27ea49073fee6ab9c399c706a608eeb9df39578364e60aa0465fdffa92",
  "repo_slug": "opensesh/karimo",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_opensesh_karimo_karimo_harness_engineeri_aae157a4/readme"
}