Agent-native contract

Bowline is agent-native without being an agent runtime. Sync makes the workspace a real local directory on every trusted device, so a coding agent works with its own native filesystem, shell, and code tools — and uses the same bowline CLI you do to read state and apply decisions. Bowline does not start, supervise, or gate the agent. This page is the contract an agent depends on: how to discover commands, read structured workspace state, and retry mutations safely.

If you're a person handing work to an agent, start with work with coding agents. This page is for the agent side.

Start here

An agent should begin every session by fetching the compact contract index, hydrating only the command descriptors it needs, and then reading state. This avoids paying the token cost of every command's options and examples up front.

bowline contract --summary --json
bowline contract status --json
bowline status --root ~/Code --json

The summary returns contract metadata plus each command's canonical name, group, one-line summary, side-effect level, and support booleans. Use bowline contract <topic...> --json to load one full descriptor before invoking it. Keep bowline contract --json for tooling that genuinely needs the complete export, including every descriptor and fixture path.

Real directories, not a tool bridge

There is no Bowline-specific edit surface for agents. The project at ~/Code/<project> is ordinary local files, so the agent edits with whatever tools it already has. Non-conflicting edits become synced workspace state and advance the Workspace Head automatically; when two devices diverge on the same file, the divergence surfaces as a conflict-aside file that the agent can reconcile with ordinary edits.

For review-before-apply work, use a work view: bowline work create [project] <name> returns an isolated, cd-able directory under ~/Code/.work/.... Edits there never touch the main project until a person runs bowline work accept; bowline work review and bowline work diff show what changed, and bowline work discard drops it.

JSON output and errors

Every command except the interactive TUI supports --json. In JSON mode, failures use a stable CommandErrorOutput envelope on stdout with a non-zero exit code. Branch on the stable exit code first, then parse the envelope for details; don't parse human text to classify failures.

The envelope includes contractVersion, command, generatedAt, status, and a top-level nextActions. It also carries an error object with code, message, and recoverability, plus optional remediation, details, retryAfterSeconds, and correlationId. Use error.recoverability and retryAfterSeconds to decide whether and when to retry.

Safe mutations and retries

Supported mutations accept --dry-run. Failed commands report whether a retry is safe through their stable exit code and JSON error envelope.

• --dry-run returns a preview and changes nothing; its result includes the exact command to apply the change.
• Exit code 3 marks a retryable runtime error. Confirm error.recoverability, and honor error.retryAfterSeconds when present.
• Exit codes 2, 4, and 5 require corrected input, user action, or safety remediation instead of an automatic retry.

Hard safety invariants

These rules live in validators and storage boundaries, not in agent judgment. They hold no matter what a prompt says.

• Work-view output never applies to the main project without bowline work accept.
• Unclassified or blocked local files never become synced state without policy.
• Project env never travels or rests unencrypted remotely, and secret values never enter prompt text.
• Policy changes require explicit user or organization approval.
• Degraded workspace state surfaces as attention in bowline status; treat it as a stop signal before risky mutations.

Diagnostics

When sync looks wrong, read before acting. bowline status --json reports attention items and safe next actions, bowline events --json lists recent workspace events, and bowline doctor --json runs read-only engine diagnostics with redacted, fixed reason codes. All three are side-effect free.

Next steps

• Agent workflows: end-to-end direct-edit, work-view, and remote-host flows.
• Coding agents: the directory and work-view model agents work in.
• CLI overview: conventions that apply to every command.