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

# Trails

> Bring intent, code, agent sessions, and review evidence together from the start of a task through merge.

## What Are Trails?

In Entire, a trail brings together what you want to build, how the code changed, and the evidence you need to review it. Trails connect human and agent collaboration across a project.

You can create a trail before writing code. Start with the problem, intended outcome, and constraints, then link a branch when you are ready to build. Each linked branch is represented by a **change**, with its own commits, checkpoints, agent sessions, findings, and merge requirements. A trail can contain changes across multiple repositories in the same project.

[What Are Trails?](https://www.youtube.com/embed/1o9j4w7HFFQ?list=PLPfwtjAgHCu0\&index=7)

## How Do Trails Help?

Trails put the context behind a change alongside the code, whether you are building a feature or reviewing someone else’s work. You can follow the decisions made during agent sessions and see what still needs attention before merging.

For example, a trail for account recovery can begin with acceptance criteria, collect changes to the API and frontend, and bring together agent findings, CI results, and human approvals. Each change is reviewed and merged separately.

## What Can You Do with Trails?

* **Capture intent early.** Create a trail with a title, description, type, assignees, and priority before attaching code.
* **Follow the work.** Link branches as changes and keep their commits, checkpoints, and agent sessions together.
* **Evaluate changes with agents.** Configure [Agents](https://docs.entire.com/guides/trails/agents.md) to review changes and report findings and signals. Automatic runs depend on each agent’s enabled trigger, repository selection, readiness condition, and branch or path filters.
* **Review with context.** Inspect each change’s diff, findings, sessions, and timeline alongside the trail’s intended outcome.
* **Set merge requirements.** Configure [Gates](https://docs.entire.com/guides/trails/gates.md) for requirements such as branch freshness, human approvals, findings, and supported CI checks.
* **Work from your coding agent.** Ask your agent to use the Entire CLI to create or update a trail and investigate its findings. Have it run `entire agent-help` first to discover the available commands.

For example, send this prompt to Codex or another coding agent:

```text theme={null}
Run `entire agent-help`, then inspect the Entire trail linked to
this branch. Summarize its intended outcome and open findings.
Check each finding against the code, propose fixes, and explain
any finding you think should be dismissed. Do not merge anything.
```

> [!NOTE]
>
> Changes in mirrored GitHub repositories use a linked GitHub pull request for
> CI and merging. Entire reviews and GitHub reviews are separate; do not assume
> an approval in one satisfies the other. GitHub branch rules can still block
> merging after Entire’s gates pass.

## Before You Start

Sign in to [entire.com](https://entire.com) and make sure you can access the project and repository.

For a GitHub repository that is not connected yet, open [repository setup](https://entire.com/start), select **Configure GitHub App**, and grant repository access. For an organization-owned repository, you may need a GitHub organization owner or someone authorized to manage the app installation.

To capture local coding-agent sessions and checkpoints, install the [Entire CLI](https://docs.entire.com/installation.md), sign in, and [enable Entire](https://docs.entire.com/quickstart.md) in each local repository where you work. Local CLI setup is not required to create a trail in the UI.

Repository writers can create repository-scoped trails and link branches. Creating a trail without repository scope requires project management permission. Changing the repository’s Trails setting requires repository admin permission.

## Enable Trails

In entire.com, open the repository's **Settings** tab then go to **General**. Trails should be on by default and it should come with some preset Agent configurations that you can use to review your code better.

![Repository General settings showing the Trails workflow enabled](https://mintcdn.com/entire/7Crxbl28PbL5RtNq/images/trails-settings.png?fit=max\&auto=format\&n=7Crxbl28PbL5RtNq\&q=85\&s=c3df78c799dc6942a50e2fdb775df11c)

Trails enabled under Workflows in the repository's General settings.

![Entire agent presets for code review, security review, and detecting sloppy patterns and drift](https://mintcdn.com/entire/7Crxbl28PbL5RtNq/images/trails-agent-presets.png?fit=max\&auto=format\&n=7Crxbl28PbL5RtNq\&q=85\&s=93c0acfa9a7304c2ba1d23c2e9814313)

Preset agents available on the project's Agents page.

`entire enable` sets up local session capture; it does not turn on the repository’s Trails setting in entire.com.

## Create a Trail

**CLI**

From your repository root, confirm the installation, sign in, and enable local session capture if you have not already:

```bash theme={null}
entire version
entire login
entire enable
```

`entire enable` installs Git and agent hooks and creates the repository’s Entire settings. To select an agent without the selection prompt, use a command such as `entire enable --agent claude-code`.

Create a trail with a title:

```bash theme={null}
entire trail create --title "Add account recovery"
```

`--title` is required. From a feature branch, this command publishes that branch and links it to the new trail. From the base branch, it derives a new branch name from the title. It does not commit uncommitted changes or switch your local checkout.

To capture intent without publishing or linking a branch, use:

```bash theme={null}
entire trail create --title "Add account recovery" --no-branch
```

Run `entire trail create --help` for the available options.

**UI**

1. Open the project or repository in entire.com and select **Trails**.
2. Select **New trail**.
3. Enter a title and description, then choose the type, priority, and assignees as needed.
4. When creating from the project’s Trails page, select the repositories to scope the trail to. Creating from a repository scopes it to that repository.
5. Select **Create trail**.

The new trail is open and starts without a linked branch. The creation form does not have a draft or status selector. Add a change when you are ready to attach code.

[Create a Trail in the UI](https://customer-0x5hsk8lh27fm00g.cloudflarestream.com/b6299261cbe5a196ee8f2e7687abaa04/iframe)

**Agent Prompt**

Open your coding agent in the repository and send this prompt:

```text theme={null}
Help me get started with Entire Trails in this repository.

Run `entire agent-help` to discover the CLI commands. Check that
the CLI is installed, I am signed in, and local session capture
is enabled. Explain any missing setup, including the repository’s
Trails setting in entire.com.

Create a trail titled "Add account recovery" without publishing
or linking a branch. Use `entire trail create --no-branch` with
a description covering the problem, intended outcome, and
acceptance criteria. Set its type to feature and priority to medium.

Share the created trail’s link or identifier. Do not change agent
configuration, publish branches, or merge anything without asking.
```

### Plan Before Attaching Code

A trail without changes lets you capture and discuss work before implementation. It is an open trail in the **Planning** phase, not a separate draft status. Trail lifecycle statuses are `open` and `closed`; phases reflect the linked work.

For example:

```bash theme={null}
entire trail create \
  --title "Add account recovery" \
  --no-branch \
  --body "Let users recover access with a single-use, expiring email link. Define expiry and rate-limit requirements before implementation." \
  --type feature \
  --priority medium
```

In a local repository, `--no-branch` still scopes the trail to that repository. It skips branch publication and linking.

### Link a Branch

In the UI, open the trail’s actions menu and select **Add change**. Choose a repository, base branch, and existing head branch, then select **Add change**. The branch must already be available remotely; this dialog does not create a new branch.

From the CLI, link an existing remote branch with:

```bash theme={null}
entire trail link 123 --branch account-recovery
```

Replace `123` with your trail’s number or identifier. Unlike `trail create`, `trail link` does not publish a local branch: push it first. To create a new remote branch instead, check `entire trail link --help` for `--branch-action create` and `--base`.

Repeat this from other repositories in the same project to add their changes to the trail.

## Configure Agents and Gates

Creating a trail or enabling Trails does not automatically configure review agents.

Open the project’s **Agents** page to add an Entire preset or create a custom agent. Select the repositories it reviews, choose or create an environment, and configure when it runs. Agent configuration requires permission to manage project agents and write access to the selected repositories.

An enabled push trigger runs only when its readiness condition and branch or path filters match an open change. By default, a push trigger runs when a change is ready for review. In repositories without an approvals gate, open changes are treated as ready. See [Agents](https://docs.entire.com/guides/trails/agents.md) for setup and trigger options.

To set merge requirements, open each repository’s **Settings → Gates** and [configure Gates](https://docs.entire.com/guides/trails/gates.md).

> [!NOTE]
>
> Project Agents are separate from repository runners configured in
> `.entire/runners/`. `entire runner setup` creates or tailors those runner
> files; it does not configure project Agents. Existing runner-enabled
> repositories may also show monitors such as Confidence, Risk, Security, and
> Drift. Their **Auto build on push** setting does not control project Agents.
> See [Runners](https://docs.entire.com/trails/runners) if your repository uses that system.

## Next Steps

1. Work on a linked branch with your coding agent. With local session capture enabled, Entire records checkpoints and sessions that can be viewed with the change.
2. Commit and push your changes. Configured agents run when their triggers match. Mark the change ready for review when required by your workflow.
3. Confirm that the implementation matches the trail’s intended outcome. Read the agent results and any configured monitors, then select **View changes** to inspect the diff.
4. Investigate findings, fix the issues, and resolve or dismiss findings as appropriate. Use sessions and the timeline for context. You can also ask your coding agent to help through the CLI.
5. Check each change’s merge requirements, address blocking gates and conflicts, and obtain any required approvals. Select **Merge** when that change is eligible. Merging one change does not merge the trail’s other changes.

After another push, findings affected by the updated code may become stale. Staleness is separate from resolution: a stale finding is not automatically marked resolved or dismissed.