Content
[](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.
<p align="center">
<img src="ai_orchestrator_pipeline.svg" alt="ai-orchestrator pipeline" width="680">
</p>
## 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.
```text
Step 0 Triage Claude reads graph.json (BFS depth=2), writes triage_ts.md
Step 1 Plan Parallel Claude planners write task_context_<domain>.md
Step 1.5 Orchestrate npm start runs Ollama agents in dependency order,
writes ollama_output_<domain>.md
Step 2 Code Parallel Claude coders apply ollama_output_<domain>.md,
write coder_output_<domain>.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.
```text
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/<type>-<date>.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:
```bash
# 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
```text
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_<domain>.md; circuit breaker for failed deps;
reviews ollama_output_<domain>.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](https://claude.ai/code) CLI
- [Ollama](https://ollama.com) installed and running
- `jq`
- Python 3 with `graphify` package (optional, for knowledge graph updates)
## Installation
```bash
git clone https://github.com/Mybono/ai-orchestrator ~/Projects/ai-orchestrator
cd ~/Projects/ai-orchestrator
./scripts/install.sh
```
Or with curl:
```bash
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:
```json
{
"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
```bash
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 "<task>" # 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 "<task description>" # run full pipeline autonomously
```
## License
MIT
---
**README** · [Architecture](documentation/ARCHITECTURE.md) · [Agents](documentation/AGENTS.md) · [Skills & Commands](documentation/SKILLS.md) · [Plugins](documentation/PLUGINS.md)
