Orchestray

Multi-agent orchestration plugin for Claude Code. Automatically detects complex tasks, decomposes them across specialized AI agents, and produces fully audited output — without manual configuration.

What it does

You type a prompt. Orchestray's PM agent scores its complexity. If it warrants orchestration, the PM decomposes the task, assigns agents (architect, developer, reviewer, custom specialists), coordinates their work, and delivers a consolidated result with full audit trail.

Simple prompts pass through to normal Claude Code behavior. Complex prompts get the full treatment.

Key features

• Auto-trigger — complexity scoring detects when orchestration helps, self-calibrates over time
• Smart model routing — assigns Haiku/Sonnet/Opus per subtask based on complexity, tracks cost savings
• GitHub Issue integration — orchestrate directly from GitHub issues via gh CLI
• CI/CD feedback loop — run CI after orchestration, auto-fix failures up to N retries
• Shift-left security — dedicated Security Engineer agent auto-invoked on security-sensitive tasks
• Pipeline templates — 7 workflow archetypes for consistent decomposition (bug fix, feature, refactor, migration, etc.)
• TDD mode — test-first orchestration: architect → tester → developer → reviewer
• Mid-orchestration control — checkpoints between groups to review, modify, or abort
• User playbooks — project-specific instructions injected into agent delegation prompts
• Parallel execution — independent subtasks run concurrently via subagents
• Verify-fix loops — reviewer failures route back to developer with specific feedback
• Correction memory — learns from verify-fix loops, prevents repeated mistakes
• Cost prediction — estimates orchestration cost from historical data before execution
• Persistent specialists — dynamic agents that prove useful get saved for reuse
• Pattern learning — extracts reusable strategies from past orchestrations
• Team features — shared config, shared patterns, daily/weekly cost budgets
• Agent Teams — opt-in dual-mode execution for tasks needing inter-agent communication
• Prompt tiering — 3-tier PM prompt architecture, significant token reduction for simple tasks
• Orchestration contracts — machine-verifiable quality gates with file ownership tracking
• Consequence forecasting — predicts downstream effects before execution, validates after
• ROI scorecard — per-orchestration value visibility with cost savings breakdown
• Diff-scoped review — reviewer focuses on changed files only, reducing noise
• Adaptive turn budgets — dynamic turn limits based on subtask complexity
• Agent introspection — Haiku distiller extracts reasoning traces after each agent, eliminating redundant exploration downstream
• Cognitive backpressure — agents signal confidence at checkpoints; PM reacts to low-confidence before proceeding
• Disagreement surfacing — design trade-offs from reviews presented as structured decisions, not verify-fix loops
• Drift Sentinel — architectural drift detection via auto-extracted invariants and static rules
• Visual Orchestration — multi-modal screenshot review for UI changes (opt-in)
• Full audit trail — per-agent tokens, cost breakdown, routing decisions, model savings
• Orchestration Threads — cross-session continuity via compressed thread summaries that carry forward decisions and open items
• Outcome Tracking — deferred quality validation via lazy probe execution when you return to delivered files
• Adaptive Personas — auto-generated project-tuned behavioral directives injected into agent delegations
• Replay Analysis — counterfactual reasoning on friction orchestrations to extract improvement patterns

Install

npx orchestray --global

This installs agents, skills, and hooks into ~/.claude/. No --plugin-dir flag needed — Claude Code discovers them automatically.

For project-local install:

npx orchestray --local

Uninstall

npx orchestray --global --uninstall

Usage

Orchestray activates automatically on complex prompts. You can also use slash commands:

Agent roles

Configuration

Run /orchestray:config to view all settings. Key options:

complexity_threshold    Score threshold for auto-orchestration (default: 4)
auto_review             Auto-spawn reviewer after developer (default: true)
model_floor             Minimum model tier: haiku/sonnet/opus (default: sonnet)
security_review         Security review mode: auto/manual/off (default: auto)
tdd_mode                Prefer TDD orchestration flow (default: false)
confirm_before_execute  Show preview before execution (default: false)
enable_checkpoints      Pause between groups for review (default: false)
ci_command              CI check after orchestration (default: null)
post_to_issue           Comment results on GitHub issue (default: false)
daily_cost_limit_usd    Daily spending limit (default: null)
weekly_cost_limit_usd   Weekly spending limit (default: null)

How it works

User prompt
    |
    v
Complexity scoring (0-12)
    |
    +-- Score < threshold --> Normal Claude Code
    |
    +-- Score >= threshold --> PM orchestration
            |
            v
        Task decomposition
            |
            v
        Model routing (Haiku/Sonnet/Opus per subtask)
            |
            v
        Agent spawning (parallel where safe)
            |
            v
        Result collection + verify-fix loops
            |
            v
        Pattern extraction + audit report

Runtime state

All orchestration state lives in .orchestray/ (gitignored):

.orchestray/
  state/          # Active orchestration state
  kb/             # Shared knowledge base
  audit/          # Event logs and metrics
  history/        # Archived orchestrations
  specialists/    # Persistent specialist registry
  patterns/       # Extracted learning patterns (gitignored)
  playbooks/      # User-authored project playbooks
  config.json     # User configuration (gitignored)
  team-config.json # Team-shared configuration (version-controlled)
  team-patterns/  # Team-shared patterns (version-controlled)
  workflows/      # Custom YAML workflow definitions (version-controlled)

Requirements

• Claude Code v2.0.0+
• Agent Teams features require v2.1.32+ (opt-in)

Agent Teams features (TaskCreated / TaskCompleted / TeammateIdle hooks) require Claude Code v2.1.32+ with the experimental flag CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 set in the environment or settings.json. Without the flag, these hooks are installed but dormant — nothing breaks, they simply never fire.

License

MIT