7.7 KiB
Pipelines
Reusable, sequential workflows for your repositories. A Go CLI/TUI and native server reuse your OpenCode login; Docker ntfy handles phone notifications.
Install
./install.sh defaults to full Docker server + ntfy setup; use --native for
native binaries only. Docker mode needs Docker Compose and Python 3; native
mode needs Go 1.27+ and uses your existing OpenCode for model stages.
git clone https://git.a-wan.net/alan/pipelines.git
cd pipelines
./install.sh # configure/start Docker services and connect a provider
# Optional host CLI/TUI binaries: ./install.sh --native
Go uses GOBIN or its normal GOPATH/bin default; put that directory on PATH.
The Docker installer automatically detects/configures LAN networking for ntfy;
you do not need to look up your IP or supply a URL/listen address.
Both Docker services bind 0.0.0.0; reinstall normalizes those bind settings
without replacing your URLs, timezone, ports or credentials.
Native mode installs the Go binaries and shared OpenCode pipelines skill without
login checks or automatic services. Docker mode configures ntfy accounts/token,
checks publishing/health, and opens container OpenCode provider login on first setup;
existing settings, credentials and volumes are retained on reinstall.
With plain go install ./cmd/..., also run pipelines skill install.
For system-wide use, install the binaries into your chosen system bin directory
with the appropriate permissions. Configuration and data remain per-user.
Start a native server explicitly; fresh databases contain no pipelines:
pipelines serve # foreground server
# In another terminal:
pipelines
Optional autostart at login (starts the server now):
pipelines service enable
pipelines service status
Uses user-level systemd on Linux or launchd on macOS; no sudo. Runs use the
directory you invoke pipelines run from. Preview with --print. Stop any existing
foreground/legacy server first. Disable with pipelines service disable before
uninstalling. See installation for environment and boot options.
Uninstall
pipelines uninstall # remove Go binaries; keep history, drafts, and ntfy data
A three-stage pipeline
Plan → Implement → Review. Each stage receives the previous stage's output;
the first receives your task prompt. One outcome selects the next stage—no
parallel branches. Definitions use Markdown output, prompt, tools,
configs, and edges blocks. For example:
# stage planner
```output
{ task, plan, acceptance_checks }
```
```prompt
Turn input.prompt into a focused plan and acceptance checks.
```
```tools
```
```configs
provider=opencode-go
model=deepseek-v4.1-flash
retries=0
```
```edges
success -> implementer
error -> #failure
```
The complete three-stage example adds the implementer and reviewer. Review and explicitly submit it:
pipelines validate examples/three-stage.md
pipelines submit examples/three-stage.md --name "three stage" --create-only
pipelines run "three stage"
Every submission is validated and creates an immutable version. Examples are optional; nothing is imported automatically. Run from your repository directory; stage tools are enabled automatically. Edits support any language/file type and new files. No file list or typed RUN confirmation is required.
Useful commands
pipelines # dashboard; b browses templates
pipelines list
pipelines run # fuzzy selection + multiline prompt
pipelines run "bug fix" "Fix the layout" # run in the current repository
pipelines new "daily digest" "Summarize changes"
pipelines edit "bug fix" "Add a review step"
pipelines drafts --json
pipelines validate /path/to/draft.md
pipelines submit /path/to/draft.md # explicit publication
pipelines runs
pipelines inspect 1
pipelines serve # foreground server; Ctrl+C stops it
pipelines ping
pipelines help edit
CLI new/edit open OpenCode directly with @pipelines. The installed skill asks
missing questions; pipelines new needs no preliminary questionnaire. Changes stay
as drafts by default; CLI and TUI share validation and draft storage. Most
commands support --json for agents and scripts.
In the TUI, press d (or use :drafts) to browse retained drafts, including CLI-created ones. e reopens a draft, v validates it, and s opens explicit submission confirmation. Drafts remain retained after submission.
From a run, press p / :pipeline to open the pipeline version it used.
Initial run input also records pwd. Press r / :retry on a failed run
(or pipelines retry <run-id>) to start a new attempt with the same original
input, directory, and pipeline version. Completed side effects are not undone.
Retries restart at the entry stage with fresh OpenCode sessions, never the previous
conversation or intermediate stage output. Pipelines does not automatically delete
generation, agent, or formatting-repair sessions, including on failure/cancellation.
Primary session IDs are retained in run steps (pipelines inspect <run-id> --json).
On Home, r opens all recent runs; both Home panels show the shortcut.
Quit the TUI with :quit; q does not exit. Ctrl+C remains an interrupt.
Starting/retrying/canceling runs and deleting drafts require confirmation. CLI
publication also prompts; use --yes only for explicitly approved automation.
n / :new and creating from a template offer a Tab-navigable, fuzzy-searchable
picker: nvim opens the draft Markdown file; OpenCode authors it with you.
Canceling the picker creates no draft and publishes nothing.
Wide terminals show runs and pipelines side by side; narrow terminals stack them.
The TUI uses soft light/dark-adaptive cards, muted metadata, subtle selections,
and local loading animations instead of heavy character borders and inverted bars.
The dashboard includes all-history usage, success rate, average completed duration,
per-pipeline usage, and a 14-day activity chart. CLI: pipelines stats [--json].
Use :status for a scrollable server/ntfy popup with health, ports, server-computer
IPs and candidate URLs. CLI: pipelines status [--json]. Candidate URLs are not
verified reachable; publishing endpoints and credentials are not disclosed.
Retry is offered only after the failed run and its agent have fully stopped.
The run inspector shows its actual path above the details, using the same graph
renderer as pipeline definitions. g focuses the graph (arrows pan, j/k scroll).
The path and elapsed duration update while running. a opens the active/latest
OpenCode session's recorded tool evidence; this does not attach a live OpenCode UI.
Press D / :debug (or pipelines debug <run-id>) for a fresh OpenCode
conversation about that run. It uses CLI queries rather than resuming or retrying
the implementing agent. Pipeline Edit offers a fuzzy-searchable nvim /
OpenCode picker; Tab and Shift+Tab navigate it.
In the draft browser, x then y deletes the selected retained draft and
metadata. CLI: pipelines draft-delete <draft.md>. Published history is untouched.
Model results use native JSON-schema output where supported, precise parsing errors, and bounded format-only repair without replaying tools. Optional stage permissions narrow file/command access without imposing a language-specific default. See model result recovery and permissions. The run graph header shows start time and elapsed/final duration, plus finish time for completed runs.
More: CLI · installation · pipeline format.