karimo-harness-engineering-agent-orchestration
Harness engineering framework for Claude Code — plan mode on steroids. Product design-driven agent orchestration with sub-agents and agent t
Open source Repository Open in the app JSON README (API)
About
Harness engineering framework for Claude Code — plan mode on steroids. Product design-driven agent orchestration with sub-agents and agent teams, tuned for developers and designers shipping real features. Phased adoption from PRD execution to automated review, code review, and CI-friendly agent teams
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- opensesh
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 284
- Forks
- 41
- Last push
- 2026-05-11T21:28:52Z
- Repository state
- ativo
- Language
- Markdown
- License
- Apache-2.0
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
opensesh/karimo/karimo-harness-engineering-agent-orchestration
README
```
██╗ ██╗ █████╗ ██████╗ ██╗ ███╗ ███╗ ██████╗
██║ ██╔╝ ██╔══██╗ ██╔══██╗ ██║ ████╗ ████║ ██╔═══██╗
█████╔╝ ███████║ ██████╔╝ ██║ ██╔████╔██║ ██║ ██║
██╔═██╗ ██╔══██║ ██╔══██╗ ██║ ██║╚██╔╝██║ ██║ ██║
██║ ██╗ ██║ ██║ ██║ ██║ ██║ ██║ ╚═╝ ██║ ╚██████╔╝
╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝
```
[](https://opensource.org/licenses/Apache-2.0)
[]()
[]()
**PRD-driven autonomous agent orchestration harness plug-in for Claude Code.**
> You are the architect, agents are the builders.
---
## See It In Action
<p align="center">
<img src="assets/demo.gif" alt="KARIMO Demo" width="800">
</p>
Want 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.
---
## 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](.karimo/docs/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](.karimo/docs/ARCHITECTURE.md#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](.karimo/docs/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)
```bash
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
```bash
/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](https://claude.ai/code), [GitHub CLI](https://cli.github.com/) (`gh auth login`), Git 2.5+
---
## Documentation
| Document | Description |
|----------|-------------|
| [Getting Started](.karimo/docs/GETTING-STARTED.md) | Installation walkthrough |
| [Commands](.karimo/docs/COMMANDS.md) | Full command reference |
| [Architecture](.karimo/docs/ARCHITECTURE.md) | System design, agents, feature breakdown |
| [Phases](.karimo/docs/PHASES.md) | Adoption phases explained |
| [Safeguards](.karimo/docs/SAFEGUARDS.md) | Code integrity & security |
| [Hooks](.karimo/hooks/README.md) | Lifecycle hooks (Slack, Jira, etc.) |
| [Context Architecture](.karimo/docs/CONTEXT-ARCHITECTURE.md) | Token-efficient context layering |
| [Compound Learning](.karimo/docs/COMPOUND-LEARNING.md) | How agents get smarter over time |
---
## FAQ
<details>
<summary><strong>Can I run without automated review?</strong></summary>
Yes. Review is optional (Phase 2). PRD interviews, execution, and PRs all work out of the box.
</details>
<details>
<summary><strong>Do I need to use a feature branch?</strong></summary>
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.
</details>
<details>
<summary><strong>Can I run multiple sessions at once?</strong></summary>
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.
</details>
<details>
<summary><strong>Do I need to use Greptile?</strong></summary>
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.
</details>
<details>
<summary><strong>Is KARIMO modular? What can I configure?</strong></summary>
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.
</details>
<details>
<summary><strong>Can I use other tools for research?</strong></summary>
Yes. We use Firecrawl MCP for deeper web research capability. You can integrate any MCP servers or tools that fit your workflow.
</details>
<details>
<summary><strong>Can I customize for my use case?</strong></summary>
Yes. You can modify your local installation directly or fork the repository for more extensive customization. Agent definitions, templates, and skills are all editable.
</details>
<details>
<summary><strong>Having issues?</strong></summary>
Run `/karimo:doctor` to diagnose. Still stuck? [hello@opensession.co](mailto:hello@opensession.co)
</details>
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
[Apache 2.0](LICENSE)
---
*Built with Claude Code by [Open Session](https://opensession.co)*