| name | hubcode |
| description | Hubcode reference for managing agents and worktrees. Load whenever you need to create agents, send them prompts, or manage worktrees. |
Hubcode is a daemon that supervises AI coding agents on your machine. Control it through tools or a CLI.
Worktrees
create_worktree — three modes:
- From a PR:
{ githubPrNumber: 503 }.
- Branch off a base:
{ action: "branch-off", branchName: "fix/foo", baseBranch: "main" }.
- Checkout an existing ref:
{ action: "checkout", refName: "feat/bar" }.
Returns { branchName, worktreePath }. Pass cwd to target a specific repo.
list_worktrees — current repo (or pass cwd).
archive_worktree — { worktreePath } or { worktreeSlug }. Removes worktree and branch.
Agents
create_agent — required: title, provider (claude/opus, codex/gpt-5.4, …), initialPrompt. Common: cwd (often a worktreePath), background (default false — blocks until completion or permission), notifyOnFinish. Returns { agentId, … }.
Compose: call create_worktree first, then create_agent with cwd set to the returned worktreePath.
send_agent_prompt — { agentId, prompt }. Blocks by default; pass background: true to fire-and-forget.
list_agents — filter by cwd, statuses, sinceHours, includeArchived.
archive_agent — { agentId }. Interrupts if running, removes from active list.
Heartbeats
create_schedule — required: prompt. Pick one of cron or every ("5m", "1h"). Optional: name, target (self | new-agent), provider, maxRuns, expiresIn. Use for periodic checks on long-running work or recurring maintenance.
Models
claude/sonnet (default), claude/opus (harder reasoning), codex/gpt-5.4 (frontier coding), claude/haiku (tests only).
Waiting
create_agent and send_agent_prompt block by default — trust them. Real tasks take 10–30+ minutes routinely. Don't poll list_agents or get_agent_status to "check on" a blocking call. To work in parallel, pass background: true and call wait_for_agent later.
CLI parity
The hubcode CLI is a thin wrapper over the same daemon. Same surface:
hubcode run --provider codex/gpt-5.4 --mode full-access --worktree feat/x "<prompt>"
hubcode send <agent-id> "<follow-up>"
hubcode ls
hubcode worktree ls
hubcode schedule create --every 5m "ping main build"
Discover with hubcode --help and hubcode <cmd> --help.
If hubcode isn't on PATH but the desktop app is installed, the bundled CLI is at:
- macOS:
/Applications/Hubcode.app/Contents/Resources/bin/hubcode
- Linux:
<install-dir>/resources/bin/hubcode
- Windows:
C:\Program Files\Hubcode\resources\bin\hubcode.cmd
The desktop app's first-run hook (installCli) symlinks this to ~/.local/bin/hubcode (macOS/Linux) or drops a .cmd trampoline (Windows) and adds ~/.local/bin to PATH via shell rc files. If that didn't take, offer to symlink it — don't do it silently.
Ops and debugging
Daemon-client architecture: the daemon owns agent lifecycle, state, and the WebSocket API. Tools, CLI, mobile, and desktop apps are all clients.
| Default |
|---|
| Listen address | 127.0.0.1:6767 (override HUBCODE_LISTEN) |
| Home | ~/.hubcode (override HUBCODE_HOME) |
| Daemon log | $HUBCODE_HOME/daemon.log |
| Agent state | $HUBCODE_HOME/agents/<id>.json |
| Worktrees | $HUBCODE_HOME/worktrees/ |
| PID file | $HUBCODE_HOME/hubcode.pid |
| Health | GET http://127.0.0.1:6767/api/health |
Debug order:
tail -n 200 ~/.hubcode/daemon.log.hubcode daemon status for liveness.curl -s localhost:6767/api/health if the CLI itself is suspect.
Never restart the daemon without explicit user approval — it kills every running agent, including, often, the one asking.
