Run agents from the terminal

The One Horizon CLI sets up and runs a local agent without Desktop.

Before you begin

You need Node.js 20 or newer, Git, a local repository you can write to, and access to the workspace that owns the work.

Set up and run

1. 1

   Install the CLI

   Install @onehorizon/cli as described in One Horizon CLI.

2. 2

   Authenticate

   Run one auth login and complete the browser OAuth flow. If the browser does not open, open the printed URL yourself.

3. 3

   Select the workspace

   Run one ws use <name-or-id>, or run one ws to choose interactively. Agent registration and queued work use this active workspace.

4. 4

   Create and configure the agent

   From the repository, run one agent create. Choose Codex, Claude Code, Cursor, OpenCode, Mistral Vibe, Hermes, Cline, DeepSeek Harness, or OMP; a compatible preset; agent access; the workflow file; PR/MR behavior; and code isolation. Pass --agent to pick a harness without prompts, for example one agent create --agent hermes. Alongside codex, claude_code, and cursor, the built-in ACP agents are vibe, hermes, cline, deepseek-harness, and omp. Run one agent configure --agent-id <agent-id> only when an existing server-side agent has no local configuration on this machine.

5. 5

   Check the setup

   Run one agent doctor. Resolve any authentication, workspace, repository, workflow file, harness, or worktree error before starting execution.

6. 6

   Start and verify

   Run one agent watch for foreground pickup or one agent start for background pickup. Use one agent status to confirm the agent is online and inspect queued work, local execution capacity, backpressure, and resource pressure.

The coding tools and terminal folders you save for one send are shared with Preferences in the dashboard.

Coding agent requirements

Setup and one agent doctor check that the coding agent you chose is installed and signed in.

Each coding agent handles its own sign-in and sandboxing. If one reports a missing credential, setup stops before the agent is registered. Local agents lists the vendor setup for each one.

OpenCode is installed from the harness catalog. Run one harness list to inspect its setup state, one harness update opencode to review and enable the curated harness, then one agent create --harness opencode to create the agent.

Agent commands

Command	Behavior
one agent run <taskId>	Runs one known work item immediately, waits for the terminal outcome, then exits. It does not upload visual artifacts yet.
one agent watch	Polls for assigned work in the foreground and prints progress. Stop it with Ctrl+C.
one agent start	Starts background pickup for the configured agent.
one agent status	Shows background process state, queued work, completed counts, token totals, local execution capacity, backpressure, and resources.
one agent logs	Prints recent agent logs and follows new output until Ctrl+C.
one agent limit [count]	Shows or sets how many agent runs may execute at once on this computer (12 by default). Every Desktop and CLI agent on the computer shares it; one agent limit default resets it.
one agent stop	Requests a server-side stop, shuts down the local background process, and marks the agent offline.
one agent remove	Removes the configured local agent after confirmation.

With several local agents in the active workspace, pass --agent-id <agent-id> to watch, start, status, or doctor where supported. Foreground watch prints its own status; status primarily tracks agents started in the background.

Worktree cleanup

Task worktrees default to ~/.one/worktrees. To store them elsewhere on this machine, set worktreesDir in ~/.one/config/local.json (for example D:\\OneHorizon\\worktrees on Windows). Existing agents that still use the implicit default pick up the new path automatically; per-agent overrides in worker.json stay authoritative.

Command	Behavior
one agent worktrees	Lists agent-managed worktrees and disk usage.
one agent worktrees remove <task-or-path>	Removes one worktree when it is safe to do so. For a workflow worktree, every computer that holds a copy removes it.
one agent worktrees remove <branch-or-run> --wait	Waits up to 10 minutes until every computer has removed its copy of a workflow worktree.
one agent worktrees remove <branch-or-run> --discard	Lists the changes in each copy you own, then discards them and removes the copies after you confirm. --yes skips the prompt but still prints the list.
one agent worktrees remove --all	Removes all safe worktrees that are not tied to a workflow run.
one agent worktrees remove <task-or-path> --force	Discards local changes while removing a worktree that is not tied to a workflow run.

Workflow worktrees go through the same cleanup as Manage worktree in Desktop and on the web:

• A manual remove keeps a copy with changes until you confirm a discard. Copies on a teammate's computer wait for that teammate to confirm.
• Archiving a failed workflow run discards its changes without asking on the run owner's computers and those of workspace owners and admins. On a teammate's computer, a clean copy is removed and a copy with changes waits for that teammate to confirm.
• When a local agent for the workspace is set up here, this computer removes its copy right away. Otherwise the command warns that no agent could take the copy, and it goes the next time an agent runs here.
• Computers that are offline finish cleanup when their agent reconnects.
• An active workflow run is never removed, and branches are never deleted.

For a copy on this computer, pass its branch or folder. For copies that only exist on other computers, pass the workflow run ID (wfr_...).

Exit code	Meaning
0	Cleanup is complete, or this computer's copy is gone. With --wait, only when every computer is done.
1	A copy was kept, failed, or is still pending. The status table shows which.

Automatic cleanup can leave a worktree in place when the task worktree or repository root has uncommitted changes, or when branch handoff fails. Resolve the Git state first, then run the cleanup command again.

For CLI commands outside agent execution, see the CLI reference.