for agents

Start in the shop worktree you own. Read the CLI’s guidance and current state:

antil skill print
antil status --json

If there is no session, inspect antil.yaml, install the app’s dependencies, prepare its resources, and start it with antil session start --json. Follow the quickstart for the shop’s exact setup. Do not choose app ports yourself.

read the result before acting

Check the top-level status and process exit code. Inspect blockers, conflicts, and next_actions before issuing another mutation. Run a returned action as an argument array, after checking its preconditions; do not concatenate it into a shell command.

For an app, require data.services.web.state to be ready, then open data.services.web.url in your harness’s browser. Read its direct loopback URL if your client cannot resolve the named localhost address.

For resources, use the provided environment mapping. Do not copy database credentials into chat or logs. For test commands, inspect the command’s exit status and exact log; a running app is not a passing test.

survive retries and handoffs

For commands that accept --idempotency-key (session lifecycle, workspace creation, named commands, and resource changes), give each request one stable key. Check the command help for support. Reuse that key if delivery is uncertain. A different key means new work, including another test run. If a request is still running, follow it. If its outcome is unknown, inspect it before choosing an explicit retry.

Record a handoff to the next agent:

antil status --takeover checkout-agent --json

status --takeover and session touch do not accept an idempotency key. Repeating them refreshes liveness; it does not start another app or test.

A stale mark does not release a worker’s data or ports. End the worker deliberately when it is finished.

the three parts

Use tunnels: apps & urls for ready app addresses, chambers: shared resources for data, and, when available, seals: proof & cache for reusable test proof. Today chambers manage Postgres only and seals are coming. The foundation is shared by all three.

machine-readable docs

Read llms.txt for the page index or llms-full.txt for the whole manual. Every page also has view markdown and copy page. The JSON reference and CLI reference describe the literal contract.