> ## 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 Cursor as your AI coding editor

> Open Cursor from an AgentRail worktree and add a Cursor rule so it stays focused on repository work without calling AgentRail lifecycle endpoints.

AgentRail integrates with Cursor by launching it from an AgentRail-managed worktree or by letting `agentrail server start` open it. A Cursor rule keeps the agent focused on repository work and prevents it from calling lifecycle endpoints that belong to AgentRail.

## How it works

Cursor should be launched by AgentRail or opened from an AgentRail-created worktree. AgentRail owns task assignment, CI observation, and lifecycle state. Cursor's job is to edit code in the provided worktree, validate the change, and commit locally.

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

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

    For non-interactive environments:

    ```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:

    ```bash theme={null}
    agentrail agent create
    ```
  </Step>

  <Step title="Start the server">
    ```bash theme={null}
    agentrail server start
    ```

    `agentrail server start` reads agent env files from `~/.agentrail/agents/` and keeps configured agents awake.
  </Step>

  <Step title="Open Cursor from the worktree">
    Open the target repository that AgentRail has prepared. You can open it from the AgentRail-created worktree directly in Cursor, or let the server supervisor open it for you.
  </Step>

  <Step title="Verify with doctor">
    ```bash theme={null}
    agentrail doctor
    ```

    Confirm the API is reachable, credentials are valid, and assigned work is visible before starting any coding work.
  </Step>
</Steps>

## Cursor rules

Add the following rule to your `.cursorrules` file or to Cursor's **Rules for AI** setting. This keeps Cursor focused on the repository and prevents it from calling routes that AgentRail owns.

```text theme={null}
This repository is worked through AgentRail. AgentRail has already assigned the
task and owns lifecycle state. If you need to inspect the current assignment,
use `agentrail run current` or `agentrail run actions`. Do not call broad
AgentRail task, CI, review, ship, rollback, provider, or operator endpoints.
Edit code in the provided worktree, validate the change, commit locally, write
the handoff file, and report with `agentrail agent report`.
```

<Tip>
  Place this rule in `.cursorrules` at the root of the target repository so it applies automatically whenever Cursor opens that repo.
</Tip>

## Run-scoped commands

Inside the AgentRail-managed context, Cursor may use only these run-scoped commands to inspect its current assignment:

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

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

<Warning>
  Do not configure Cursor to call broad AgentRail task, CI, review, ship, rollback, provider, or operator endpoints. Those routes are for external harnesses and are not part of the child agent contract.
</Warning>

## Reporting completion

When Cursor finishes its work, it reports back to AgentRail:

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

## What AgentRail owns

Cursor edits files, validates changes, and commits locally. AgentRail owns everything else:

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