> ## Documentation Index
> Fetch the complete documentation index at: https://agentrail.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Use AgentRail with Claude Code as your coding agent

> Run Claude Code as a managed AgentRail agent or trigger single debug runs. Covers environment variables, run-scoped commands, and handoff reporting.

AgentRail integrates with Claude Code in two modes: a managed local runner where `agentrail server start` wakes Claude Code automatically whenever there is actionable work, and a manual debug mode where you trigger a single run yourself. In both modes, Claude Code edits code in the target repository while AgentRail owns task assignment, CI observation, review tracking, PR creation, and lifecycle state.

## Managed mode

In managed mode you never launch Claude Code directly. `agentrail server start` reads managed agent env files from `~/.agentrail/agents/`, starts an event-driven `agentrail agent run` loop for each configured local agent, and restarts those loops when they exit.

<Steps>
  <Step title="Initialize AgentRail">
    Run the interactive setup to create local config and your first agent profile.

    ```bash theme={null}
    agentrail init
    ```

    If you are running in a non-interactive shell, provide explicit defaults:

    ```bash theme={null}
    agentrail init --mode server --repo /path/to/target-repo --yes
    ```
  </Step>

  <Step title="Create an agent profile">
    If `agentrail init` did not already create an agent, run:

    ```bash theme={null}
    agentrail agent create
    ```

    The wizard creates scoped agent credentials, writes the managed agent env file, and configures starter routing for your repo.
  </Step>

  <Step title="Start the server">
    Keep this running in a dedicated terminal. The server brings up the local API, starts provider delivery, and wakes configured agents automatically.

    ```bash theme={null}
    agentrail server start
    ```

    Expected output includes:

    ```text theme={null}
    Starting AgentRail API.
    ✓ AgentRail API ready at http://127.0.0.1:3000
    ```
  </Step>

  <Step title="Verify with doctor">
    In a second terminal, confirm that the API is reachable, credentials are valid, and assigned work is visible.

    ```bash theme={null}
    agentrail doctor
    ```

    Do not start a coding agent until `doctor` passes.
  </Step>
</Steps>

<Note>
  You do not need to run `agentrail agent run` yourself in managed mode. Reserve it for manual debugging or one-off validation.
</Note>

## Manual debug mode

Use this when you want to trigger a single Claude Code run outside the server supervisor — for example, to test a new agent configuration or reproduce a specific task.

```bash theme={null}
cd /path/to/target-repo
agentrail agent run --agent-id agt_runner --once
```

For manual runs where you need to export connection settings yourself:

```bash theme={null}
cd /path/to/target-repo
export AGENTRAIL_BASE_URL=http://127.0.0.1:3000
export AGENTRAIL_API_KEY=ar_live_replace_with_real_key
```

To pass AgentRail's agent instructions to Claude interactively:

```bash theme={null}
claude --append-system-prompt-file /path/to/agentrail/docs/agent-recipes.md
```

## Environment variables

AgentRail injects the following variables into the managed runner environment. Claude Code can read these at runtime — it should not attempt to discover them through other means.

| Variable                     | Description                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| `AGENTRAIL_RUN_REPORT_PATH`  | Path to the local report file AgentRail reads after the child process exits.         |
| `AGENTRAIL_HANDOFF_PATH`     | Path to the structured handoff file Claude should write before reporting completion. |
| `AGENTRAIL_RUN_CONTEXT_PATH` | Path to the current run context snapshot.                                            |
| `AGENTRAIL_TASK_ID`          | The task ID AgentRail already selected before starting Claude.                       |
| `AGENTRAIL_TASK_IDENTIFIER`  | The human-readable task identifier (for example, `ENG-123`).                         |

## Run-scoped commands

Claude Code running as a managed child process should use only these run-scoped commands. They are scoped to the current run and do not expose task lists or provider credentials.

```bash theme={null}
# Inspect the current assignment
agentrail run current

# Inspect available actions for this run
agentrail run actions
```

<Warning>
  Do not ask Claude to call broad AgentRail task, CI, review, ship, rollback, provider, or operator endpoints from inside the child process. Those routes are for external harnesses, not managed child agents.
</Warning>

## Reporting completion

When Claude finishes its work, it must write the handoff file and report back to AgentRail before exiting.

```bash theme={null}
agentrail agent report \
  --status completed \
  --summary "short completion summary" \
  --handoff-file "$AGENTRAIL_HANDOFF_PATH"
```

To report a progress update without finishing:

```bash theme={null}
agentrail agent report --status progress --summary "short update"
```

Use `--status completed` with a handoff file when work is done. Use `--status progress` for intermediate updates during long-running tasks.

<Tip>
  Run the smallest relevant validation (unit tests, type checks, lint) before reporting completion. AgentRail uses the handoff file contents when deciding the next lifecycle action.
</Tip>

## What AgentRail owns

Claude Code edits files and reports back. Everything else belongs to AgentRail:

* Task assignment and lifecycle state
* CI and review observation
* Provider PR creation, shipping, and rollback
* Relaunching Claude only when CI or review feedback requires further code changes