Skip to main content
subagent CX Codex

agent_start — Claude Code subagent: what it does, how to install

This Claude Code subagent starts an agent in a project directory on one of the user's machines. It hands off development work and returns the new session ID.

MIT ★ 395 updated 2026-11-16

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/agent_start.md
Open on GitHub

What agent_start does

agent_start launches an agent in a project folder and gives it an initial prompt. It checks machine resources and availability through machines_list before choosing where to run. If the selected machine failed its most recent launcher health check, the agent starts on a working machine instead; paths under the home directory move to that machine's home.

For parallel work, provide a branch and the machine's engine creates a worktree before the agent starts. A branch already checked out elsewhere is refused. Secret values can be supplied through references to a secret provider after the user approves the hand-off; they reach only the agent's environment. Install the file at .claude/agents/agent_start.md.

What it helps with

  • start an agent in a project directory
  • delegate development work to another machine
  • create a separate worktree for parallel changes
  • pass secret-provider values to an agent's environment

Example prompts for the agent

  • Start an agent in /workspace/app and ask it to fix the error handling.
  • Check available machines, then launch an agent to run tests on branch fix-tests.
  • After approval, pass API_TOKEN from op://vault/item/field to the agent.

How to install agent_start

Manually: put the files in place

.claude/agents/agent_start.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about agent_start

How do I install agent_start in Claude Code?

Add the agent file at .claude/agents/agent_start.md.

What does agent_start do?

It starts an agent in a project directory on one of the user's machines, provides the first prompt, and returns the session ID. It can also place the agent in a separate worktree for parallel work.

How does agent_start create a worktree?

The machine's engine creates it before the agent starts, so it appears in Orca and the app. A branch already checked out elsewhere is refused.

Source text

agent_start.md · MIT
Start a new agent in the terminal engine (herdr or Orca) of one of the user's computers, in a project directory, with a first prompt. Use for real development work instead of doing it here. Check machines_list for current machine resources and availability before choosing a machine. Returns the new session id. When the launcher failed its last health check on that machine, the agent starts on a machine where it works (a directory under the home moves to that home) and the answer says so. Claude-family launchers and Paseo providers with Auto Accept always start in bypassPermissions; traex and omp: no effort.

The launcher decides the agent. A Claude Code launcher starts Claude Code. A launcher named pi, cursor or agy (or one the machine lists as that agent) starts that agent in a herdr pane with the model you give: pi, the Cursor CLI (cursor-agent) or the Antigravity CLI (agy). pi's first message goes through its Persona extension; cursor's and agy's go through herdr once it recognises the agent. Those three take no permission mode and no ultracode, and their effort is their own.

When the work needs a branch and checkout of its own (work in parallel with what is already open in that repository), give `worktree.branch`: Persona makes the worktree through the machine's engine first (herdr's or Orca's own, so it is listed there and in the app, under the workspace `cwd` is in) and starts the agent in it. Do not tell the agent to run `git worktree add` itself: a worktree made that way is invisible to Orca and to the app. An existing local branch is checked out; a new one starts at the HEAD of the workspace `cwd` is in. A branch already checked out elsewhere is refused.

When the agent needs credentials the user keeps in a secret provider (a token in 1Password, say), give `secret_env`: each environment variable it should have, with the reference its value comes from (such as `op://vault/item/field`), never the secret itself. The user approves the hand-off on a card on iPhone or the web before anything starts, and the values reach only that agent's environment, for this run: you never see them, and the answer lists each variable as granted, declined, expired or failed. Only Claude Code agents on a computer this manager connects take them. Tell the agent the variables are there; never ask it to print them.

Give `ultracode: true` for a large task: one that spans many files or needs checking from several angles (design, tests, review). Claude Code then runs every substantial step as a multi-agent workflow: slower and costlier, so leave it off for small or quick work. Do not write the word "ultracode" into the prompt instead. Claude Code agents only (2.1.284 or later): any other agent, an older Claude Code or a node too old for it starts without it, and the answer says so. Whether it is really on shows as `ultracode=on` in agents_list once Claude Code confirms it. An organization policy may keep some conversations read-only: a call from such a conversation is refused with the policy's reason. Do not retry the same call; follow what the refusal says instead.

```json
{
  "type": "object",
  "required": [
    "machine",
    "cwd",
    "prompt"
  ],
  "properties": {
    "machine": {
      "type": "string"
    },
    "cwd": {
      "type": "string",
      "description": "absolute path or ~/…; with worktree, a directory of the repository to branch from"
    },
    "prompt": {
      "type": "string"
    },
    "attachments": {
      "type": "array",
      "maxItems": 8,
      "items": { "type": "string" },
      "description": "pictures and files the user gave you for it, by their absolute paths on your computer: a picture they sent (the path Claude Code gives it), a file the app put in their message. They are copied to the agent's computer and listed at the end of its message, and the text's mentions of them name the copies. Only those the user gave you in this conversation are accepted"
    },
    "launcher": {
      "type": "string",
      "description": "launcher name, one that machine has (a name it lacks is refused, listing the ones it has): a Claude Code launcher, or pi, cursor or agy for those agents; empty: the default, or one the machine has when it lacks the default (claude first; the answer says so)"
    },
    "secret_env": {
      "type": "object",
      "maxProperties": 8,
      "additionalProperties": { "type": "string" },
      "description": "environment variables for this run from the user's secret providers: NAME → reference (op://vault/item/field), never a value; asked on a card first"
    },
    "ultracode": {
      "type": "boolean",
      "description": "turn Claude Code's ultracode on for this agent (multi-agent workflows for every substantial step); default false"
    },
    "worktree": {
      "type": "object",
      "description": "start the agent in a new worktree of cwd's repository, made by the machine's engine",
      "required": [
        "branch"
      ],
      "properties": {
        "branch": {
          "type": "string",
          "description": "the branch to check out (made from the workspace's HEAD when it does not exist)"
        }
      }
    },
    "tier": {
      "type": "string",
      "description": "An Agent preset: one of the tiers the snapshot's 模型档位 line lists for the profile in use, each with what it is for; pick the one whose description fits the work. Resolved before the user is asked, and the card shows it. Explicit launcher/model/effort override its values."
    },
    "effort": {
      "type": "string",
      "description": "Explicit effort override; omit to use the tier or purpose default."
    },
    "model": {
      "type": "string",
      "description": "Explicit model override: a model id the agent takes (an alias such as opus, or a gateway's own id; letters, digits and . _ - / : @ [ ] only, or a leading ~ as in ~vendor/model-latest). Omit to use the tier or purpose default."
    }
  }
}
```

© nwverse · MIT · nwverse/persona

Similar subagents

Subagents catalog →

From the same set61

The whole set →
worker_supervise worker_supervise — a subagent for Claude Code supervises background workers launched with task_plan. It checks submitted evidence against completion criteria and updates worker status via task_review. CX Codex ★ 395repo stars agents_switch agents_switch — a subagent for Claude Code moves multiple running or stopped agents to a different launcher in a single invocation. Executes when requested to manage subscription usage quotas. CX Codex ★ 395repo stars standing_actions Claude Code subagent standing_actions classifies the operations authorized by an agent confirmation card. CX Codex ★ 395repo stars agent_send This Claude Code subagent sends messages to another agent and can assign it supervised work. It can resume a stopped agent with its context when the recorded stop reason allows it. CX Codex ★ 395repo stars engine_handoff engine_handoff — a subagent for Claude Code managing session handoffs and context synchronization between engines. Runs when switching engines during an active development session. CX Codex ★ 395repo stars frontend-motion The frontend-motion subagent for Claude Code handles UI layout, components, transitions, and animations. It runs during scoped frontend tasks with a defined brief. CX Codex ★ 395repo stars task_review task_review — a subagent for Claude Code reviews completed delegated tasks and records a verdict. It can accept the work, return gaps to the same agent, or ask the owner to decide. CX Codex ★ 395repo stars task_plan The task_plan subagent for Claude Code builds and hands users a task plan for running agents on their computers. Runs on any work that takes an agent or more than a few tool calls. CX Codex ★ 395repo stars

Project sponsors

Companies that keep this analytics open