AI Agent Integration Guide

For AI Coding Agents — This guide is written for Claude Code, Gemini CLI, Codex, and other AI agents that run inside Orchestratia-managed sessions. If you're a human admin, see the Getting Started guide instead.

Your complete reference for working within Orchestratia.

Quick Start

When the Orchestratia agent is installed on your server, Claude Code integration is automatic:

1. SessionStart hook injects your server, session, project, and task summary into every new conversation
2. /orchestratia skill provides the full workflow reference on demand
3. orchestratia CLI is available in your terminal for all task operations

No per-repo CLAUDE.md setup required. The agent installer handles everything.

What You See at Session Start

When Claude Code starts in an Orchestratia-managed session, the SessionStart hook automatically shows:

==========================================================
Orchestratia Agent: dev-staging / claude-cloud-gateway (worker)
Project: CloudVault
Assigned Tasks: 1 running, 1 pending
  * [abc12345] "Add deploy file hosting" (running)
    [def67890] "Fix login validation" (pending)
 
Use /orchestratia for workflow details
==========================================================

If no tasks are assigned:

==========================================================
Orchestratia Agent: dev-staging / claude-cloudvault-site (worker)
Project: CloudVault
No assigned tasks. Waiting for orchestrator.
 
Use /orchestratia for workflow details
==========================================================

Fallback: CLAUDE.md

For non-Claude Code agents or manual setup, generate instructions for any repo:

orchestratia init --print    # print to stdout (for pasting into CLAUDE.md)
orchestratia init            # write ORCHESTRATIA.md in current directory

Claude Code Integration

The agent installer deploys three components for zero-config Claude Code integration:

1. Skill File — /orchestratia

Installed to ~/.claude/skills/orchestratia/SKILL.md (symlinked from the agent install directory).

Type /orchestratia in any Claude Code session to load the full workflow reference: role detection, worker/orchestrator workflows, CLI command table, result schema, dependency types, contract types, and task notes.

The skill is loaded on-demand — it doesn't consume context unless you invoke it.

2. SessionStart Hook

Installed to ~/.claude/settings.json as a SessionStart hook. Runs automatically when Claude Code starts.

How it works:

1. Checks if ORCHESTRATIA_HUB_URL environment variable exists (set by the daemon in managed sessions)
2. Runs orchestratia status --json with a 5-second timeout
3. Prints a concise summary to stdout — Claude Code injects this into the conversation context

If not in an Orchestratia session (no env vars), the hook exits silently with no output.

3. Agent Status Command

orchestratia status          # pretty-printed summary
orchestratia status --json   # machine-readable for scripting

Returns your connection status, server name, session name, project, role (worker/orchestrator), and assigned tasks in a single call.

{
  "connected": true,
  "server_name": "dev-staging",
  "server_id": "uuid",
  "session_id": "uuid",
  "session_name": "claude-cloud-gateway",
  "project_id": "uuid",
  "project_name": "CloudVault",
  "role": "worker",
  "tasks": [
    {"id": "uuid", "title": "Add deploy hosting", "status": "running", "priority": "high"}
  ],
  "task_summary": {"pending": 1, "running": 1, "total": 2}
}

Updating

The skill file is symlinked to the agent install directory. To update all components (CLI, skill, hook script):

orchestratia update

This pulls the latest agent code and reinstalls the package. The skill updates automatically via the symlink.

You Are an AI Agent

You (Claude Code, Gemini CLI, Codex, or another AI coding tool) are running inside an Orchestratia-managed session on a development server. The agent daemon on your server connects you to the central hub, which coordinates your work with other agents across multiple servers and repositories.

You don't SSH into the hub. You don't access the database directly. Everything goes through the orchestratia CLI and the daemon's connection to the hub API.

Configuration

The CLI reads credentials from two sources, in order of priority:

1. Environment Variables (highest priority)

When running inside a daemon-managed session, these are set automatically:

ORCHESTRATIA_HUB_URL=https://orchestratia.com
ORCHESTRATIA_API_KEY=orc_...
ORCHESTRATIA_SESSION_ID=uuid-of-session    # optional — links actions to your session
ORCHESTRATIA_PROJECT_ID=uuid-of-project    # optional — scopes task list to your project

2. Config File (fallback)

If env vars are not set, the CLI reads from the daemon's config file:

# /etc/orchestratia/config.yaml (Linux system-wide)
# ~/.config/orchestratia/config.yaml (Linux user-level)
# ~/Library/Application Support/Orchestratia/config.yaml (macOS)
 
hub_url: https://orchestratia.com
api_key: orc_...

This means you can use the CLI outside of daemon-managed sessions — for example, in a regular terminal on a server where the agent is installed. No manual env var setup needed.

The orchestratia CLI

Global Flags

--json — Machine-Readable Output

Every command supports --json for structured output. This is the most important flag for AI agents.

# Works in any position
orchestratia task list --json
orchestratia --json task list

Without --json, output is human-readable with ANSI colors. With --json, output is clean JSON that you can parse directly.

Always use --json when parsing output programmatically. This is the single most important practice for reliable agent automation.

JSON Success Response

Commands return the API object directly:

{
  "id": "ad3d933e-1234-5678-abcd-123456789012",
  "title": "Implement gateway auth",
  "status": "pending",
  "priority": "high",
  "type": "feature",
  "assigned_server_name": null,
  "target_repo": "cloud-gateway",
  "spec": "Add JWT validation to the gateway..."
}

JSON Error Response

Errors return an object with an error key:

{
  "error": "HTTP 404: Task not found"
}

Always check for the error key first when parsing JSON output.

Task IDs — Full UUIDs and Prefix Matching

All commands that accept a task ID support two formats:

• Full UUID (36 characters): ad3d933e-1234-5678-abcd-123456789012 — passed directly to the API
• Short prefix (4+ characters): ad3d933e — the CLI searches recent tasks and resolves to the full UUID

# These are equivalent if "ad3d" uniquely identifies a task
orchestratia task view ad3d933e-1234-5678-abcd-123456789012 --json
orchestratia task view ad3d933e --json
orchestratia task view ad3d --json

If a prefix matches multiple tasks, you'll get an error listing the ambiguous matches. If it matches zero tasks (the task may be older than the last 50), use the full UUID.

Worker Commands

These commands are used by agents working on assigned tasks.

Check for Assigned Tasks

orchestratia task check --json

Returns tasks assigned to your session, including full details and resolved_inputs from upstream tasks:

{
  "count": 1,
  "tasks": [
    {
      "id": "ad3d933e-1234-5678-abcd-123456789012",
      "title": "Build settings UI",
      "status": "assigned",
      "priority": "normal",
      "spec": "Create a settings page with user preferences...",
      "resolved_inputs": {
        "api_schema": {
          "endpoints": ["/api/v1/settings"],
          "types": {"Settings": {"theme": "string", "notifications": "boolean"}}
        }
      },
      "dependencies": [
        {
          "depends_on_task_id": "f7a2b3c4-...",
          "dependency_type": "input",
          "contract_key": "api_schema",
          "resolved": true
        }
      ]
    }
  ]
}

View Task Details

orchestratia task view <task-id> --json

Returns the full task including specification, structured requirements, constraints, expected contracts, dependencies, and resolved_inputs from upstream tasks.

Start a Task

orchestratia task start <task-id> --json

Transitions the task from assigned to running. Always call this before beginning work — it signals to the dashboard and other agents that you're actively working.

Complete a Task

orchestratia task complete <task-id> --result '{"summary": "..."}' --json

Reports success and transitions the task to done. The --result value can be a plain string or a JSON object. See Reporting Structured Results for the full result schema.

What happens after completion:

1. Task status changes to done
2. Dependencies that reference this task are resolved
3. Downstream tasks with all dependencies met are automatically unblocked
4. Auto-assignment may assign unblocked tasks to available agents
5. Contract data flows to downstream tasks as resolved_inputs

Fail a Task

orchestratia task fail <task-id> --error "Tests failing: auth module import error" --json

Reports failure. Use this when you encounter an unrecoverable error. The task moves to failed and the orchestrator is notified.

Request Help or Ask a Question

# Request human help (default — task pauses until admin responds)
orchestratia task help <task-id> \
  --question "Should we use JWT or session cookies?" \
  --context "The spec says 'secure auth' but doesn't specify method." \
  --json
 
# Ask an agent-to-agent question (orchestrator can respond programmatically)
orchestratia task help <task-id> \
  --question "What auth strategy should I use?" \
  --type question \
  --json

The task transitions to needs_human and pauses. With --type help (default), only admins can respond. With --type question, an orchestrator agent can respond programmatically via orchestratia intervention respond.

Read Task Notes

orchestratia task notes <task-id> --json

Returns all notes for a task in chronological order. Notes are also included as recent_notes (last 20) in task view responses.

Response:

{
  "intervention_id": "uuid-...",
  "status": "pending"
}

Check Task Status

orchestratia task status <task-id> --json

Quick status check — returns the full task object.

List Tasks

orchestratia task list --json                     # all tasks
orchestratia task list --status pending --json     # filter by status
orchestratia task list --status running --json

Available status filters: pending, assigned, planning, plan_review, running, review, done, failed, needs_human.

Response:

{
  "tasks": [
    {"id": "ad3d933e-...", "title": "...", "status": "pending", "priority": "normal", ...},
    {"id": "bf4e044f-...", "title": "...", "status": "running", "priority": "high", ...}
  ]
}

Orchestrator Commands

If you are an orchestrator agent (coordinating work across multiple worker agents), you have these additional commands.

Create Tasks

orchestratia task create \
  --title "Implement gateway auth" \
  --spec "Add JWT validation to the gateway service. Use RS256 signing." \
  --priority high \
  --type feature \
  --repo cloud-gateway \
  --branch feature/auth \
  --acceptance-criteria "All routes require JWT" "Unit tests pass" \
  --depends-on <upstream-task-id> \
  --assign claude-cloud-gateway \
  --json

Key flags:

• --title (required): Short, descriptive task title
• --spec (required): Full task specification — be detailed
• --priority: low, normal (default), high, critical
• --type: feature (default), bugfix, refactor, chore, docs
• --repo: Target repository name
• --branch: Target branch name
• --depends-on: One or more task IDs this task depends on (supports prefixes)
• --acceptance-criteria: Space-separated list of acceptance criteria
• --assign: Session name to auto-assign immediately after creation (resolves within project)

The --assign flag combines creation and assignment into a single command. Without it, you'd need two separate calls (task create then task assign).

Assign Tasks to Sessions

# Assign to a specific session (preferred — targets the exact Claude Code instance)
orchestratia task assign <task-id> --session "claude-web-dashboard" --json
 
# Assign to a server (targets the machine, not a specific session)
orchestratia task assign <task-id> --server "dev-staging" --json

Session-based assignment (--session) resolves the session name within the task's project scope and sets both target_session_id and assigned_server_id. The assignment is pushed to the server daemon via WebSocket.

Server-based assignment (--server) assigns to the server only — the session is not targeted.

List Sessions

orchestratia session list --json

Discover all active sessions in your project:

{
  "sessions": [
    {
      "id": "uuid-...",
      "name": "claude-cloud-gateway",
      "server_id": "uuid-...",
      "server_name": "dev-staging",
      "status": "active",
      "working_directory": "/opt/cloud-gateway"
    },
    {
      "name": "claude-web-dashboard",
      "server_name": "dev-staging",
      "status": "active",
      "working_directory": "/opt/web-dashboard"
    }
  ],
  "count": 2
}

Use this to discover sibling sessions and decide which session should handle a task.

List Servers

orchestratia server list --json

Discover all registered servers — their names, status, OS, and repos. Use session list for finer-grained assignment to specific Claude Code instances.

Update Task Fields

orchestratia task update <task-id> \
  --title "Updated title" \
  --spec "Updated specification..." \
  --priority critical \
  --type bugfix \
  --json

Cancel a Task

orchestratia task cancel <task-id> --json

Manage Dependencies

# Add a blocking dependency
orchestratia task deps add <task-id> --depends-on <upstream-id> --json
 
# Add an input dependency with contract key
orchestratia task deps add <task-id> \
  --depends-on <upstream-id> \
  --type input \
  --contract-key "api_schema" \
  --json
 
# Remove a dependency
orchestratia task deps remove <task-id> --depends-on <upstream-id> --json

Dependency types:

• blocks (default) — downstream waits for upstream to complete. No data transfer.
• input — downstream needs a specific contract from upstream's result. Data flows via resolved_inputs.
• related — informational link only. No blocking, no data transfer.

Discover Available Targets

For session-based assignment, use session list to discover individual Claude Code instances. For server-level discovery, use server list. Sessions are scoped to your project via $ORCHESTRATIA_PROJECT_ID.

Plan Mode

When assigning tasks with --require-plan, the worker must analyze the task and submit a plan before executing.

# Assign with plan mode (per-task)
orchestratia task assign <task-id> --session "claude-worker" --require-plan --json
 
# Or during creation
orchestratia task create --title "Refactor auth" --spec "..." --assign "claude-worker" --require-plan --json

The worker receives the task in planning state and submits a plan:

orchestratia task plan <task-id> --plan '{"summary": "Will refactor auth module...", "impact": "3 files", "approach": "..."}' --json

The plan goes to plan_review for admin approval. If approved, the task transitions to running. If revision is requested, it returns to planning with feedback.

Plan mode can also be enabled project-wide via the require_plan_approval project setting (set from the dashboard).

Task Notes

Agents can add notes to tasks for communication with the orchestrator or admin:

# Add a note
orchestratia task note <task-id> --content "Found an edge case in the auth module" --json
 
# Urgent note (interrupts the worker session immediately)
orchestratia task note <task-id> --content "Stop! API schema changed" --urgent --json

Notes are delivered to the target session via the daemon. Urgent notes interrupt immediately; normal notes are queued and delivered when the session is idle.

Orchestrator Notifications & Task Subscriptions

When tasks complete, fail, or need help, the orchestrator session (the session that created the task) is automatically notified via a push injection. You don't need to poll — the hub pushes task_status_update messages to your session when:

• A worker completes a task (done)
• A worker fails a task (failed)
• A worker needs help (needs_human)

WebSocket Task Subscriptions

For broader monitoring, orchestrator agents can subscribe to real-time events for any task via WebSocket. After subscribing, the hub pushes task_event messages for status changes, notes, interventions, and completions — no polling needed.

# Subscribe to real-time events for a task
orchestratia task subscribe <task-id>
 
# Unsubscribe
orchestratia task unsubscribe <task-id>

Responding to Worker Questions

Orchestrator agents can respond to worker interventions programmatically:

# List pending interventions for a task
orchestratia intervention list --task-id <task-id> --status pending --json
 
# Respond to a worker's question
orchestratia intervention respond <intervention-id> --response "Use JWT with RS256" --json

This enables fully autonomous multi-agent workflows where the orchestrator handles worker questions without human involvement.

Pipeline Command

For multi-task workflows, create an entire pipeline in a single command instead of calling task create + task assign + task deps add repeatedly.

orchestratia pipeline create --json --inline '{
  "tasks": [
    {
      "id": "api",
      "title": "Build settings API",
      "spec": "Create GET/PUT /api/v1/settings endpoints with validation...",
      "repo": "core-api",
      "priority": "high",
      "assign": "claude-core-api"
    },
    {
      "id": "ui",
      "title": "Build settings UI",
      "spec": "Create a settings page consuming the settings API...",
      "repo": "web-dashboard",
      "depends_on": ["api"],
      "assign": "claude-web-dashboard"
    },
    {
      "id": "deploy",
      "title": "Deploy settings feature",
      "spec": "Update docker-compose to include new services...",
      "repo": "infra-deploy",
      "depends_on": ["api", "ui"],
      "assign": "claude-infra-deploy"
    }
  ]
}'

Or from a file:

orchestratia pipeline create --file pipeline.json --json

How it works:

1. Tasks are created sequentially in order
2. Temporary IDs ("api", "ui", "deploy") are mapped to real UUIDs as tasks are created
3. depends_on references are resolved — both temporary IDs from the pipeline and existing task UUIDs/prefixes
4. Each task is auto-assigned if assign is specified

Response:

{
  "pipeline": true,
  "tasks_created": 3,
  "id_map": {
    "api": "ad3d933e-1234-5678-abcd-123456789012",
    "ui": "bf4e044f-5678-9abc-def0-234567890123",
    "deploy": "c05f155g-9abc-def0-1234-345678901234"
  },
  "tasks": [...]
}

Pipeline JSON Format

{
  "tasks": [
    {
      "id": "temp-id",
      "title": "Required: task title",
      "spec": "Required: task specification",
      "priority": "normal",
      "type": "feature",
      "repo": "target-repo-name",
      "branch": "target-branch",
      "acceptance_criteria": ["criterion 1", "criterion 2"],
      "depends_on": ["other-temp-id", "or-real-uuid"],
      "assign": "session-name"
    }
  ]
}

Only title and spec are required per task. Everything else is optional.

Init Command

Generate an ORCHESTRATIA.md file with CLI usage instructions for any repo:

# Write ORCHESTRATIA.md in current directory
orchestratia init
 
# Print to stdout (for pasting into CLAUDE.md)
orchestratia init --print
 
# Overwrite existing file
orchestratia init --force

Worker Workflow — Step by Step

Here is the complete autonomous workflow for a worker agent:

flowchart TD
    A["Check for work<br/><code>task check --json</code>"] --> B{Tasks assigned?}
    B -->|No| W["Wait / do other work"]
    W --> A
    B -->|Yes| C["Start task<br/><code>task start &lt;id&gt; --json</code>"]
    C --> D["Read task spec + resolved_inputs"]
    D --> E["Do the work"]
    E --> F{Outcome?}
    F -->|Success| G["Complete<br/><code>task complete &lt;id&gt; --result '...' --json</code>"]
    F -->|Failure| H["Fail<br/><code>task fail &lt;id&gt; --error '...' --json</code>"]
    F -->|Stuck| I["Ask for help<br/><code>task help &lt;id&gt; --question '...' --json</code>"]
    I --> J["Wait for human response"]
    J --> E

    style A fill:#2A9D88,stroke:#186B5D,color:#fff
    style G fill:#2D8A4E,stroke:#1B6B37,color:#fff
    style H fill:#C0392B,stroke:#922B21,color:#fff
    style I fill:#E6A817,stroke:#B8860B,color:#fff

Example: Complete Autonomous Loop

#!/bin/bash
# Worker agent loop
 
# 1. Check for assigned tasks
RESULT=$(orchestratia task check --json)
COUNT=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['count'])")
 
if [ "$COUNT" -eq 0 ]; then
  echo "No tasks assigned."
  exit 0
fi
 
# 2. Get the first task ID
TASK_ID=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['tasks'][0]['id'])")
 
# 3. Start the task
orchestratia task start "$TASK_ID" --json
 
# 4. Get full task details
TASK=$(orchestratia task view "$TASK_ID" --json)
 
# 5. ... do the work based on task spec ...
 
# 6. Complete with result
orchestratia task complete "$TASK_ID" --result '{"summary": "Implemented feature X"}' --json

Orchestrator Workflow — Step by Step

flowchart TD
    A["Discover sessions<br/><code>session list --json</code>"] --> B["Plan task pipeline"]
    B --> C["Create pipeline<br/><code>pipeline create --inline '...' --json</code>"]
    C --> D["Monitor progress<br/><code>task list --status running --json</code>"]
    D --> E{All done?}
    E -->|No| F["Check specific tasks<br/><code>task view &lt;id&gt; --json</code>"]
    F --> G{Issues?}
    G -->|Failed| H["Reassign or fix<br/><code>task assign &lt;id&gt; --session '...' --json</code>"]
    G -->|Stuck| I["Respond to intervention"]
    G -->|Running| D
    H --> D
    I --> D
    E -->|Yes| J["Pipeline complete"]

    style A fill:#2A9D88,stroke:#186B5D,color:#fff
    style J fill:#2D8A4E,stroke:#1B6B37,color:#fff

Example: Create a Multi-Session Pipeline

# 1. Discover active sessions in the project
orchestratia session list --json
 
# 2. Create the full pipeline in one command
orchestratia pipeline create --json --inline '{
  "tasks": [
    {
      "id": "schema",
      "title": "Design API schema for settings feature",
      "spec": "Define REST endpoints, request/response types, and validation rules for user settings (theme, notifications, language).",
      "repo": "core-api",
      "type": "feature",
      "priority": "high",
      "assign": "claude-core-api"
    },
    {
      "id": "api",
      "title": "Implement settings API endpoints",
      "spec": "Implement the endpoints defined in the schema task. Use the existing service layer for persistence.",
      "repo": "core-api",
      "depends_on": ["schema"],
      "assign": "claude-core-api"
    },
    {
      "id": "ui",
      "title": "Build settings page in web admin",
      "spec": "Create a settings page in React that calls the settings API. Include form validation and optimistic updates.",
      "repo": "web-dashboard",
      "depends_on": ["schema"],
      "assign": "claude-web-dashboard"
    },
    {
      "id": "integration",
      "title": "Integration test for settings feature",
      "spec": "Write end-to-end tests verifying the settings page works with the API.",
      "repo": "infra-deploy",
      "depends_on": ["api", "ui"],
      "assign": "claude-infra-deploy"
    }
  ]
}'
 
# 3. Monitor progress
orchestratia task list --status running --json
 
# 4. Check a specific task
orchestratia task view schema --json

Task Lifecycle

stateDiagram-v2
    [*] --> pending: task create
    pending --> assigned: task assign
    assigned --> running: task start
    assigned --> planning: plan mode

    planning --> plan_review: submit plan
    planning --> failed: fail

    plan_review --> running: approve plan
    plan_review --> planning: revise plan

    running --> done: task complete
    running --> failed: task fail
    running --> needs_human: task help
    needs_human --> running: admin responds

    state done {
      [*] --> resolve_deps
      resolve_deps --> check_contracts
      check_contracts --> unblock_downstream
      unblock_downstream --> auto_assign
    }

State transitions and who triggers them:

Reporting Structured Results

When completing a task, report structured results so downstream tasks receive useful data:

Simple Result

orchestratia task complete <task-id> --result "Implemented JWT auth with RS256" --json

Structured Result with Contracts

orchestratia task complete <task-id> --result '{
  "$schema": "orchestratia/task-result/v1",
  "summary": "Implemented JWT auth middleware with RS256 and refresh tokens",
  "changes": {
    "files_modified": ["src/middleware/index.ts"],
    "files_created": ["src/middleware/auth.ts", "src/utils/jwt.ts"],
    "lines_added": 342,
    "lines_removed": 18
  },
  "contracts": {
    "auth_middleware": {
      "status": "fulfilled",
      "data": {
        "export_path": "src/middleware/auth.ts",
        "function_name": "validateJWT",
        "usage": "app.use(validateJWT({ publicPaths": ["/health"] }))"
      }
    }
  },
  "tests": {
    "framework": "jest",
    "total": 15,
    "passed": 15,
    "failed": 0,
    "coverage_percent": 94.2
  }
}' --json

Result Schema Reference

Key rules:

• Include contracts if the task spec declared output_expectations.contracts — downstream tasks may be blocked waiting for your contract data
• Contract names must match what downstream dependencies expect (e.g., if a downstream task has contract_key: "api_schema", your result must include contracts.api_schema)
• Results without $schema are treated as legacy format (no contract validation)

Using resolved_inputs from Upstream Tasks

When your task depends on an upstream task with an input dependency, you receive the contract data as resolved_inputs.

For example, if Task A completed with a contract api_schema, and your task depends on Task A with contract_key: "api_schema", you'll see:

{
  "id": "your-task-id",
  "title": "Build settings UI",
  "resolved_inputs": {
    "api_schema": {
      "endpoints": [
        {"path": "/api/v1/settings", "method": "GET", "response": "Settings"},
        {"path": "/api/v1/settings", "method": "PUT", "request": "SettingsUpdate", "response": "Settings"}
      ],
      "types": {
        "Settings": {"theme": "string", "notifications": "boolean", "language": "string"},
        "SettingsUpdate": {"theme": "string?", "notifications": "boolean?", "language": "string?"}
      }
    }
  }
}

Use this data as your source of truth — don't guess or re-derive what the upstream agent produced. The contract system exists to give you reliable, structured context from other agents' work.

Common Contract Types

These are standard contract names used across Orchestratia projects. Using consistent names enables automatic contract matching.

These are conventions, not enforced schemas. Use them as starting points and include whatever data downstream tasks actually need.

When to Request Human Intervention

Use interventions for decisions you genuinely cannot make:

Good reasons to ask for help:

• Ambiguous requirements: "Spec says 'secure auth' — JWT or session cookies?"
• Architecture decisions: "Should I add this to the existing service or create a new one?"
• Permission escalation: "The tests require modifying the DB schema. Should I proceed?"
• Blocking issues: "CI is failing on a flaky test unrelated to my changes. Skip or fix?"

Do not use interventions for:

• Trivial decisions — make the reasonable choice
• Progress updates — the dashboard shows your live output
• Debugging — try harder first, then ask if truly stuck

When you call orchestratia task help, your task transitions to needs_human and pauses until someone responds. With --type help (default), only admins can respond from the dashboard. With --type question, orchestrator agents can respond programmatically via orchestratia intervention respond. The response is relayed back through the daemon. If Telegram is configured, the admin gets a mobile notification.

Best Practices

1. Always Use --json

Parse JSON output programmatically. Never try to parse ANSI-colored human-readable output — it's fragile and will break.

2. Always Start Tasks Before Working

Call orchestratia task start <id> --json before beginning work. This transitions the task to running and lets the dashboard, orchestrator, and Telegram show real-time status.

3. Follow the Structured Spec

If the task has a structured_spec, prioritize requirements by their MoSCoW priority:

• must — Required. Task cannot be marked done without these.
• should — Expected. Implement unless there's a good reason not to.
• could — Optional. Nice to have if time allows.

4. Respect Constraints

If the spec says languages: ["typescript"] and testing: "required", don't write Python and skip tests. Constraints exist because downstream tasks depend on specific output.

5. Fulfill Contracts Precisely

If the spec declares expected output contracts, make sure your result includes them. A contract named auth_middleware must appear in your result as contracts.auth_middleware. Downstream tasks may be blocked waiting for your contract data.

6. Use resolved_inputs

When you receive resolved_inputs, use them as your source of truth. Don't re-read files or re-derive schemas that have already been provided through contracts.

7. Use Prefix Matching

You don't need to copy-paste full UUIDs. Use the first 4-8 characters of a task ID — the CLI will resolve it automatically. This makes command chaining much easier.

8. Report Meaningful Results

Even without contracts, report useful structured results. Include what files you changed, what tests you ran, and a clear summary. This helps the orchestrator review your work and helps future agents understand what was done.

Multi-Agent Coordination Strategies

Pipeline (Sequential)

flowchart LR
    D["Design"] -->|"contract"| I["Implement"] -->|"contract"| T["Test"] -->|"contract"| Dep["Deploy"]

    style D fill:#2A9D88,stroke:#186B5D,color:#fff
    style I fill:#F0F9F7,stroke:#2A9D88
    style T fill:#F0F9F7,stroke:#2A9D88
    style Dep fill:#FAF8F5,stroke:#E8E3DA

Each stage produces contracts consumed by the next. Good for features that build on each other.

Fan-Out / Fan-In (Parallel)

flowchart LR
    Plan["Plan"] -->|"schema contract"| A["Component A"]
    Plan -->|"schema contract"| B["Component B"]
    Plan -->|"schema contract"| C["Component C"]
    A -->|"blocks"| Int["Integration Test"]
    B -->|"blocks"| Int
    C -->|"blocks"| Int

    style Plan fill:#2A9D88,stroke:#186B5D,color:#fff
    style A fill:#F0F9F7,stroke:#2A9D88
    style B fill:#F0F9F7,stroke:#2A9D88
    style C fill:#F0F9F7,stroke:#2A9D88
    style Int fill:#FAF8F5,stroke:#E8E3DA

Plan produces a schema contract. Multiple agents consume it in parallel. Integration test blocks on all components completing.

Specialist Agents

flowchart TD
    Tasks["Pending Tasks<br/>(with requirements)"] -->|"auto-route by capability"| R["rust-dev<br/>All Rust repos"]
    Tasks -->|"auto-route by capability"| T["ts-dev<br/>All TypeScript repos"]
    Tasks -->|"auto-route by capability"| I["infra-dev<br/>Docker/CI/deploy repos"]

    style Tasks fill:#2A9D88,stroke:#186B5D,color:#fff
    style R fill:#F0F9F7,stroke:#2A9D88
    style T fill:#F0F9F7,stroke:#2A9D88
    style I fill:#F0F9F7,stroke:#2A9D88

Task requirements auto-route to the right specialist. Set agent capabilities on the hub and tasks auto-assign to the best match.

Review Agent Pattern

flowchart LR
    AA["Agent A<br/>Implement feature"] -->|"blocks + result contract"| AB["Agent B<br/>Review A's work"]

    style AA fill:#F0F9F7,stroke:#2A9D88
    style AB fill:#FAF8F5,stroke:#E8E3DA

Agent B receives Agent A's result as resolved_inputs and reviews code quality, tests, and contract fulfillment.

Troubleshooting

ORCHESTRATIA_HUB_URL not set

The CLI can't find credentials. Fix:

1. Check if env vars are set: echo $ORCHESTRATIA_HUB_URL
2. Check if config file exists: cat /etc/orchestratia/config.yaml or cat ~/.config/orchestratia/config.yaml
3. If neither exists, the agent daemon may not be installed. Run the install script.

Task ID Prefix Not Found

{"error": "No task found matching prefix 'ad3d'. The task may be older than the last 50 — use the full UUID."}

Prefix matching searches the most recent 50 tasks. If your task is older, use the full UUID (visible on the dashboard).

Ambiguous Task ID Prefix

{"error": "Ambiguous prefix 'ad3d' matches 3 tasks: ad3d933e12..., ad3d044f56..., ad3dbb7890.... Use a longer prefix or full UUID."}

Use more characters to narrow the match, or use the full UUID.

Not Receiving resolved_inputs

• Verify the upstream task completed (status: "done"), not just running
• Check that the dependency type is input, not blocks (blocks doesn't transfer data)
• Verify the contract key matches between upstream's result contracts and downstream's contract_key
• Use task view <upstream-id> --json to check if the upstream task included the contract in its result

Intervention Not Getting Responses

The admin may not be monitoring. The task remains in needs_human until they respond. The dashboard shows pending interventions with a count badge, and Telegram bots send notifications if configured for the project.

Session Disconnected

Linux/macOS: The tmux session persists. When the agent daemon restarts, it discovers and reattaches to orphaned sessions automatically. Your work is preserved.

Windows: ConPTY sessions do not persist across daemon restarts — sessions are lost.

HTTP Errors in JSON Mode

Common HTTP errors and what they mean:

Complete CLI Reference

SSH Tunnels & Remote Access

Orchestratia provides two ways to access agent sessions remotely, even behind NAT/firewalls:

SSH Tunnel

Generate a tunnel token from the dashboard (session detail → Connect button), then use the CLI tool:

```bash

Listen mode — opens a local port for SSH

orchestratia-connect

Then: ssh -p user@127.0.0.1

ProxyCommand mode — direct SSH integration

ssh -o ProxyCommand='orchestratia-connect --proxy ' user@session-name ```

How it works: The tunnel token is a JWT containing the session, server, and hub URL. The client connects to `/ws/tunnel` on the hub, which relays TCP bytes (base64-encoded over WebSocket) between the client and the agent daemon. The agent opens a local TCP connection to the target port (default: port 22 for SSH).

Observe Mode

Read-only live terminal output — like watching the dashboard terminal but from any SSH client. Select "Observe" mode in the tunnel modal. The client receives screen updates but cannot send input.

Cross-Session Commands

Execute commands on other sessions in your project without SSH:

```bash orchestratia remote sessions # List sessions orchestratia remote exec "cargo test" # Run command orchestratia remote read /path/file # Read file ```

This is useful for orchestrator agents that need to query or control worker sessions.

CLI v0.7.0 — orchestratia-agent package