Orka

Multi-agent coding orchestration CLI. Orka coordinates a swarm of AI agents that work like an engineering team — Coordinator breaks down goals, Scout analyzes the codebase, Builders implement in parallel, and Reviewer ensures quality — all automatically coordinated without file conflicts.

$ orka run "build user authentication with OAuth2 and JWT"

  ┌─────────────────────────────────────────────────────────┐
  │  Orka — session #a3f2                                   │
  │  Goal: Build user authentication with OAuth2 and JWT    │
  │  Elapsed: 2m 34s  │  Tokens: 12.4k  │  Cost: $0.03     │
  ├──────────┬──────────────────────────┬────────┬──────────┤
  │  Status  │  Task                    │  Agent │  Files   │
  ├──────────┼──────────────────────────┼────────┼──────────┤
  │  ✓ DONE  │  Scan codebase           │  scout │  —       │
  │  ✓ DONE  │  Auth types & schemas    │  bld-1 │  3 files │
  │  ◎ REVIEW│  Auth service            │  bld-1 │  2 files │
  │  ⚡ BUILD │  API routes & middleware │  bld-2 │  4 files │
  │  ⏳ QUEUE │  Login & signup UI       │  —     │  5 files │
  └──────────┴──────────────────────────┴────────┴──────────┘

Features

• Parallel multi-agent swarm — Coordinator + Scout + N Builders + Reviewer work concurrently
• Zero file conflicts — atomic SQLite file ownership locks prevent two agents from editing the same file
• AI self-healing loop — TesterAgent runs your test suite after each build; if tests fail, Builder retries with the test output as feedback
• Provider-agnostic — Claude, OpenAI, Gemini, Ollama (local/free), OpenRouter — mix and match per role
• Git integration — auto-branch per session, auto-commit after approval, safe rollback
• Crash recovery — full state persisted in SQLite; orka resume picks up exactly where it left off
• Cost tracking — real-time token usage and estimated cost per agent
• Plugin system — extend with custom roles, providers, and hooks
• MCP server — expose Orka as an MCP tool for use inside Claude, Cursor, and other AI editors

Installation

npm install -g orka-cli

Requirements: Node.js v20+, at least one LLM provider (API key or local Ollama)

Quickstart

# 1. Initialize config in your project
cd your-project
orka init

# 2. Add your API key
orka login --provider claude

# 3. Run your first session
orka run "add input validation to all API endpoints"

Configuration

orka init generates orka.config.yaml in your project root:

providers:
  claude:
    apiKey: ${ANTHROPIC_API_KEY}      # reads from environment variable
  ollama:
    baseUrl: http://localhost:11434

swarm:
  builders: 2                         # number of parallel Builder agents
  review: true                        # enable Reviewer agent
  maxReviewRetries: 3

roles:
  coordinator: { provider: claude, model: claude-sonnet-4-20250514 }
  scout:       { provider: claude, model: claude-haiku-4-5-20251001 }
  builder:     { provider: ollama, model: deepseek-coder-v2 }
  reviewer:    { provider: claude, model: claude-sonnet-4-20250514 }

git:
  autoBranch: true
  autoMerge: true
  commitPrefix: "[orka]"
  push: false                         # never pushes without explicit confirmation
  conflictResolution: prompt          # prompt | auto | manual

tester:
  enabled: false                      # set true to enable self-healing test loop
  command: "npm test"
  timeout: 60000
  maxRetries: 3

Budget Setup (fully local, free)

roles:
  coordinator: { provider: ollama, model: llama3 }
  scout:       { provider: ollama, model: llama3 }
  builder:     { provider: ollama, model: deepseek-coder-v2 }
  reviewer:    { provider: ollama, model: llama3 }

Quality Setup (cloud for planning and review)

roles:
  coordinator: { provider: claude, model: claude-sonnet-4-20250514 }
  scout:       { provider: claude, model: claude-haiku-4-5-20251001 }
  builder:     { provider: ollama, model: deepseek-coder-v2 }
  reviewer:    { provider: claude, model: claude-sonnet-4-20250514 }

Self-Healing Test Loop

Enable tester.enabled: true to have Orka automatically run your test suite after each build:

tester:
  enabled: true
  command: "npm test"
  timeout: 60000
  maxRetries: 3

Pipeline:

Builder writes code → TesterAgent runs tests → pass: send to Reviewer
                                             → fail: Builder retries with test output

Rules System

Create orka.rules.md in your project root to guide all agents:

## Code Style
- Use TypeScript strict mode
- Prefer named exports over default exports
- All functions must have explicit return types

## Architecture
- API routes go in src/app/api/
- Use Zod for validation, not manual type checking
- No direct database calls outside of repository files

Global rules (applied to all projects): ~/.orka/rules.md

All Commands

Session Management

orka run "goal"                          # start an orchestration session
orka run "goal" --files src/app.ts       # single-task run targeting specific files
orka run "goal" --no-git                 # disable session branch and auto-commit
orka run "goal" --builders 4             # use 4 parallel Builder agents
orka run "goal" --provider claude        # override all roles to one provider
orka run "goal" --dry-run                # preview plan without calling any LLM
orka run "goal" --mock                   # use mock provider (no API calls, for testing)
orka pause                               # pause all agents gracefully
orka resume                              # resume from pause or crash
orka rollback                            # rollback last session branch to base commit

Monitoring

orka status                              # show last session status board
orka status --watch                      # live-refresh status board
orka status --ink                        # interactive Ink TUI board
orka board                               # alias for status
orka logs                                # show event log for last session
orka logs --session session-123          # filter to a specific session
orka logs --type task:completed          # filter by message type
orka cost                                # show token usage and cost summary

Provider & Credentials

orka login --provider claude             # save Claude API key
orka login --provider openai             # save OpenAI API key
orka login --provider gemini             # save Gemini API key
orka login --provider ollama             # configure Ollama base URL
orka logout --provider claude            # remove saved credential
orka whoami                              # show credential status for all providers
orka models --provider claude            # list available models from provider

Project Setup

orka init                                # generate config from default preset
orka init --profile ollama               # local-first preset (no cloud API needed)
orka init --wizard                       # interactive setup wizard
orka init --force                        # overwrite existing config

Git Conflict Resolution

orka fix                                 # resolve git conflicts using LLM
orka fix --strategy ours                 # keep current branch version
orka fix --strategy theirs               # keep incoming branch version

Rules & Memory

orka rules show                          # show active project and global rules
orka rules edit                          # open project rules in $EDITOR
orka memory show                         # show memory entries
orka memory add "always use pnpm"        # add a memory entry
orka memory clear                        # clear all memory entries

Plugins

orka plugin add my-plugin                # install plugin from npm
orka plugin add ./local-plugin           # install local plugin
orka plugin list                         # list installed plugins
orka plugin remove my-plugin             # uninstall plugin

MCP Server

orka mcp-server                          # start as MCP server (stdio transport)

Git Flow

Orka never touches your active branch directly:

main (your branch)
  │
  └── orka/session-<timestamp>           ← session branch (auto-created)
       ├── task-1: auth types            ← builder-1 works here
       ├── task-2: auth service          ← builder-2 works here
       └── task-3: API routes            ← builder-2 works here

After all tasks are approved, Orka auto-commits to the session branch. You decide when to merge.

Safety guarantees:

• Never force pushes
• Never pushes to remote without explicit confirmation (push: false by default)
• Merge conflicts → session pauses and notifies you, never silently auto-resolves

Supported Providers

| Provider | Notes | |----------|-------| | Claude | Best quality for planning and review | | OpenAI | GPT-4o, o1, and variants | | Gemini | Gemini 2.0 Flash, 1.5 Pro | | Ollama | Free, runs locally — llama3, deepseek-coder-v2, qwen2.5-coder | | OpenRouter | Access any model via OpenRouter | | Zai / GLM | GLM-4 and variants |

MCP Integration

Use Orka as an MCP tool inside Claude Desktop, Cursor, or any MCP-compatible editor:

{
  "mcpServers": {
    "orka": {
      "command": "orka",
      "args": ["mcp-server"]
    }
  }
}

Contributing

See CONTRIBUTING.md.

License

MIT