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