Open Context Orchestrator (OCO)

Intelligent orchestration middleware for IDE-based coding assistants.

OCO sits between your IDE, an LLM, local tools, and context sources. It decides at each step whether to respond, retrieve context, call a tool, verify a result, or stop — producing structured decision traces for full auditability.

Claude Code Plugin

Install OCO as a Claude Code plugin in any project — one command:

npx oco-claude-plugin install          # project-level
npx oco-claude-plugin install --global # all projects
npx oco-claude-plugin status           # check installation
npx oco-claude-plugin uninstall        # clean removal

What you get:

• Safety hooks — blocks destructive commands, protects sensitive files, detects loops, enforces verification before completion
• 5 skills — /oco-inspect-repo-area, /oco-investigate-bug, /oco-safe-refactor, /oco-trace-stack, /oco-verify-fix
• 3 agents — codebase-investigator, patch-verifier, refactor-reviewer
• MCP tools — composite codebase search, error tracing, patch verification, findings collection

Plugin-only mode (Node.js only, no build required): hooks, skills, agents, and basic MCP tools work immediately. No API key required.

Full mode (requires Rust toolchain + OCO source repo): install the oco binary (cargo install --path apps/dev-cli) for indexed search, stack trace mapping, and task delegation via MCP.

Architecture

┌──────────────┐     ┌──────────────────────────────────┐     ┌─────────────┐
│  VS Code Ext │◄───►│  Orchestrator Core (Rust)        │◄───►│  ML Worker  │
│  (TypeScript)│     │  ┌────────────┐  ┌────────────┐  │     │  (Python)   │
└──────────────┘     │  │ Policy Eng │  │  Planner   │  │     └─────────────┘
                     │  │ Context Eng│  │ (DAG gen)  │  │
┌──────────────┐     │  │ Code Intel │  ├────────────┤  │     ┌─────────────┐
│  Claude Code │◄───►│  │ Tool RT    │  │ GraphRunner│  │◄───►│  LLM APIs   │
│  (MCP/Hooks) │     │  │ Retrieval  │  │ (parallel) │  │     │  (any)      │
└──────────────┘     │  │ Verifier   │  │ LlmRouter  │  │     └─────────────┘
                     │  └────────────┘  └────────────┘  │
                     │  MCP Server    Agent Teams        │     ┌─────────────┐
                     └──────────────────────────────────┘     │  SQLite     │
                                                              └─────────────┘

Orchestration v2 — Emergent Plan Engine

Medium+ tasks get a unique ExecutionPlan (DAG of steps) generated by the Planner. No templates — plans emerge from task, repo context, and available capabilities.

Request → Classifier → Trivial/Low: flat action loop
                      → Medium+: Planner → DAG → GraphRunner
                         ├── Parallel step execution (tokio::spawn)
                         ├── Observable plans (DAG overview, progress bar, per-step events)
                         ├── Hard step count enforcement per complexity tier
                         ├── Verify gates after implementation steps
                         ├── Replan on failure (max 3 attempts, budget pre-check)
                         ├── Multi-model routing (opus/sonnet/haiku per step)
                         ├── Effort-level routing (low/medium/high per step)
                         ├── Agent Teams (Mesh/HubSpoke/Pipeline topologies)
                         ├── HTTP hooks for Claude Code event integration
                         ├── MCP elicitation for interactive decisions
                         └── Cooperative cancellation + per-step budget limits

Rust Crates (15)

| Crate | Role | |-------|------| | shared-types | Domain types, ExecutionPlan DAG, CapabilityRegistry, TeamCoordinator, ElicitationRequest, EffortLevel | | shared-proto | Protobuf definitions (gRPC IPC) | | policy-engine | Deterministic action selection, budget enforcement, zero-limit guards | | code-intel | Tree-sitter parser, symbol indexer | | retrieval | SQLite FTS5, vector search, hybrid RRF ranking | | context-engine | Context assembly, dedup, step-scoped filtering | | planner | DirectPlanner (trivial) + LlmPlanner (Medium+ DAG generation) | | orchestrator-core | GraphRunner (DAG execution), LlmRouter (multi-model + effort), AgentTeamsExecutor | | tool-runtime | Shell/file executors | | verifier | Test/build/lint/typecheck runners | | telemetry | Tracing, event recording | | mcp-server | Axum HTTP + MCP server, Claude Code HTTP hook endpoints | | dev-cli | CLI binary with Terminal/JSONL/Quiet renderers | | architecture-tests | Crate dependency DAG enforcement, layer violation detection |

Key Principles

• Emergent orchestration — each plan is unique, generated from task + repo + capabilities
• Provider-agnostic — works with Anthropic, Ollama, or any LLM API
• Local-first — no cloud dependencies required
• Auditable — every decision produces a structured trace
• Observable — plan DAG overview, live progress bar, per-step lifecycle events, verify gate results
• Bounded — explicit token, time, and tool-call budgets with per-step cancellation and step count limits
• Deterministic policy — no LLM calls for routing decisions
• Multi-model routing — opus for architecture, sonnet for implementation, haiku for exploration
• Effort-level routing — automatic --effort selection per step role, budget-aware downgrade
• Agent Teams native — Mesh, HubSpoke, Pipeline topologies with runtime enforcement
• Interactive decisions — MCP elicitation for replan confirmation, architecture choices, verify gate failures
• Event-driven UI — core emits structured events, CLI renders via pluggable renderers

Stack

| Layer | Technology | |-------|-----------| | Core runtime | Rust 1.85+ (edition 2024), Tokio, Axum | | Orchestration | DAG planner, GraphRunner, LlmRouter, Agent Teams | | Storage | SQLite + FTS5 | | Code analysis | Tree-sitter (regex fallback) | | IPC | gRPC / Protobuf | | IDE extension | TypeScript, VS Code API | | Claude Code | MCP bridge, hooks, skills, agents | | ML worker | Python, Sentence Transformers | | Telemetry | tracing + OpenTelemetry |

Getting Started

Prerequisites

• Rust 1.85+ (edition 2024)
• Node 20+ (for Claude Code plugin)
• Python 3.11+ and uv (optional, for ML worker)
• pnpm (optional, for VS Code extension)

Build from source

git clone https://github.com/hoklims/oco.git
cd oco

# Build all Rust crates
cargo build

# Run the test suite (421+ tests)
cargo test

# Run the CLI
cargo run -p oco-dev-cli -- --help

Optional components

# Python ML worker (embeddings & reranking)
cd py/ml-worker && uv sync

# VS Code extension
cd apps/vscode-extension && pnpm install

Quick usage

oco index ./my-project                    # Index a workspace
oco search "auth handler" --workspace .   # Full-text search
oco run "fix the login bug" --workspace . # Orchestrate (live trace)
oco serve --port 3000                     # Start HTTP/MCP server
oco doctor --workspace .                  # Check health
oco eval scenarios.jsonl                  # Run evaluations
oco runs list                             # List past runs
oco runs show last                        # Replay last run's trace

Output modes

oco doctor                                # Human: colors, spinners, icons
oco --format jsonl doctor                 # Machine: 1 JSON event per line
oco --quiet doctor                        # Quiet: only final result/errors

Configuration

Runtime config in oco.toml. See examples/oco.toml for a documented template.

LLM Providers

| Provider | Config | Requirements | |----------|--------|--------------| | claude-code | provider = "claude-code" (default) | claude CLI on PATH | | stub | provider = "stub" | None | | anthropic | provider = "anthropic" | ANTHROPIC_API_KEY env var | | ollama | provider = "ollama" | Local Ollama at localhost:11434 |

Documentation

• Architecture overview
• Architecture Decision Records
• Feature specifications
• Claude Code integration
• Contributing
• Security policy

Contributing

See CONTRIBUTING.md for setup instructions, conventions, and workflow.

License

Apache-2.0