hydra-os-cli

Terminal user interface for the Hydra multi-agent workflow orchestrator. Monitor workflows, approve decisions, and manage agents from your terminal.

Built with Ink (React for CLI), TypeScript, and Zustand.

Install

npm install -g hydra-os-cli

Or run without installing:

npx hydra-os-cli doctor --json

Prerequisites

• Node.js 18+
• Hydra API running on http://localhost:7070 (or configured via ~/.hydra/config.yaml)
• Temporal server running on localhost:7233

CLI Usage

hydra-os                                Launch interactive TUI (default)
hydra-os --attach <workflow-id>         Launch and attach to a running workflow
hydra-os --theme <name>                 Launch with a specific theme
hydra-os status <workflow-id>           Check workflow status (non-interactive)
hydra-os status <workflow-id> --json    Output status as JSON
hydra-os list                           List all workflows (non-interactive)
hydra-os list --json                    Output workflow list as JSON
hydra-os doctor                         Run service health checks (non-interactive)
hydra-os doctor --json                  Output health checks as JSON

JSON Output

All non-interactive commands support --json for scriptable output:

# Pipe workflow list to jq
hydra-os list --json | jq '.[].status'

# Check a specific workflow programmatically
hydra-os status wf-abc123 --json | jq '.status.phase'

# Health check in CI
hydra-os doctor --json | jq '.api.status'

Examples

# Start the interactive TUI
hydra-os

# Attach to a workflow on launch
hydra-os --attach wf-abc123

# Check a workflow from the command line without entering the TUI
hydra-os status wf-abc123

# List all workflows
hydra-os list

# Health check all services
hydra-os doctor

Development Mode

cd apps/tui
npm install
npm run dev

Interactive Commands

Once inside the TUI, type slash commands in the input bar. Press Tab to autocomplete.

Core

| Command | Description | |------------|------------------------------------------------| | /help | Show all available commands | | /clear | Clear chat output | | /doctor | Health check (API, Temporal, Qdrant, workers) |

Workflow

| Command | Description | |----------------------------------|--------------------------------------| | /start <description> | Start a new workflow from natural language | | /status [workflow-id] | Show workflow status (defaults to active) | | /list | List all workflows | | /attach <workflow-id> | Attach to a workflow's live SSE stream | | /detach | Detach from live stream | | /approve [workflow-id] | Approve pending approval | | /deny [workflow-id] [feedback] | Deny pending approval with optional feedback | | /pause [workflow-id] | Pause a running workflow | | /resume [workflow-id] | Resume a paused workflow | | /cancel confirm [workflow-id] | Cancel a workflow (requires confirm) |

Agent

| Command | Description | |------------------|--------------------------------------| | /agents | List all agent roles and their status | | /agent <role> | Show details for a specific agent role |

Config

| Command | Description | |-----------|----------------------------------------| | /roles | Show role catalog from config/roles.yaml |

Keyboard Shortcuts

| Key | Action | |----------|----------------------| | Ctrl+P | Toggle side panels | | Ctrl+D | Exit | | Tab | Autocomplete command |

Layout

The TUI uses a split-pane layout:

┌──────────────────────────────────────────────────────────┐
│ Hydra TUI v0.1.0                        ● IDLE          │
├───────────────────────────────────┬──────────────────────┤
│                                   │ Agents               │
│  Chat / Command Output            │  ○ pm.prd    pending │
│                                   │  ⏳ eng.init running │
│                                   │  ...                 │
│                                   ├──────────────────────┤
│                                   │ Artifacts            │
│                                   │  📄 prd.md           │
│                                   ├──────────────────────┤
│                                   │ Memory               │
│                                   │  3 decisions, 7 facts│
├───────────────────────────────────┴──────────────────────┤
│ > /start Build a REST API for user auth                  │
├──────────────────────────────────────────────────────────┤
│ no workflow    —    tokens: 0    $0.00    0s             │
└──────────────────────────────────────────────────────────┘

Toggle the right panel with Ctrl+P for a full-width chat view.

Configuration

The TUI reads configuration from ~/.hydra/config.yaml with sensible defaults. No config file is required — everything works out of the box for local development.

Config File

Create ~/.hydra/config.yaml:

temporal:
  address: localhost:7233
  namespace: default

api:
  url: http://localhost:7070

qdrant:
  url: http://localhost:6333

tui:
  theme: dark          # dark, light, solarized, monokai, hydra
  layout: split        # split, full
  rightPanel: true
  vimMode: false
  maxHistory: 1000     # max chat messages kept in memory
  spinnerStyle: dots   # dots, line, arc, bounce

workflow:
  defaultModel: claude-sonnet-4-5-20250929
  autoApproveReads: true
  qualityThreshold: 28
  costWarning: 5.0     # warn when workflow cost exceeds this ($)

notifications:
  sound: true
  desktop: true
  idleAlert: 300       # seconds before idle alert

Environment Variable Overrides

Environment variables take precedence over the config file:

| Variable | Overrides | Example | |--------------------|-------------------|------------------------------| | TEMPORAL_ADDRESS | temporal.address | localhost:7233 | | HYDRA_API_URL | api.url | http://localhost:7070 | | QDRANT_URL | qdrant.url | http://localhost:6333 | | HYDRA_THEME | tui.theme | dark |

# Example: connect to a remote API
HYDRA_API_URL=http://192.168.1.50:7070 npm run dev

Development

# Typecheck
npm run typecheck

# Run tests
npm test

# Build to dist/
npm run build

Project Structure

src/
  cli.tsx              CLI entry point (Commander)
  app.tsx              Main Ink application component
  store.ts             Zustand state store
  config.ts            Config loading and validation (Zod)
  sse.ts               SSE streaming with reconnection
  clients/
    api.ts             REST API client
    temporal.ts        Temporal client (stub)
    qdrant.ts          Qdrant client (stub)
  commands/
    registry.ts        Command registry with autocomplete
    index.ts           Command registration
    core.ts            /help, /clear, /doctor
    workflow.ts         /start, /status, /list, /approve, ...
    agent.ts           /agents, /agent
    config.ts          /roles, /config, /theme
    artifact.ts        Artifact commands (Phase 3)
    memory.ts          Memory commands (Phase 3)
    session.ts         Session commands (Phase 4)
  widgets/
    header.tsx         Header bar
    chat-panel.tsx     Chat message display (windowed)
    agent-panel.tsx    Agent status panel
    artifact-tree.tsx  Artifact tree view
    memory-panel.tsx   Memory stats panel
    input-bar.tsx      Input with Tab autocomplete
    status-bar.tsx     Footer status bar
    timeline.tsx       Workflow timeline
    health-check.tsx   Health check display
    approval-modal.tsx Approval modal
  screens/
    main.tsx           Main screen (re-exports App)
    help.tsx           Help screen
    workflow-detail.tsx Workflow detail view
    workflow-list.tsx  Workflow list view

Typical Workflow

1. Launch the TUI: npm run dev
2. Check services are healthy: /doctor
3. Start a workflow: /start Build a user authentication system with JWT
4. Watch progress via the agent panel and chat stream
5. Attach to live updates if not already streaming: /attach <workflow-id>
6. Approve when prompted: /approve
7. Check final status: /status
8. List all workflows: /list