Files
pipelines/README.md
T
alan 3e100f78f3 Document the current install, harnesses and notifications
Rewrite the README around the server, web/Android app and CLI, and
replace docs/install.md with the current native install (all-or-nothing
Docker web build, flags from setup-native.py, lifecycle commands, data
locations, password, upgrading). Add docs/harnesses.md and
docs/notifications.md; point ntfy.md at the new overview and fix its
topic name.
2026-11-02 15:54:25 +00:00

144 lines
6.4 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.
![Workflow](docs/images/workflow.png)
## 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 open the URL the installer prints (default `http://localhost:8082/`) and
sign in with the password you chose.
## 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**
- Starter templates, 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.