a48e4a5b6a
The template catalog is now Example 1-4: one stage, two stages (handoff), feedback loop (runner-owned limits, retries, timeout) and human decision (type=human approve/revise/abort with notify hooks). All read-only or leave changes uncommitted; none commits, pushes or deploys. A brand-new database (schema created by this Open) gets the examples once at server start, bound to the configured default model and harness. A server_settings marker records the decision, so removed examples never come back and existing installs are marked without any pipeline being added or rewritten.
193 lines
8.2 KiB
Markdown
193 lines
8.2 KiB
Markdown
# Pipelines
|
|
|
|
Small, reusable AI workflows for coding, research and everyday project work,
|
|
plus chats with the coding agents you already use.
|
|
|
|
Pipelines is one per-user server with three clients:
|
|
|
|
- **Web app** (Flutter, served behind a sign-in) and the same app as an
|
|
**Android APK**.
|
|
- **CLI and TUI** (`pipelines`) for scripting, inspection and authoring.
|
|
|
|
A **pipeline** is a versioned Markdown definition of stages (model, human
|
|
decision, notification). A **run** executes it in a project directory on the
|
|
server machine. A **chat** is a conversation with an agent harness (OpenCode,
|
|
Claude Code or Codex) that the server keeps going while you are away.
|
|
|
|
**Alpha:** single-user, supervised work. Models make mistakes and editing
|
|
stages change files and run commands. Start in a disposable project, review
|
|
results, and expect provider charges.
|
|
|
|

|
|
|
|
## Install
|
|
|
|
```sh
|
|
git clone https://git.a-wan.net/alan/pipelines.git
|
|
cd pipelines
|
|
./install # server + CLI + web app, login autostart
|
|
./install --apk # optional: Android app, offered to phones for update
|
|
```
|
|
|
|
Needs Go (version in `go.mod`), Node.js 18+, Python 3.9+, git, curl, a C
|
|
compiler, a **running Docker** (the web app is built in Docker; the install
|
|
refuses without it) and an existing OpenCode on `PATH`. The installer never
|
|
installs these for you. See [Installation](docs/install.md).
|
|
|
|
Then put the CLI on your `PATH`, open the URL the installer prints (default
|
|
`http://localhost:8082/`) and sign in with the password you chose:
|
|
|
|
```sh
|
|
export PATH="$HOME/.local/share/pipelines/bin:$PATH" # add to ~/.bashrc or ~/.zshrc
|
|
pipelines status
|
|
```
|
|
|
|
### Linux quick start (Debian/Ubuntu)
|
|
|
|
```sh
|
|
# Prerequisites: git, curl, a C compiler, Python 3, Node.js 18+ and Docker.
|
|
sudo apt update
|
|
sudo apt install -y git curl build-essential python3 nodejs npm docker.io
|
|
sudo usermod -aG docker "$USER" # then log out and back in (or: newgrp docker)
|
|
|
|
# Go: the version in go.mod is newer than most distro packages; use go.dev.
|
|
curl -fsSL "https://go.dev/dl/$(curl -fsSL 'https://go.dev/VERSION?m=text' | head -1).linux-amd64.tar.gz" \
|
|
| sudo tar -C /usr/local -xz
|
|
export PATH="/usr/local/go/bin:$PATH"
|
|
|
|
# OpenCode (required: it runs pipeline stages and chat by default).
|
|
curl -fsSL https://opencode.ai/install | bash
|
|
|
|
git clone https://git.a-wan.net/alan/pipelines.git && cd pipelines
|
|
./install
|
|
|
|
# Keep the server running after you log out (systemd --user service).
|
|
sudo loginctl enable-linger "$USER"
|
|
```
|
|
|
|
Check `node --version` is 18 or newer (older distros: install Node from
|
|
nodejs.org or NodeSource). On ARM machines use `linux-arm64` in the Go URL.
|
|
|
|
### Set up harnesses
|
|
|
|
One command per harness (native or Docker install). Each checks the CLI is
|
|
installed (printing the install command if not), signs in with the harness's
|
|
own login when needed, picks default models for OpenCode/Pi, and verifies it
|
|
the way the server does. No restart needed.
|
|
|
|
```sh
|
|
pipelines harness setup opencode # stages + chat (required; ./install configured it)
|
|
pipelines harness setup pi # pipeline stages
|
|
pipelines harness setup claude # chat
|
|
pipelines harness setup codex # chat
|
|
pipelines harness list # status of all four
|
|
```
|
|
|
|
## What you can do
|
|
|
|
**Runs**
|
|
- Runs list with filters, multi-select and delete, and sorting by newest,
|
|
oldest, **largest on disk**, duration, pipeline or status.
|
|
- Run detail tabs: Summary, Timeline, and Artifacts and Changes when the run
|
|
has any.
|
|
- Artifacts viewer for files a stage produced, including the recorded session
|
|
export (`session.html`).
|
|
- Changes: the file diffs each stage made in the workspace.
|
|
- Human decision stages: a run waits for you; decide in the app or with
|
|
`pipelines decide`.
|
|
- Retry from the failed stage, cancel, rename, per-run model overrides.
|
|
|
|
**Pipelines**
|
|
- A new install starts with four [example pipelines](examples/README.md),
|
|
from one stage to a review loop and a human decision; they are also the
|
|
template set.
|
|
- Draft-first authoring with a harness, versioned publishing, import/export
|
|
as ZIP.
|
|
- [Schedules](docs/schedules.md): recurring runs of an existing pipeline.
|
|
- Search across pipelines, versions, runs, steps, fields and artifacts.
|
|
|
|
**Chat**
|
|
- Chat with **OpenCode**, **Claude Code** or **Codex** in any folder on the
|
|
server, picked with the folder picker.
|
|
- Send messages while the agent is working: Claude Code and Codex receive them
|
|
mid-turn; otherwise the server queues them durably and delivers them in order
|
|
when the turn ends, even with no client attached.
|
|
- Approvals, questions, uploads, model choice and interrupt in the app.
|
|
- Adopt an existing harness session with `pipelines chat-adopt`.
|
|
|
|
**Notifications**
|
|
- The Android app keeps its own connection and shows notifications in the
|
|
background (no ntfy app needed).
|
|
- Settings: any run ended, chat needs you, chat reply finished, and
|
|
**Also send to ntfy** for devices that still use ntfy.
|
|
|
|
Pi runs pipeline stages (`harness=pi`) but is not offered as a chat harness.
|
|
See [Harnesses](docs/harnesses.md).
|
|
|
|
## Architecture
|
|
|
|
```
|
|
browser / Android app ──HTTPS (tailscale serve) or HTTP──┐
|
|
▼
|
|
web proxy (node, 0.0.0.0:8082) ── sign-in, web app, /updates/
|
|
│ same-origin /connect, /artifacts/
|
|
▼
|
|
pipelines CLI/TUI ──ws://127.0.0.1:8080/connect──► pipelines-server (SQLite)
|
|
│
|
|
┌────────────────────┬───────────────┼───────────────┐
|
|
▼ ▼ ▼ ▼
|
|
opencode serve pi (RPC) claude (stdio) Codex App Server
|
|
stages + chat stages chat chat (socket)
|
|
│
|
|
▼
|
|
ntfy (8090, optional fallback)
|
|
```
|
|
|
|
- **One server process** (`pipelines-server`) owns the database, runs, chats
|
|
and notifications. Its API has no authentication and binds to
|
|
`127.0.0.1:8080` by default.
|
|
- **One web app.** The authenticated Node proxy (`web/serve.mjs`) serves the
|
|
installed web build and proxies to the server. Every address (localhost,
|
|
LAN, tailnet) reaches this same proxy.
|
|
- **Tailnet HTTPS.** When `PIPELINES_WEB_PUBLIC_URL` is an `https://*.ts.net`
|
|
address, `./install` runs `tailscale serve` to point it at the proxy.
|
|
- **ntfy** is built from source and runs alongside, for optional fallback
|
|
delivery and stage notification hooks.
|
|
- A login service (launchd on macOS, `systemd --user` on Linux) supervises the
|
|
server, web proxy and ntfy together.
|
|
|
|
## Terminal quick start
|
|
|
|
```sh
|
|
export PATH="$HOME/.local/share/pipelines/bin:$PATH"
|
|
cd /path/to/your/project
|
|
pipelines # TUI
|
|
pipelines run "pipeline name" "Describe a small task"
|
|
pipelines runs
|
|
pipelines inspect 1
|
|
pipelines doctor
|
|
```
|
|
|
|
Runs use the directory you start them from, on the server machine. A browser
|
|
on another computer does not upload its files.
|
|
|
|
## Documentation
|
|
|
|
- [Installation and lifecycle](docs/install.md)
|
|
- [Harnesses: OpenCode, Claude Code, Codex, Pi](docs/harnesses.md)
|
|
- [Notifications](docs/notifications.md) · [ntfy reference](docs/ntfy.md)
|
|
- [CLI and authoring](docs/cli.md)
|
|
- [Schedules](docs/schedules.md)
|
|
- [Pipeline format](internal/author/skill/references/format.md)
|
|
- [Reasoning effort and stage limits](docs/harnesses-and-control.md)
|
|
- [Chat backend details](docs/chat-backends.md)
|
|
- [Artifacts](docs/stage-artifacts.md) · [File diffs](docs/stage-file-diffs.md)
|
|
- [Transfer pipeline definitions](docs/pipeline-transfer.md)
|
|
- [Docker installation](docs/docker.md)
|
|
- [Web proxy](web/README.md)
|
|
- [Alpha walkthrough and known limits](docs/first-version-testing.md)
|
|
|
|
When reporting a problem, include your OS, install mode, reproduction steps,
|
|
`pipelines version --json` and `pipelines ping --json`. Redact credentials and
|
|
private content; do not post your database or harness session storage.
|