CLI

The Hubcode CLI lets you manage agents from your terminal. It's the same interface exposed by the daemon's API, so anything you can do in the app you can do from the command line.

Agent orchestration: You can tell coding agents to use the Hubcode CLI to spawn and manage other agents. This enables multi-agent workflows where one agent delegates subtasks to others and waits for results.

Quick reference

hubcode run "fix the tests"           # Start an agent
hubcode ls                             # List running agents
hubcode attach <id>                    # Stream agent output
hubcode send <id> "also fix linting"  # Send follow-up task
hubcode logs <id>                      # View agent timeline
hubcode stop <id>                      # Stop an agent

Running agents

Use hubcode run to start a new agent with a task:

hubcode run "implement user authentication"
hubcode run --provider codex "refactor the API layer"
hubcode run --detach "run the full test suite"  # background
hubcode run --worktree feature-x "implement feature X"
hubcode run --output-schema schema.json "extract release notes"
hubcode run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "summarize release notes"

The --worktree flag creates the agent in an isolated git worktree, useful for parallel feature development.

Use --output-schema to return only matching JSON output. You can pass a schema file path or an inline JSON schema object. This mode cannot be used with --detach.

By default, hubcode run waits for completion. Use --detach to run in the background.

Listing agents

hubcode ls                    # Running agents in current directory
hubcode ls -a                 # Include completed/stopped agents
hubcode ls -g                 # All directories
hubcode ls -a -g --json       # Full list as JSON

Streaming output

Use hubcode attach to stream an agent's output in real-time:

hubcode attach abc123   # Attach to agent (Ctrl+C to detach)

Agent IDs can be shortened — abc works if it's unambiguous.

Sending messages

Send follow-up tasks to a running or idle agent:

hubcode send <id> "now run the tests"
hubcode send <id> --image screenshot.png "what's wrong here?"
hubcode send <id> --no-wait "queue this task"

Viewing logs

hubcode logs <id>                  # Full timeline
hubcode logs <id> -f               # Follow (streaming)
hubcode logs <id> --tail 10        # Last 10 entries
hubcode logs <id> --filter tools   # Only tool calls

Waiting for agents

Block until an agent finishes its current task:

hubcode wait <id>
hubcode wait <id> --timeout 60   # 60 second timeout

Useful in scripts or when one agent needs to wait for another.

Permissions

Agents may request permission for certain actions. Manage these from the CLI:

hubcode permit ls                # List pending requests
hubcode permit allow <id>        # Allow all pending for agent
hubcode permit deny <id> --all   # Deny all pending

Agent modes

Change an agent's operational mode (provider-specific):

hubcode agent mode <id> --list   # Show available modes
hubcode agent mode <id> bypass   # Set bypass mode
hubcode agent mode <id> plan     # Set plan mode

Daemon management

hubcode daemon start             # Start the daemon
hubcode daemon status            # Check status
hubcode daemon stop              # Stop the daemon

Use HUBCODE_HOME to run multiple isolated daemon instances.

Multi-agent workflows

The CLI is designed to be used by agents themselves. You can instruct an agent to spawn sub-agents for parallel work:

# Agent A spawns Agent B and waits for it
hubcode run --detach "implement the API" --name api-agent
hubcode wait api-agent
hubcode logs api-agent --tail 5

Simple implement + verify loop:

# Requires jq
while true; do
  hubcode run --provider codex "make the tests pass" >/dev/null

  verdict=$(hubcode run --provider claude --output-schema '{"type":"object","properties":{"criteria_met":{"type":"boolean"}},"required":["criteria_met"],"additionalProperties":false}' "ensure tests all pass")
  if echo "$verdict" | jq -e '.criteria_met == true' >/dev/null; then
    echo "criteria met"
    break
  fi
done

This pattern enables hierarchical task decomposition — a lead agent can break down work, delegate to specialists, and synthesize results.

Output formats

Most commands support multiple output formats for scripting:

hubcode ls --json                # JSON output
hubcode ls --format yaml         # YAML output
hubcode ls -q                    # IDs only (quiet)

Global options

--host <host:port> — connect to a different daemon
--json — JSON output
-q, --quiet — minimal output
--no-color — disable colors