Ai Orchestrator

[](https://github.com/Mybono/ai-orchestrator/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT)

README · [Architecture](documentation/ARCHITECTURE.md) · [Agents](documentation/AGENTS.md) · [Skills & Commands](documentation/SKILLS.md) · [Plugins](documentation/PLUGINS.md)

---

TypeScript + Bash orchestration that runs AI agents — Ollama for code generation, Claude for planning and triage — in parallel, in dependency order.

How it works

/implement triggers a multi-step pipeline. Claude handles triage and planning; the TypeScript orchestrator runs Ollama agents in dependency order; Claude applies the generated output.

Step 0   Triage      Claude reads graph.json (BFS depth=2), writes triage_ts.md
Step 1   Plan        Parallel Claude planners write task_context_.md
Step 1.5 Orchestrate npm start runs Ollama agents in dependency order,
                     writes ollama_output_.md
Step 2   Code        Parallel Claude coders apply ollama_output_.md,
                     write coder_output_.md
Step 2.5 Pre-review  Standards compliance check
Step 3   Build       npx tsc --noEmit
Step 4   Review      Fast review per file; deep review for flagged files
Step 5   Fix loop    Max 3 rounds, circuit breaker on repeat errors
Step 6   Finalize    git diff + track savings

scripts/run_pipeline.sh wraps steps 1–3 into a single non-interactive script. Pass a task description and it runs triage, parallel planning, and the TS orchestrator in sequence without any Claude interaction required.

Agents communicate through files in .claude/context/. Each step reads file paths from the previous step, not the full content.

Self-learning loop

After every pipeline run the orchestrator records what happened and uses it to improve future reviews automatically.

Pipeline run
  └─► capture-outcome.sh      ──► knowledge/outcomes.jsonl
        │  (task, verdict, reviewer_issues, model, duration)
        │
        ├─► embed-outcomes.sh  ──► knowledge/embeddings.jsonl
        │     (mxbai-embed-large via Ollama, runs in background)
        │
        └─► learn.sh --apply   ──► skills/discovered/-.md
              (auto-triggered every 10 outcomes)

| Script | What it does | |---|---| | capture-outcome.sh | Appends one JSON record per run: task, verdict, files changed, reviewer issues, model, duration | | embed-outcomes.sh | Generates Ollama vector embeddings for each outcome; skips already-embedded records | | semantic-search.sh | Cosine-similarity search over embeddings.jsonl; returns top-k similar past outcomes | | learn.sh | Finds recurring reviewer issues (≥ 3 occurrences), calls Ollama reviewer to draft a skill amendment, writes it to skills/discovered/ |

Every 10 captured outcomes learn.sh --apply fires automatically (background, no blocking). Discovered amendments land in skills/discovered/ and are picked up by the reviewer on the next run.

Run manually:

# Dry-run: print proposed amendments without writing files
bash scripts/learn.sh

# Apply: write amendments to skills/discovered/
bash scripts/learn.sh --apply

# Query: find issues similar to a specific task description
bash scripts/learn.sh --query "add authentication middleware"

# Semantic search standalone
bash scripts/semantic-search.sh --query "TypeScript type errors" --top-k 3

Source layout

src/
  types/index.ts          AgentDomain, KNOWN_DOMAINS, Role, AgentTask,
                          AgentResult (done|skipped|failed|blocked), TriageResult
  agents/
    AgentRunner.ts        Wraps call_ollama.sh via spawn; 5 min timeout; 10 MB output limit
    TriageAgent.ts        BFS depth=2 on graph.json; writes triage_ts.md; CLI via import.meta.url
  core/
    DependencyGraph.ts    Kahn topological sort; duplicate domain detection
    Orchestrator.ts       Reads task_context_.md; circuit breaker for failed deps;
                          reviews ollama_output_.md after all domains complete
    BuildChecker.ts       Runs npx tsc --noEmit; returns pass/fail with stderr
    DiffCompressor.ts     Strips lock files, collapses blanks, truncates long hunks
    FileWriter.ts         Parses %%FILE...%%ENDFILE blocks from Ollama output; writes to disk
    TriageRouter.ts       Reads triage_ts.md and extracts the chosen TriageRoute
  cli/
    commit.ts             npm run ao-commit — calls local-commit.sh via spawn
    review.ts             npm run ao-review — runs reviewer agent on current diff
    stats.ts              npm run ao-stats  — prints token savings summary
    update.ts             npm run ao-update — pulls latest orchestrator version
  mcp/
    server.ts             MCP HTTP server (default port 3456); exposes get_stats,
                          triage_task, and run_ollama tools to Claude
  index.ts                CLI entry point

Domain dependencies

| Domain | Depends on | |--------|------------| | coder | (none) | | unit-tester | coder | | doc-writer | coder | | devops | coder, unit-tester, doc-writer |

Domains within the same dependency level run concurrently. If a domain fails, its dependents are marked blocked and skipped.

Requirements

• Node.js 20+ with tsx
• Claude Code CLI
• Ollama installed and running
• jq
• Python 3 with graphify package (optional, for knowledge graph updates)

Installation

git clone https://github.com/Mybono/ai-orchestrator ~/Projects/ai-orchestrator
cd ~/Projects/ai-orchestrator
./scripts/install.sh

Or with curl:

curl -sSL https://raw.githubusercontent.com/Mybono/ai-orchestrator/main/scripts/install.sh | bash

install.sh creates symlinks from ~/.claude/ into the repo. A git pull in the repo directory updates all tooling immediately.

Configuration

Model routing is controlled by llm-config.json in the repo root:

{
  "models": {
    "coder":        "qwen3:32b-q4_K_M",
    "reviewer":     "qwen3:32b-q4_K_M",
    "pre-reviewer": "qwen3:8b",
    "debugger":     "qwen3:32b-q4_K_M",
    "devops":       "qwen3:8b",
    "quick-coder":  "qwen3:8b",
    "commit":       "qwen2.5-coder:7b",
    "triage":       "qwen3:8b",
    "embedding":    "mxbai-embed-large"
  },
  "free_api_url": "http://localhost:3001/v1/chat/completions",
  "free_api": {
    "planner":      "qwen/qwen3-32b",
    "coder":        "qwen3-coder-next",
    "reviewer":     "auto",
    "pre-reviewer": "auto",
    "debugger":     "qwen3-coder-next",
    "devops":       "auto",
    "quick-coder":  "qwen3-coder-next",
    "commit":       "auto",
    "triage":       "auto"
  },
  "cerebras_api": {
    "coder":        "gpt-oss-120b",
    "reviewer":     "gpt-oss-120b",
    "pre-reviewer": "gpt-oss-120b",
    "debugger":     "gpt-oss-120b",
    "devops":       "gpt-oss-120b",
    "quick-coder":  "gpt-oss-120b",
    "commit":       "gpt-oss-120b",
    "triage":       "gpt-oss-120b"
  },
  "fallback": {
    "coder":        "claude-sonnet-4-6",
    "reviewer":     "claude-sonnet-4-6",
    "pre-reviewer": "claude-haiku-4-5-20251001",
    "debugger":     "claude-sonnet-4-6",
    "devops":       "claude-haiku-4-5-20251001",
    "quick-coder":  "claude-haiku-4-5-20251001",
    "commit":       "claude-haiku-4-5-20251001",
    "triage":       "claude-haiku-4-5-20251001",
    "embedding":    ""
  },
  "cloud_first_roles": ["planner", "reviewer", "debugger"]
}

Routing follows a 4-tier provider chain. Roles listed in cloud_first_roles (planner, reviewer, debugger) try Cerebras first, then FreeLLM, then Ollama, then Claude. All other roles start with Ollama, then fall through FreeLLM, Cerebras, and finally Claude. Changing a model name takes effect immediately — no restart needed. See [Architecture](documentation/ARCHITECTURE.md#model-configuration) for details.

Development

npm run build                                    # compile TypeScript
npm run typecheck                                # tsc --noEmit, no output files
npm start "coder,unit-tester"                    # run TS orchestrator for given domains
npx tsx src/agents/TriageAgent.ts ""       # run triage standalone

npm run ao-commit                                # generate commit message via Ollama and commit
npm run ao-review                                # review current diff with reviewer agent
npm run ao-stats                                 # print token savings (day/week/month)
npm run ao-update                                # pull latest orchestrator version
npm run ao-mcp                                   # start MCP server on port 3456

bash scripts/run_pipeline.sh ""  # run full pipeline autonomously

License

MIT

---

README · [Architecture](documentation/ARCHITECTURE.md) · [Agents](documentation/AGENTS.md) · [Skills & Commands](documentation/SKILLS.md) · [Plugins](documentation/PLUGINS.md)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Mybono
• Source: Mybono/ai-orchestrator
• License: MIT

Install and usage instructions live in the source repository linked above.