# Agent workflows (/docs/agents/workflows)



This page shows the common end-to-end flows an agent runs against Bowline. Each
one composes the [agent commands](/docs/cli/commands) under the rules in the
[agent-native contract](/docs/agents/contract). All commands accept `--json`;
mutations accept `--dry-run` and `--idempotency-key`.

## Run a task in the real project [#run-a-task-in-the-real-project]

The default write target for a direct lease is the real project directory. The
agent's edits enter the normal local write log and sync as ordinary workspace
state. No Git publish is required.

1. Discover the contract and read state.

   ```bash
   bowline contract --json
   bowline status ~/Code/acme/web --json
   ```

2. Start a lease for the task and read its context and prompt.

   ```bash
   bowline agent start ~/Code/acme/web --task "fix the auth callback race" --json
   bowline agent context --lease <id> --json
   bowline agent prompt --lease <id>
   ```

3. Explore with bounded, index-backed tools before broad reads.

   ```bash
   bowline search "auth callback" ~/Code/acme/web --json
   bowline symbols AuthCallback ~/Code/acme/web --path-prefix src --json
   ```

4. Do the work in the project directory, then complete the lease. A
   non-conflicting [Agent Overlay](/docs/concepts/agent-leases) becomes a
   Workspace Snapshot and advances the Workspace Head automatically.

   ```bash
   bowline agent complete --lease <id> --json
   ```

## Review before applying with a Work View [#review-before-applying-with-a-work-view]

When the work needs human review before it touches the main project, start the
lease through an isolated [Work View](/docs/concepts/work-views). Work-view
output never applies to the main project until someone accepts it.

```bash
bowline agent start ~/Code/acme/web --task "risky refactor" --work-view --json
# ... agent works in the isolated overlay ...
bowline agent publish --lease <id> --json
```

The published output is reviewable with `bowline review` and `bowline diff`, and
a person applies it with `bowline accept` or drops it with `bowline discard`. See
[work with coding agents](/docs/guides/working-with-agents) for the human side.

## Extend the hydration budget [#extend-the-hydration-budget]

A lease has a bounded hydration budget so an agent can't pull the whole
workspace. If a task legitimately needs more, request additional budget rather
than working around the limit.

```bash
bowline agent budget --lease <id> --add 256MiB --json
```

## Bootstrap a remote host and hand off [#bootstrap-a-remote-host-and-hand-off]

To run on a remote host, complete a [Remote Bootstrap](/docs/getting-started/connect-remote-hosts)
and hand off into a lease in one command. The host becomes a trusted device, and
the lease starts in the named project.

```bash
bowline connect linux-server-1 \
  --project ~/Code/acme/web \
  --task "fix the auth callback race" \
  --agent codex \
  --json
```

<Callout type="warn" title="Trust requires a completed bootstrap">
  Treat the host as trusted only when `bowline connect` finishes with no blocked
  steps and reports `trusted: true`. SSH reachability, host login, or copied
  binaries are never workspace trust on their own.
</Callout>

## Repair a conflict [#repair-a-conflict]

Conflict repair is an agent-assisted action a person starts, not a new
publishing path. The repair works inside a
[Conflict Bundle](/docs/concepts/conflicts) and produces a Resolution Overlay the
user accepts.

```bash
bowline status --json
bowline resolve --diff <conflict> --json
bowline resolve --agent codex
# or, when no agent CLI is available:
bowline resolve --copy-prompt
```

The agent must work only inside the bundle's `resolution` directory, respect
Conflict Spans and per-key env merges, avoid source-control actions, and run the
narrowest relevant checks. A person accepts the Resolution Overlay before it
affects the live project.

## Idempotent retries [#idempotent-retries]

Wrap retryable mutations with an idempotency key so a retried step replays the
stored result instead of acting twice.

```bash
bowline agent complete --lease <id> --idempotency-key complete-<id>-1 --json
```

A replay with the same key and request returns the stored result marked
`replayed: true`; a different request under the same key returns an
`idempotency_conflict` error.

## Next steps [#next-steps]

* [Agent-native contract](/docs/agents/contract): the rules these flows rely
  on.
* [Agent leases](/docs/concepts/agent-leases): lease lifecycle and overlays.
* [Work with coding agents](/docs/guides/working-with-agents): the human side
  of these flows.