Documentation · Start here · Installation · Release notes

English · 简体中文 · 日本語

Slipway

AI coding tools are fast, but a long autonomous session can stray from the task you asked for, claim to have run checks it skipped, or declare the work done before the changes land in the repository.

Slipway is a user-invoked soft autopilot. It wraps an AI coding session in a lightweight, resumable workflow while keeping decisions and control with the user.

A Slipway Run moves through one bounded Action at a time: orient, clarify, implement, review, or summarize. The order is not a fixed pipeline — the CLI derives each Action from the last Outcome and its own Git observation.

The host performs the work. The Slipway CLI records the Run, observes repository changes, and provides structured recovery. It does not call a model or own/manage provider credentials, and it does not decide that the software is ready to merge or release.

[!IMPORTANT] Use a build whose slipway --help lists install, uninstall, list, doctor, run, status, and stop, alongside the protocol group that generated adapters call. Package-manager channels can lag the repository. Until a tagged release contains this interface, build the current checkout from source.

Why use Slipway?

• Explicit start: nothing starts on its own. You invoke a generated capability or the CLI for a specific task.
• User control: skip, stop, resume, reorder, or take over. No explanation needed.
• Facts before questions: the host inspects the repository before asking you to make a decision.
• Recoverable Runs: an append-only journal and pinned source material let a Run resume without relying on chat history.
• Optional GitHub source: use a self-contained Change Issue for durable work, or start ad hoc when an Issue is unnecessary, unavailable, or inappropriate.
• Honest outcomes: every command, exit code, finding, known issue, and uncertainty is reported. An ended Run only means the Action queue is empty.

Quick start from this checkout

Build Slipway with the Go version declared in go.mod, then install the adapter for your AI coding host:

go build -o ./slipway .
./slipway install --tool claude
./slipway doctor

In Claude, explicitly invoke the generated slipway-run skill and describe one task. For another host, replace claude with one of:

codex  copilot  cursor  kilo  kiro  opencode  pi  qwen  windsurf

Kiro requires a surface on first install:

./slipway install --tool kiro --surface ide   # or: --surface cli

The generated capability drives the machine protocol for you. If you are integrating a host directly, an ad-hoc Run starts with:

./slipway run -- "add CSV export to the reports command"

Run d51ecc3e-3b77-4e27-b9e4-f32fa5a0f11c started.
State: active
Goal: add CSV export to the reports command
Budget remaining: 7
Current action: orient (6da7c41d-7283-4c68-9238-868f3502f67c)
Next choices:
- submit-outcome-file: requires outcome_file (path via --outcome-file)
- submit-outcome-stdin: slipway protocol submit --run d51ecc3e-… --action 6da7c41d-… --root /path/to/reports --outcome-stdin
- skip-action: slipway protocol skip --run d51ecc3e-… --action 6da7c41d-… --root /path/to/reports

That is the shape of a Run: one Action at a time, a remaining budget, and an exact next command for every branch the host can take — including skip, which never needs a reason. The CLI chose and recorded that Action; it never edits code on its own. Add --json for the machine-readable form.

See the getting-started guide for the complete interaction and the machine protocol for integration details.

Sources and Runs

Source	Use it when	What Slipway records
Ad hoc	The task is small, private, urgent, offline, or deliberately not tracked in GitHub.	The goal and subsequent Run events.
GitHub Change Issue	The task needs a reviewable, revision-pinned requirements source.	Stable Issue identity, a bounded section catalog, and accepted section material by digest.

A GitHub Objective Issue may group several Changes, but only a self-contained Change can start an issue-backed Run. Repository ownership by a personal account or an organization is not part of the source format. Slipway does not require GitHub Projects, organization-only Issue Types, or organization-only fields.

The generated workflow capability coordinates the functions in Slipway's Issue workflow. From a rough idea, Objective, Change, or existing Run it inspects the current stage and names the shortest valid next explicit capability or an explicit no-further-action outcome. It may investigate facts, interview genuine decisions, and synthesize a work-item draft when needed, but it is not a general skill router. It is self-contained and may reuse only an already-installed, model-invocable /grilling primitive; it never invokes user-only front doors, writes to GitHub, or starts a Run itself.

This is the beginning of the README. Read the rest at the original. Read the full README ↗