Work with coding agents

This guide walks through handing real work to a coding agent. You start a lease, give the agent its prompt and context, let it work in your project, and then review and accept the result. You'll also see how to keep an agent's output isolated for review-before-apply and how to spin up a remote agent host. The agent works in the same ~/Code tree you use, so reviewing its output means opening a folder and running tests, not learning a console.

Before you start

You need an Authorized Device with a synced project. A lease requires a real latest Workspace Snapshot, so confirm the project is synced first:

bowline status ~/Code/acme/web

If the project hasn't synced yet, status reports that as attention, and lease creation will tell you the same. Resolve any conflicts before handing off, since a degraded workspace state stops risky agent actions.

Hand a task to a local agent

Start a lease for the task, then give the agent the context and prompt the lease generates. By default the agent writes to the real project directory, and a non-conflicting result advances the Workspace Head automatically.

1. Start the lease and capture the returned next-step commands:

   bowline agent start ~/Code/acme/web \
     --task "fix auth callback race" \
     --hydrate-budget 500MB --json

2. Fetch the structured context and the rendered prompt for the run:

   bowline agent context --lease <id> --json
   bowline agent prompt --lease <id>

3. Let the agent work. If it needs more hydration budget mid-run, grant it explicitly:

   bowline agent budget --lease <id> --add 250MB

4. Review the result with normal tools, then signal completion:

   cd ~/Code/acme/web
   pnpm test
   bowline agent complete --lease <id>

Keep output isolated for review

When you want to review before anything touches the main project, bind the lease to a Work View with --work-view. The agent's writes stay in an isolated overlay under ~/Code/.work until you accept them.

1. Start a work-view lease:

   bowline agent start ~/Code/acme/web \
     --task "fix auth callback race" \
     --work-view

2. Inspect the isolated output once the agent finishes:

   cd ~/Code/.work/acme/web/<name>
   bowline diff <name>
   pnpm test

3. Apply it into the main view, or drop it if it's not good:

   bowline accept <name>
   # or
   bowline discard <name>

Spin up a remote agent host

To run an agent on another machine, bootstrap the host and hand off the task in one step. bowline connect uses your SSH access as transport and Bowline device trust for decrypt authority, then creates the remote lease for you.

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

This makes the host an Authorized Device with the same real ~/Code, creates the remote lease, and returns safe next actions pointing at the Work View, the agent context, and the redacted prompt for the named agent. Treat the host as trusted only when the command completes without blocked steps. SSH reachability alone is not workspace trust.

Review a review-ready lease

A completed lease whose output needs your review is a Review-Ready Agent Lease. It appears in status and in the work list as soon as it's ready:

bowline status ~/Code/acme/web
bowline work

Open the output, run the checks you care about, and apply or drop it. A review-ready lease is work waiting for a decision, not a workspace failure.

Next steps

• Agent leases: how a lease scopes authority, budget, and writes.
• Work views: the review-before-apply mode used by --work-view.
• Connect remote hosts: more on bowline connect and device trust.
• Agent-native contract: driving Bowline from the agent's side.
• Agent workflows: prompt recipes and primitive tools.