SuperAPI AI Directory

orch-runtime

Coding & development

View repository

Updated 10-18 16:38

About this skill

Historical version and verification scope

This page restores and fully translates the complete orch-runtime main guide from the parent of its revert. The publisher reverted this file on 2026-03-31 UTC. This historical status does not establish that the existing install command still retrieves identical content. Path history, revert commit, complete parent file tree, blob, translation and MIT notice checked on 2026-10-19. Original metadata, all 13 code blocks and the license notice are retained. Companion CLI, adapters and other files were not separately recovered. Installation, agent invocation, messaging, goal creation and source commands were not executed; current runtime behavior is untested.

Publisher original at pinned commit

Publisher revert commit

Complete main guide

ORCH Runtime Integration

Use this skill when you need to hand off work to a persistent, stateful AI agent team managed by ORCH — the TypeScript CLI runtime for coordinating Claude Code, OpenCode, Codex, and Cursor agents.

Unlike ECC's in-process subagents (ephemeral, single-session), ORCH agents are:

  • persistent — survive process restarts and session ends
  • stateful — tasks flow through a formal state machine (todo → in_progress → review → done)
  • resilient — auto-retry on failure, with configurable retry budgets
  • communicating — agents send direct messages and broadcast to the team

When to Use

  • The task spans multiple Claude sessions (>1 context window)
  • You need a background agent to run while you work on something else
  • You want human review gates before a task is marked done
  • You have a team of specialized agents (Backend, QA, Reviewer) that should coordinate
  • You need an audit trail of task state transitions

Prerequisites

npm install -g @oxgeneral/orch

Verify installation:

orch --version
orch agent list

Core Concepts

State Machine

Every task in ORCH follows a managed lifecycle:

todo → in_progress → review → done
              ↓
           retrying (on failure, up to N attempts)
              ↓
           failed

No task jumps directly to done — the review gate ensures accountability.

Agent Registry

Agents are persisted in .orchestry/agents/. Each agent has:

  • adapter: claude | opencode | codex | cursor | shell
  • model: the AI model to invoke
  • role: the system prompt
  • approval_policy: auto | suggest | manual

Shared Context

Use orch context set/get as a key-value store that all agents can read. This is the shared memory layer between ORCH and ECC sessions.

Dispatching Tasks from Claude Code

1. Add a task and assign to an agent

# Find available agents
orch agent list

# Create task with description and priority
orch task add "Implement OAuth2 middleware" \
  -d "Add OAuth2 bearer token validation to Express. Files: src/middleware/auth.ts" \
  -p 2 \
  --assignee <agent-id>

2. Pass context from current Claude session

# Share findings from your ECC session with ORCH agents
orch context set security-findings "XSS vulnerability in src/views/profile.tsx:42 — unsanitized user input passed to innerHTML"

# Share a file reference
orch context set current-pr "https://github.com/org/repo/pull/123"

# Share structured analysis
orch context set arch-decision "Use JWT with RS256, not HS256. See: docs/adr/0012-auth.md"

3. Monitor task progress

# List active tasks
orch task list --status in_progress

# Watch the live dashboard
orch tui

# Stream logs from a specific run
orch logs --tail 50

4. Collect results

# Read context set by the ORCH agent after completion
orch context get implementation-result
orch context get test-coverage-report

# Show full task details
orch task show <task-id>

Integration with /orchestrate

Combine ECC's in-process orchestration with ORCH for long-horizon tasks:

## Hybrid Workflow Example

### Phase 1: In-process planning (ECC)
/orchestrate feature "Add OAuth2 middleware"
→ planner generates implementation plan
→ architect reviews design
→ Output: HANDOFF document in context

### Phase 2: Persistent execution (ORCH)
orch context set ecc-handoff "<paste HANDOFF document>"
orch task add "Implement OAuth2 per handoff" \
  -d "$(orch context get ecc-handoff)" \
  -p 1 --assignee <backend-agent-id>

### Phase 3: Async review gate
# ORCH enforces review state before marking done
# Agent transitions: in_progress → review → done
orch task list --status review  # see tasks awaiting review

Agent Communication

# Send a message to a specific agent mid-task
orch msg send <agent-id> "Prioritize security hardening over performance" \
  -s "Updated requirements"

# Broadcast to entire team
orch msg broadcast "New requirement: FIPS compliance required" \
  -s "Compliance update"

# Check team inbox
orch msg inbox <agent-id>

Goal-Driven Workflows

For multi-task projects, set a goal to link related tasks:

# Create a goal
orch goal add "Implement full authentication system" \
  -d "OAuth2 + session management + 2FA. Target: Sprint 24."

# Add tasks under the goal
orch task add "OAuth2 middleware" -p 1 --goal <goal-id>
orch task add "Session store (Redis)" -p 2 --goal <goal-id> --depends-on <oauth-task-id>
orch task add "2FA via TOTP" -p 2 --goal <goal-id> --depends-on <session-task-id>

# Monitor goal progress
orch goal show <goal-id>

Resilience Patterns

Auto-retry configuration

Configure retry budgets per agent in .orchestry/agents/<id>.yaml:

max_retries: 3
retry_delay_ms: 5000

When a task fails, ORCH automatically transitions it to retrying and re-dispatches after the delay.

Stall detection

ORCH's orchestrator tick loop detects zombie processes and stalled tasks. If an agent exceeds stall_timeout_ms, the task is retried or failed automatically.

Context Store Patterns

Use the ORCH context store as a blackboard between ECC sessions and ORCH agents:

# ECC session writes analysis
orch context set code-analysis-result "Found 3 N+1 queries in UserService"

# ORCH Backend agent reads and acts
# (agent's role prompt: "read context key 'code-analysis-result' and fix the issues")
orch task add "Fix N+1 queries per analysis" \
  -d "Read: orch context get code-analysis-result" -p 1 --assignee <backend-id>

# QA agent writes test results back
orch context set qa-result "PASS: all 47 tests green, coverage 94%"

# Back in ECC session, collect
orch context get qa-result

Programmatic API

ORCH exports a full engine API for embedding in Node.js apps:

import { TaskService, AgentService, OrchestratorService } from '@oxgeneral/orch';

// Use ORCH engine programmatically from your Claude skill
const tasks = await TaskService.list({ status: 'review' });
const pending = tasks.filter(t => t.priority === 1);

Best Practices

  1. One task = one atomic unit of work — avoid mega-tasks; decompose with --depends-on
  2. Pass rich context — agents perform better with file paths, constraints, and examples in -d
  3. Use review gate — don't skip review → done; it catches agent mistakes
  4. Check logs before escalating — orch logs --tail 100 before creating a new task
  5. Context keys are namespaced — use prefixes like qa-, arch-, security- to avoid collisions
  6. Teams for parallel work — orch team list to see groups; assign tasks to team members for parallelism

References

Original metadata

name: orch-runtime
description: Dispatch tasks to a persistent ORCH agent team from Claude Code. Use when you need long-running or multi-session AI workflows that survive beyond a single Claude context window.
origin: community

Attribution and license

MIT License

Copyright (c) 2026 Affaan Mustafa

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.