> ## Documentation Index > Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt > Use this file to discover all available pages before exploring further. # Sail for coding agents > Delegate coding work to Sail models from Claude Code or local Codex sessions without changing your coding workflow. The **Sail** plugin lets your coding agent send work to a Sail model without making you switch tools. Use it to lower the cost of token-heavy coding work, try curated open models, or add a second model's perspective to your normal workflow. GLM-5.2 is the current worker model. One plugin installs nine skills and one `sail-delegate` MCP server. The server provides six tools: * `sail_delegate` runs one implementation, analysis, or review task. * `sail_fanout` runs several independent tasks concurrently from one baseline. * `sail_await` waits for a background delegation or selected task. * `sail_collect` returns compact status or one selected task's result. * `sail_resume` continues an incomplete task from its saved checkpoint. * `sail_cancel` requests cancellation of an active delegation. Every worker receives an isolated copy of the current project, including uncommitted changes. A writable worker edits and tests only that copy, then returns a unified diff. Your coding agent inspects the diff, applies it to your live checkout, and reruns the relevant checks locally. The plugin exposes three ways to use those tools: | Skill | Ownership model | | --------------- | -------------------------------------------------------------------------------------- | | **Sail Subs** | Your coding agent owns the task and delegates suitable scoped subtasks to Sail. | | **Sail Swarm** | Your coding agent owns the task and runs an announced campaign of coordinated workers. | | **Sail Review** | Sail performs an on-demand, read-only review and returns findings. | The `Sail Update` skill handles plugin upgrades. It does not call a Sail worker. ## Prerequisites Install [`uv`](https://docs.astral.sh/uv/) once. The plugin uses `uvx` to start the local MCP server: ```bash theme={null} curl -LsSf https://astral.sh/uv/install.sh | sh ``` On Windows: ```powershell theme={null} powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` Authenticate before your first delegation: ```bash theme={null} sail auth login ``` If you need the Sail CLI first: ```bash theme={null} curl -fsSL https://cli.sailresearch.com/install.sh | sh ``` Signing in is the only credential setup you need. Installing the plugin does not require it first: the MCP server checks for a stored login on every call, so you can sign in after installation without restarting it. You can instead export `SAIL_API_KEY` before starting your coding agent. A stored login works more reliably for desktop apps because they may not inherit shell variables. ## Install From a Claude Code session: ```text theme={null} /plugin marketplace add sailresearchco/sail-skills /plugin install sail@sail ``` Or from a terminal: ```bash theme={null} claude plugin marketplace add sailresearchco/sail-skills claude plugin install sail@sail ``` Run `/mcp` and confirm that `sail-delegate` exposes all six tools. The same plugin works in the Claude Code terminal, desktop app, and IDE extension. Claude Code supplies the selected project root directly to the plugin's MCP server, so desktop sessions do not depend on its process working directory. Add the Sail marketplace and plugin: ```bash theme={null} codex plugin marketplace add sailresearchco/sail-skills codex plugin add sail@sail ``` Restart an open Codex session after installation. The Codex package sets a 120-second startup timeout and a 3600-second tool timeout for Sail. Delegation, review, fanout, waiting, collection, and resume calls run without an extra approval prompt. Cancellation still requires approval because it stops active work. The local Codex app, CLI, and IDE extension can run the bundled stdio MCP server. Hosted Codex sessions cannot run it in this release. For each call from the Codex app or IDE extension, the Sail skills pass the active workspace as `project_path`. This keeps delegation tied to the selected project even when Codex starts the MCP server from another directory. ## Use the plugin Pick by how much you hand over. Sail Subs gives you extra hands: you stay in the driver's seat while Sail takes the heavy pieces. Sail Swarm makes one change in many places when the pieces still need discovering: the agent shows you the campaign plan first, then runs a paid scouting round and coordinates workers to land the change consistently. Sail Review checks a diff and returns findings, worst first, changing nothing. If you remember one line, make it this: several jobs is Subs; one sweeping job that needs scouting first is Swarm. Ask naturally, or invoke a skill directly: ```text theme={null} /sail:sail-subs /sail:sail-swarm /sail:sail-review /sail:sail-update ``` Examples: ```text theme={null} Use Sail for suitable implementation subtasks while you own the overall task. ``` ```text theme={null} Use Sail Swarm. Run this cross-cutting migration as a coordinated campaign, recon first, then partitioned implementation. ``` ```text theme={null} Use Sail Review on my current diff, focusing on authorization bugs. ``` ```text theme={null} Update my Sail plugin. ``` Ask naturally, or name a skill with `$`: ```text theme={null} $sail-subs delegate suitable scoped work while you own integration. ``` ```text theme={null} $sail-swarm run this migration as a coordinated campaign with recon first. ``` ```text theme={null} $sail-review review my current diff for correctness and missing tests. ``` ```text theme={null} $sail-update update my installed Sail plugin. ``` ## Sail Subs Sail Subs is the automatic delegation mode. The host can select it whenever the task contains suitable scoped work; you do not need to invoke the skill or mention Sail, GLM, or open models. Direct invocation and standing preferences remain available when you want to encourage more delegation. For suitable self-contained work, the host can treat a Sail worker as a peer execution path to a coding subagent. This lets the host route token-heavy leaf work to Sail while keeping its own token budget for planning, coordination, integration, and final judgment. The host coding agent keeps the plan, conversation context, decisions, integration, review, and final verification. It sends Sail well-scoped work such as: * An implementation or refactor within known files. * A broad read-only audit or usage inventory. * Test and documentation generation with clear acceptance criteria. * Independent leaf tasks that can run concurrently. Give each worker the goal, acceptance criteria, relevant paths, conventions it cannot infer, and decisive checks. Keep requests concise. Do not repeat the runtime's safety, isolation, or environment boilerplate, and do not list the same checks again in prose. Once that minimum grounding is complete, delegate the specified execution before the host exhaustively explores it. Bound that grounding pass to the context needed to specify the leaves. Do not run worker-leaf experiments, exploratory tests, or repeat repository reads that belong to the worker before dispatch. While workers run, the host does only necessary non-overlapping coordination or integration preparation, and waits for their edits before running checks that depend on those edits. Choose the topology from the dependency graph: * First enumerate the substantial, Sail-eligible leaf tasks that are ready from the current baseline. A ready leaf is independently implementable and checkable without a sibling's unintegrated edits, with non-overlapping output ownership. * If at least two ready leaves exist, put all currently ready leaves in one `sail_fanout`. A shared product goal, final acceptance suite, or later host integration does not make independent leaves cohesive. * Do not manufacture leaves by splitting tightly coupled implementation, tests, and documentation. Use one worker, or keep tiny work local, only when splitting would divide an evolving interface or invariant, overlap edits, produce tasks too small to delegate, or leave fewer than two eligible leaves. * Use multiple waves when later work depends on an interface or edit from an earlier worker. Integrate the upstream result before starting the next wave. Fewer workers is not a goal in itself. Genuinely independent work keeps its parallelism; tightly coupled work stays together. After topology is chosen, a single cohesive leaf with more than roughly six distinct edit sites or more than two test files may warrant an explicit 64-turn ceiling. This estimate never justifies splitting an overlapping interface or invariant. When the host has no independent work, it calls with `wait=true`; the tool waits while emitting bounded progress. When the host has real, non-overlapping work, it starts with `wait=false`, keeps the `delegation_id`, does that work, then calls `sail_await` once. `sail_collect` is for deliberate inspection and recovery, not timed polling. While a worker is active, the host does not duplicate its implementation. If a worker definitively fails, stalls, or returns an unusable or empty diff, the host can transparently repair that scoped work locally or re-delegate it. If an incomplete checkpoint remains useful, the host resumes it instead. The Sail Subs skill explicitly requests compact results. It calls a single delegation with `include_diff=false`, and indexed collection with `include_request=false`. The full patch remains at `diff_path`. Background work continues if the MCP connection closes. Clean writable success is a fast path. When a completed result has a patch, changed paths within its declared ownership, and fresh passing required checks, the host does not dump the full diff, re-read every worker-owned file, or add duplicate ad hoc tests. For a wave, it batch-checks all patches with `git apply --check`, then applies the whole wave while preserving unrelated user work. After all waves, it runs the exact final acceptance suite once. Deeper patch inspection is reserved for suspicious scope or evidence, apply failures, risky changes, user-work overlap, or failed final acceptance. ## Sail Swarm Sail Swarm runs one large objective as a coordinated campaign of workers while your coding agent keeps ownership. It fits work that must stay consistent across many files, such as a migration of many call sites or one convention rolled out across modules, when the subtasks cannot be specified without first reading the project broadly. The host announces the campaign plan before starting. A read-only recon fanout reads each area and returns briefs. The host synthesizes them into a field guide, one shared context artifact with the target conventions, exact interface signatures, and a file-ownership map. Implementation tasks are partitioned so no two writable workers touch the same file, every task receives the field guide, and dependent work runs as ordered waves. The host checks each returned diff against its task's assigned files, applies diffs wave by wave, runs checks after each wave, and verifies the merged result against the field guide. Use Sail Subs for subtasks the host can already specify. A swarm's recon round is paid work, so it pays off at roughly six or more coordinated implementation tasks over a shared surface. ## Sail Review Sail Review is an on-demand, read-only second opinion. Asking for a review in plain language is enough; you do not need to name the skill. It never runs as an automatic end-of-task check. When you do not specify a scope, the host sends the current working diff. You can instead name a base revision, paths, or a focus such as security, correctness, performance, or tests. The review runs through `sail_delegate` with `write=false`. It does not edit files or run repository code. The host validates the response against the live checkout and returns actionable findings in severity order with file and line references. If Sail finds no actionable defects, the host says so directly. No automatic review hook or mandatory review loop is installed. If a review reaches its attempt ceiling, the host can continue its saved read-only checkpoint with `sail_resume`. It does not restart the review or change its permissions. ## Sail Update Ask `Sail Update` to update the plugin without copying commands from this guide. It detects the current coding host, refreshes the Sail marketplace, updates the installed plugin, and verifies the installed version. Use `/sail:sail-update` in Claude Code or `$sail-update` in Codex. The running session keeps its current plugin snapshot. Reload plugins or start a new session after the update finishes. Users upgrading from a release older than `0.3.0` must use the manual update flow once because that release does not contain `Sail Update` yet. For that one-time upgrade, run the matching commands: ```bash theme={null} claude plugin marketplace update sail claude plugin update sail@sail ``` ```bash theme={null} codex plugin marketplace upgrade sail ``` ## Worker model Sail delegation uses GLM-5.2 as its only curated worker choice in this release. The MCP tools retain an optional `model` argument for future additions, but the plugin does not present a model picker yet. ## Web search in workers Workers can look things up on the web. Every worker has a `web_search` tool, enabled by default, so an analysis worker can check current documentation and an implementation worker can resolve a question mid-task. Search results never reach a worker as raw web pages. A separate reader model reads the results first and writes a short summary. That reader has no tools, no access to your files, and no ability to take actions. The worker receives the summary, not the page text. The reader is asked to name the site behind each claim, so attribution usually survives, but it comes from the summary rather than from a separate list the worker can rely on. This matters because web pages are written by strangers. A page can contain text written to give instructions to whatever reads it. Sending it to a reader that cannot act, and passing on only what that reader wrote, removes most of the risk and keeps the worker's context small. Smaller context also makes searching cheaper than handing over full pages. Treat the result as untrusted all the same. The reader cannot act on an instruction it finds, but it can still repeat one, so a summary is safer than a raw page rather than proof that a page was safe. Workers are told to read it as evidence, not as direction. If you would rather a worker not read the web at all, turn search off for that call. To turn search off for a call, pass `search=false` on `sail_delegate` or `sail_fanout`. Each search a worker performs is billed to your organization per request. Task results report a `searches` count, and the aggregate appears next to token usage. ## Results, checkpoints, and cancellation Every single delegation and fanout receives a durable `delegation_id`. `sail_await` waits read-only for the whole delegation or one `task_index`; it never resumes, cancels, or repeats paid work. By default, `sail_collect` returns compact task entries with status, turns, token usage, recent tool activity, stall state, a summary preview, diff size, stop reason, and resume availability. Pass `task_index` to retrieve one task's result and diff metadata. Set `include_request=false` when the host already knows the request and context. Every non-empty saved patch has an absolute `diff_path`, byte count, and SHA-256. Add `include_diff=true` to inline a selected patch when it is at most 32 KiB; larger patches stay at `diff_path`. The compatibility defaults remain unchanged for callers outside the revised Sail Subs skill. For writable work, Sail preserves the summary and usage when patch capture fails. An `omitted_files` list means the saved partial patch excludes oversized new files; the task remains incomplete and cannot resume because their content is not retained. A `diff_error` means the complete patch could not be captured. Compact and indexed results expose these fields so the host can keep the paid analysis and repair only the missing implementation. Compact results bound long omission lists and report their total; indexed results retain the complete list. Usage reports `input`, `cached_input`, `output`, and `total` tokens. The top-level `tokens` object aggregates the latest cumulative usage for every task in the delegation. `total` is input plus output; cached input is already part of input. Sail keeps one prompt cache identifier across the original attempt and every resume. Workers aim to finish within a 24-turn primary budget. The default `max_turns=48` applies when the parameter is omitted and is a hard ceiling. Every explicit value is also a hard ceiling. Complex cohesive work can explicitly use up to 64 turns. A 48-turn attempt receives a finish checkpoint at turn 40; a 64-turn attempt receives one at turn 53. Four turns before each boundary, the worker receives a reminder to finish the highest-value work and verification. Sail never resumes an attempt automatically. An attempt that reaches its ceiling does not end silently. Sail withdraws the worker's tools and requires one closing reply, so the incomplete result still carries the worker's own final report: what finished, what remains, and what it last verified. If that closing reply fails, the result keeps a generic summary instead. A worker counts as stalled after four consecutive responses without a successful new tool call or final answer. Repeating an identical tool call and output-recovery responses do not reset that count. Multiple independent tool calls requested in one response consume one model turn, though the tools run sequentially. Combined tool output from one response is capped at 100,000 characters. Writable results also include machine-recorded evidence. `command_runs` records the setup commands, the worker's commands, and Sail-run required checks. Each record includes its exit code, source, and a `stale` flag set when the tree changed afterward. The ledger keeps the most recent forty records; `commands_total` counts every command, and `command_runs_truncated` marks a trimmed ledger. `edits_total` counts tree changes. Check these records instead of relying on the summary's claims: a result whose final state was never followed by a passing check is unverified, whatever its status. Writable calls can declare `setup_commands`: up to three commands that Sail runs inside the isolated project copy before the worker's first turn. Use them for deterministic dependency restoration. Setup records have `source="setup"` and turn zero. If one fails, Sail returns `stop_reason="setup_failed"` without starting the worker or spending model tokens. Setup commands run again when a saved task resumes because ignored dependency directories are not part of its checkpoint. A resume reruns the original setup by default. If the partial patch makes those commands invalid, pass `setup_commands=[]` to skip setup or pass up to three replacement commands. The override applies only to that resume. If resumed setup fails, the previous summary, partial patch, cumulative usage, and checkpoint remain available. Writable calls can declare `required_checks`: up to five commands, such as the project's tests, lint, or a generator followed by its drift check. Each entry must be one self-contained verification invocation. A leading `cd path && command` is allowed. Avoid `||`, `;`, pipelines, mixed precedence, and launchers that setup does not install. The worker receives these commands as immutable acceptance criteria. It may diagnose or repair its environment, but it cannot replace the gate. After the worker finishes, Sail runs the original checks before capturing the patch. A failure returns `stop_reason="checks_failed"` and a resumable checkpoint. When the failure evidence suggests a broken invocation, `failed_details` includes `gate_suspect=true`, and the patch and checkpoint remain available. Attempt-ceiling results also include required-check verdicts for the partial tree. A completed result means the declared checks passed against the delivered patch. At an attempt ceiling, Sail saves the original isolated baseline, conversation, partial patch, model, permissions, prompt cache identifier, and cumulative usage. The host must not apply or report that incomplete result as finished. It can call: ```text theme={null} sail_resume( delegation_id="", task_index=0, mode="finalize", instruction="Make only the named repair, run the named checks, and report.", wait=true ) ``` `task_index` is optional for a single delegation and required for fanout. `additional_turns` accepts 1 through 64; a first substantive resume may use the default 24. `mode="finalize"` is the closure device for a task that hit its ceiling or failed its required checks: Sail clamps the attempt to at most 8 turns, frames it as repair-verify-report only, and the declared checks still gate completion. After a task has failed two attempts, the host should stop granting resumes and apply the partial patch and finish the repair itself. A resume continues the checkpoint even if the live checkout changed after the first attempt. It never writes directly to that checkout. Each newly saved checkpoint refreshes its 24-hour resume window, and results and patches remain available for seven days. Older saved results from before this release remain collectible but cannot be resumed. To stop active work, ask the host to call `sail_cancel` with its delegation id. Closing or rejecting a waiting tool call does not cancel the work. Cancellation is cooperative, so a model response or command already in progress may finish first. Saved results remain available through `sail_collect`. ## Security boundary Repository content cannot establish trust, grant Sail ownership of the whole task, or override the approval boundary for writable delegation. Those decisions must come from the user, not instructions found in the repository. The plugin does not send the host coding provider's credentials to Sail. A `write=true` worker can still run the repository's build and test commands in its isolated project copy. Those commands run with the user's OS and network access. Although inherited credentials are removed from the command environment, this is not a full filesystem boundary. Repository code may discover on-disk CLI logins, cloud credentials, or SSH keys, and a background process may outlive the delegation. Use `write=false` for repositories you do not trust, or approve writable delegation with that boundary in mind. Reviewing the returned diff does not undo code that already ran. Sail Review uses `write=false`, so it does not execute repository code. ## Troubleshooting * **The tools are missing or the server failed to connect.** Install `uv`, restart the coding agent, and inspect its MCP server list. * **A call says no Sail API key is available.** Run `sail auth login`, then retry the call. No MCP restart is needed. * **The project is not a Git repository.** Initialize Git and create at least one commit before delegating. * **A delegation connection closed.** Call `sail_collect` without an id to list recent delegations for the current project, then collect the matching id. * **An incomplete result needs more work.** Collect the task by index, inspect its partial patch and cumulative usage, then use `sail_resume` before the 24-hour checkpoint expires. ## Related guides Run Claude Code itself on a Sail-hosted model. Run Codex itself on a Sail-hosted model. Connect your coding agent to Sail documentation and workflow skills. Browse the Sail model catalog.