OCO Claude Code plugin — safety hooks, skills, agents, and MCP tools for any project

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`

oco-claude-plugin