Local Agents

Local agents run a supported coding tool on your machine. Send them work from One Horizon, and the run stays tied to the original initiative, bug, or todo.

This is the middle path between Send to app and a team-shared agent. The agent runs only for the person who started it, on that person's machine. The work item should already be a usable spec.

Before you start

Workspace access

Sign in to the workspace that owns the initiative, bug, or todo you want the local agent to run.

Local agent setup uses OAuth. API Keys can read and write workspace data through the REST API, but they cannot create or run local agents.

Before a local agent can run, these things need to be true:

• You are signed in to the workspace where the work lives.
• Git is installed and available to the app or terminal that starts the agent.
• The coding tool CLI you selected is installed, available on PATH, and signed in when that tool requires it.
• The working directory exists, is writable, and is inside the git repository you want the agent to use.
• The repository has a usable base branch, such as main, master, or the base branch set in the workflow file.
• For pull requests, merge requests, or handoff to another local agent, the repository needs an origin remote that this machine can push to. For code changes, the agent needs to commit locally; One Horizon creates PRs and MRs through the connected GitHub or GitLab integration after the branch is pushed.

Agent CLI

Install the agent you plan to run and make sure its CLI is on your PATH:

• Codex — the codex binary. Codex covers Send to app, local agent runs, and opening recorded Codex threads.
• Claude Code — the claude binary, with an authenticated Claude Code CLI session. Claude Code separates MCP setup from local agent setup.
• Cursor — the agent binary (some installs expose cursor-agent). This is a separate install from the Cursor IDE MCP integration; installing or configuring MCP in the editor does not satisfy local agent prerequisites.

Cursor local agents need the Cursor CLI installed and authenticated. The Cursor IDE and MCP connector do not satisfy either requirement on their own.

If agent --version or cursor-agent --version already works in the terminal where you run one agent, no extra Cursor download is needed for CLI runs. Desktop setup checks for the same binary before it can start a Cursor agent. Otherwise install the Cursor CLI:

curl https://cursor.com/install -fsS | bash

Cursor documents this on the Cursor CLI installation page. Make sure ~/.local/bin is on your PATH if the installer puts agent there.

Verify and authenticate the CLI before setup:

agent --versionagent status

Authenticate with agent login, or set CURSOR_API_KEY from Cursor Settings → Integrations → User API Keys. If a browser cannot open from the terminal, run NO_OPEN_BROWSER=1 agent login and open the printed URL yourself. One Horizon does not store Cursor credentials.

If setup or a run fails with Cursor CLI is not authenticated on this machine, the CLI is installed but not signed in. Run agent login or set CURSOR_API_KEY, then retry. See Cursor for install and sign-in steps.

Repository folder

Choose the git repository you want the agent to work in. In the default worktree mode, One Horizon creates isolated task worktrees under ~/.one/worktrees and uses your repository as the source. In shared repository mode, runs use the selected folder directly.

Desktop or CLI

Desktop is the shortest setup path. The installed and signed-in CLI gives you terminal control.

Local agents are private to the person who starts them. Only you can send work to agents running on your machine. Other workspace members cannot trigger execution on your machine just because they can assign you work.

Desktop setup

Desktop handles the guided setup path from the agents page under Workflows. You can also start the same setup flow from a workflow step when that step needs an agent, or use Get started on the workflows overview to create Planner, Builder, and Reviewer agents plus starter definitions in one pass.

The agents page is the main place to add and manage local agents after setup.

1. Open the Desktop app and sign in.
2. Open the workspace where the work lives.
3. Go to Workflows, open the agents page, and select Add agent.
4. In Set up new agent, walk through the setup steps:
   • Agent — choose Codex, Claude Code, or Cursor. Claude Code requires a local claude binary on your PATH and an authenticated Claude Code CLI session. Cursor requires an authenticated Cursor CLI (agent or cursor-agent) on your PATH; the Cursor app alone is not enough unless it installed that CLI.
   • Runtime preset — choose Builder, Planner, or Reviewer (see Runtime presets below).
   • Agent access — choose Read-only, Workspace access, or Full access. Full access is a host-level trust choice.
   • Basics — set the Agent name and Working directory (repository folder).
   • Workspace — set the Workflow file path. When the access level allows workspace changes, also choose Code isolation and whether One Horizon should create a PR/MR when work completes.
   • Instructions — choose Model and, when shown, Reasoning effort (Codex), then add optional agent-level guidance.
5. Select Set up agent. Desktop registers the agent, writes local runtime settings, tries to start it, and opens the agent details page.
6. If setup could not start the agent, or you stopped it later, start it again from the agent details page when you want automatic pickup.

Desktop uses your signed-in session, writes local agent config, registers or reuses your private local agent, and starts the local process when setup succeeds. Stop asks the server to stop the agent and shuts down the local process when this Desktop app owns it.

The setup dialog starts by choosing which local runtime this agent should use.

The workflow designer has an inline entry point for the same modal. Open a workflow, select an agent step, open the Agent selector, and choose Create agent. Desktop creates the agent without leaving the designer and selects it for that step after setup succeeds. This path fits agents created for a specific Workflow.

The Workflow file in local agent setup is local runtime policy, such as hooks, worktree behavior, and command settings. The workflow definition you design in the workflow designer is the product-level process that routes work between steps.

Runtime presets

During setup, Builder, Planner, and Reviewer set the initial agent access level and PR/MR creation choice:

Builder fits implementation work that edits files in the task workspace. Planner fits investigation and planning. Reviewer fits critique and review passes that can still run local tools and browser automation, but does not request PR/MR creation by default.

The Workspace step shows Code isolation and the PR/MR toggle when agent access is Workspace access or Full access. Read-only agents still collect the workflow file path.

The preset stores agent access on the agent. You can change settings like model, reasoning effort, and agent access later from Settings on the agent details page.

macOS repository folders

On macOS, choosing a repository inside Documents, Downloads, or on the Desktop can trigger a system file-access prompt when Desktop opens the native folder picker. The grant applies to the folder you explicitly select, not your entire home directory or disk.

The agent process Desktop starts runs as a child of the Desktop app and inherits the same access the app received for that folder, so the app must obtain the grant before the agent starts.

Local agent data under ~/.one/ lives in your home folder and does not rely on that protected-folder grant for the repository path.

Running one agent from Terminal uses your shell environment instead of Desktop's macOS grant for the same folder-selection flow.

After the agent is online, open an initiative, bug, or todo and use Send to to start a local agent run. Selecting a specific agent in the launcher sends the run to that agent only.

Settings

In the dashboard, open Agents and select your local agent to reach the agent details page. The Settings card appears on that page in the browser and in Desktop.

The Auto start toggle saves as soon as you change it. Auto start is on by default; turn it off if you do not want this agent to start when Desktop opens on a machine where the agent is already configured.

Desktop, dashboard setup, and CLI one agent create let you choose Model, reasoning effort, and agent access when you create the agent. Setup also stores the initial code isolation, workflow file, and related defaults. Return to Settings later when you need to change them without recreating the agent.

Max visible runs is not the same as how many agent processes run at once. A laptop-wide active execution cap and resource limits in WORKFLOW.md decide when a run can start local processes. The dashboard field description calls this out; adjust agent.max_active_executions and agent.resource_limits in the workflow file when you need different laptop-wide limits.

The Working directory (repository folder) you choose during setup is not in this table. It cannot be changed after the agent is created, not from Settings, not with one agent configure, and not from Desktop. one agent configure only binds local runtime settings to a server-side agent that has none on this machine yet; it refuses to run against an agent already configured here. The chosen folder is written once to local config on the machine that created the agent and is never synced to the server (see Build a Local Agent for where). Create a new agent to point at a different repository folder.

Task worktrees always live under ~/.one/worktrees and are not configurable. From the terminal, change code isolation, workflow file, and concurrency with one agent configure when this machine has no local settings for that server-side agent yet, or by editing the local config under ~/.one/config/. Change model, reasoning effort, and agent access from Settings in the dashboard or Desktop. See CLI setup below.

Change any setting in the table, then select Save settings. Visible concurrency changes apply after the agent process starts again.

In Desktop, when you own the agent and the local process is running on your machine, restart it from Agent actions → Restart agent, or select Restart agent in the message that appears after you save. On the Agents page, open the more menu and choose Restart all agents to restart every local agent configured on this machine.

After Desktop or CLI updates

After you install a Desktop update and relaunch the app, configured local agents on this machine restart automatically so they run the new app bundle. You may see a short summary toast. Auto start waits until that restart finishes.

After you update the global CLI (npm install -g @onehorizon/cli or the equivalent for your package manager), the next one command restarts agents started with one agent start. Foreground one agent watch does not auto-restart; stop it with Ctrl+C and run one agent watch again after updating.

In the web dashboard, saving stores runtime values on the server. Apply them by restarting the agent on the machine that runs it: use Start and Stop in Desktop on that machine, run one agent stop and one agent start in the CLI, or wait until the agent starts again if it is already offline.

Only you can open or update a local agent you own. Other workspace members cannot load or change another person's local agent or its runtime settings.

CLI setup

The CLI gives you terminal control, foreground logs, background process management, and scriptable agent setup. Install, sign in, and choose a workspace from CLI first.

one agent createone agent doctor

one agent create prompts for agent, runtime preset, agent access, and workflow setup. Model and reasoning effort use preset defaults until you change them in Settings:

1. Agent — Codex requires the codex binary on your PATH. Claude Code requires the claude binary on your PATH and an authenticated Claude Code CLI session. Cursor requires an authenticated Cursor CLI as agent or cursor-agent.
2. Runtime preset — Builder, Planner, or Reviewer (see Runtime presets above). The preset sets the initial model, reasoning effort, agent access, and PR/MR creation defaults.
3. Agent access — Read-only, Workspace access, or Full access. Use --permission-level readOnly|workspaceTools|fullAccess for scripted creation.
4. Starter workflow — create a starter file in the current folder, choose a custom folder, or skip.
5. Workflow file — press Enter to accept WORKFLOW.md, or type another filename. If the file already exists, choose whether to overwrite it.
6. Repository root — confirm the git repository root (defaults to the folder you chose).
7. Pull request or merge request — whether One Horizon should create a PR/MR when a task completes. The default follows the runtime preset (Builder on, Planner and Reviewer off).
8. Code isolation — New worktree per task or New branch per task.

To change model, reasoning effort, or agent access after creation, open Settings on the agent details page in the dashboard or Desktop.

The command creates a local agent for the active workspace and signed-in user, saves local runtime settings under ~/.one/config/, and writes a starter WORKFLOW.md when you create one.

one agent doctor checks authentication, workspace selection, server-side agent registration, local runtime settings, the workflow file, the worktree root, and the agent binary.

What creation configures

The local agent runtime reads the workflow file and local config for:

Cursor runtime

Cursor agents run through the Cursor CLI with agent -p --output-format stream-json --stream-partial-output. The agent writes the prompt to stdin, records the Cursor session ID from stream JSON, and passes --resume when a later run continues the same Cursor session.

Agent access maps to Cursor CLI flags:

When Model is set, the agent passes it with --model. Cursor does not use Reasoning effort.

For document-backed runs, the agent adds a temporary one_documents MCP server to the task worktree's .cursor/mcp.json before starting Cursor. The config stores Authorization: Bearer ${env:ONE_WORKER_DOCUMENT_TOKEN} and the token is passed through the child process environment, so the raw token is not written into the workspace file. After the run, the agent removes only its one_documents entry or restores the previous entry if one existed.

Cursor CLI also reads Cursor's normal project and global MCP configuration. Because the agent starts Cursor with --approve-mcps, review unrelated Cursor MCP servers before using Cursor local agents on sensitive repositories.

Run modes

Run one known work item:

one agent run tsk_123

run starts that work item immediately, prepares the worktree, runs workflow hooks, starts the configured coding tool, emits activity, and finishes or fails the run.

Watch for assigned work in the foreground:

one agent watch

watch keeps the agent online, checks for assigned work, and starts runs when a laptop-wide execution slot is free. Progress prints in the current terminal. Stop it with Ctrl+C.

Run in the background:

one agent startone agent statusone agent logsone agent stop

status and logs only track background agents started with one agent start. Foreground watch runs report progress in their own terminal. one agent status also shows Local execution, Backpressure, and Resources for laptop-wide concurrency and resource pressure on that machine.

If the active workspace has multiple local agents, watch, start, and status can target one with --agent-id <agent-id>. Agents without local runtime settings on this machine are shown as not configured until you run one agent configure for them.

What happens during a run

The local agent loop is:

1. Tell the platform it is online.
2. Check for work assigned to this agent.
3. Reserve work up to the visible run limit.
4. Acquire a laptop-wide local execution slot when resource pressure and the active cap allow it.
5. Set up the task worktree or shared repository folder according to WORKFLOW.md.
6. Start the configured coding tool through the local runtime.
7. Emit progress, plan, external URL, completion, failure, or policy activities.
8. Finish, fail, or release the work so it can be retried later.

The default runtime checks for work every 30 seconds, allows up to six visible runs per agent, and starts up to three active local executions across the laptop. Setup can use isolated task worktrees or a shared repository mode. Commits created by the agent are attributed to the agent name in git user.name.

Worktrees and workflow files

In task mode, each run gets its own subdirectory under the worktree root. This supports isolated git worktrees per task.

In repository mode, runs share the configured repository folder.

The workflow file can define worktree settings, hooks, retry limits, polling interval, visible and active concurrency, resource limits, runtime command, and timeouts. Hook scripts include before_run, after_run, after_create, after_complete, and before_remove. Common agent fields include max_concurrent_agents, max_active_executions, and resource_limits entries such as max_load_average_per_cpu, min_free_memory_bytes, max_process_count, and pause_on_mac_thermal_pressure. Set a limit to null in YAML to disable that check. The platform still owns run policy and work state transitions.

Starter WORKFLOW.md files tell the coding agent to commit locally and stop. They do not ask the agent to push the branch or run gh pr create or glab mr create.

After a successful run

When a run completes successfully and the agent reports the outcome to One Horizon, the runtime runs post-command cleanup.

The hooks.after_complete script runs after review artifacts are published. Hook failures are logged as warnings and do not retry the run.

In Worktree per task mode, the agent then tries to move the task branch back to your repository root and remove the task worktree. Handoff runs only when the run used a linked git worktree, the task worktree has no uncommitted changes, and the repository root has no uncommitted changes. The agent detaches the task worktree at its current commit, checks out the task branch in the repository root, and removes the worktree. If handoff or removal fails, the worktree stays in place and the agent logs a warning.

Branch per task mode does not run this built-in handoff.

Review handoff and pull requests

When PR/MR creation is enabled, the agent still only needs to commit locally. It does not need GitHub or GitLab PR credentials. After a successful run with committed changes, the runtime pushes the branch and One Horizon creates a GitHub pull request or GitLab merge request through the connected integration. The linked initiative, bug, or todo moves to In Review, and the PR/MR URL appears on the run and work item.

If the branch push succeeds but PR/MR creation fails, the runtime posts a task comment with recovery steps. Connect GitHub or GitLab in workspace integrations, then open the review manually from the pushed branch or retry creation.

Visual verification artifacts

Starter WORKFLOW.md files include a Visual artifacts section. It tells the coding agent to save screenshots or screen recordings to $ONE_WORKER_ARTIFACTS_DIR when that environment variable is set, and not to commit or push those files.

For Codex and Claude Code runs with writable agent access, the runtime sets ONE_WORKER_ARTIFACTS_DIR and grants the agent access to that directory. Read-only modes do not set the variable. Cursor local agents do not currently receive a visual-artifacts directory.

After a successful Desktop run, one agent watch, or one agent start, the built-in orchestrator uploads accepted files from that directory to the workspace and adds one comment on the initiative, bug, or todo with links. Labels follow the file type, such as Artifact 1 for images and Video 1 for recordings. Failed runs do not upload artifacts or post that comment.

one agent run does not upload artifacts yet.

Safety boundary

Your local agent can run code on your machine and use local tools or secrets that you explicitly make available. Keep trusted workflow policy separate from untrusted work text, comments, documents, and prompts.

Trusted inputs include platform policy, the agent profile, local agent config, and your local workflow file. Untrusted inputs include work titles, descriptions, comments, documents, and user prompts.

Claude Code and Cursor own their CLI sandbox and network behavior. One Horizon maps Agent access to provider flags, but it cannot force network-off execution for those runs.

Review code, tests, and pull requests before merging model-produced work.

Troubleshooting

Common local agent issues are usually missing local configuration or workspace selection problems.

If watch or start says no agent has been created, run:

one agent createone agent doctor

If the server-side agent exists but this machine is not configured for it, run one agent configure in the active workspace to bind local runtime settings to the existing agent without creating a new one.

If no work starts, check that a run exists for your local agent and that the agent is online. Use the agent details page in Desktop, Agent queue in the main menu or title bar, one agent status, or the terminal running one agent watch.

If runs exist but local execution waits, run one agent status and read Local execution, Backpressure, and Resources. Foreground one agent watch and one agent run print similar delay reasons while they retry. Typical causes are the laptop-wide active execution cap, high load, low free memory, high process count, or macOS thermal pressure. Work waits until a local slot opens.

On macOS, a sustained kernel_task CPU spike during agent runs is often a thermal-management symptom rather than a separate bug in the agent. Compare Activity Monitor with agent logs and one agent status before you change limits. Apple documents kernel_task CPU use as part of temperature management. Local agents can contribute indirectly through CPU-heavy turns, many child processes, git operations, package installs, tests, or disk-heavy builds.

If one agent doctor reports stale local runtime configs, those configs no longer match a server-side agent. Normal agent lists ignore stale configs.

Remove worktrees that automatic cleanup skipped, or reclaim disk when completed runs pile up:

one agent worktreesone agent worktrees remove tsk_123one agent worktrees remove --all

Agent Sessions explains the run lifecycle. Build a Local Agent covers a custom polling-based runtime.

Frequently asked questions