satelle

module

v0.0.260 Latest Latest Go to latest Published: Jul 15, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/bobmcallan/satelle

Links

Open Source Insights

README ¶

satelle

Local-first substrate for agent-driven work. Satelle governs the authored process — stories, tasks, an evidence ledger, and authored markdown (documents, workflows, principles, skills) — backed by a per-repo SQLite database. Work moves through a gated workflow: the agent executes; isolated reviewers gate every status change. satelle runs 100% locally: a single static binary, no server, no cgo.

V6 rebrand of satellites. See docs/ for the product spec, port architecture, and the operating model.

Install

curl -fsSL https://github.com/bobmcallan/satelle/releases/latest/download/install.sh | sh

Downloads the latest release binary for your platform, sha256-verifies it, and installs to ~/.local/bin (override with SATELLE_INSTALL_DIR). Or build from source: make install.

Already installed? satelle update self-updates in place — it resolves the latest release, sha256-verifies it, replaces the binary, and restarts the background service. satelle update --check reports availability without installing.

Quickstart

go build -o satelle ./cmd/satelle   # or: make install

cd your-repo
satelle init           # scaffold .satelle/ (config, database, default workflows + skills) + validate the deployment
satelle story create --title "Ship the thing" --priority high
satelle task create  --title "write release notes"
satelle reindex          # index authored markdown under .satelle/
satelle status         # config, database, and store counts
satelle serve          # local web project page (http://127.0.0.1:8787)

While serve runs, the project page lists every story/task, and each links to a trackable detail URL — http://127.0.0.1:8787/story/<id> (or /task/<id>) — showing status, acceptance criteria, and the full ledger timeline. The server is local-only (there is no hosted URL).

Always-on service

satelle serve runs in the foreground. To keep the project page up across terminals and reboots, install it as a background service:

make install                 # build + place satelle on PATH (~/.local/bin)
cd your-repo
satelle service install      # systemd user service (Linux/WSL)
satelle service status       # show state + URL

Settings live in the machine-wide ~/.satelle/config.toml ([service] port / addr / repo). Change the port there (or pass --port) and re-run satelle service install. The service binds 0.0.0.0 by default, so in WSL it's reachable from a Windows browser at http://localhost:<port>. On native Windows (no systemd), service install prints Task Scheduler steps instead.

init is idempotent and writes a managed .gitignore block (the local .satelle/satelle.db stays out of git; the config and authored markdown are committed). It's also optional — a repo with no .satelle/satelle.toml runs zero-config on defaults, with data in .satelle/satelle.db travelling with the repo it governs.

Commands

Group	Verbs
`story` / `task`	`create`, `get`, `list`, `set`
`task` (only)	`archive` — dispose of a superseded header (record archived + files moved to `.satelle/backups/`)
`ledger`	`append`, `list`
`doc`	`list`, `get`
`hosted`	`login`, `logout`, `whoami` — authenticate to a hosted satelle-server (OAuth 2.1 + PKCE); optional, the local service runs standalone without it
`project`	`create`, `list`, `bind`, `show` — manage projects on the hosted satelle-server; `bind` records which hosted project this repo's personal sync targets. Requires `login` for create/list
`sync`	`scopes`, `config` (push/deploy), `documents` (push/pull), `workstate` (push/pull), `rehydrate`/`pull` (no push) — personal opt-in targets this repo's bound hosted project only; local is the default. Recover after clone/wipe: install → `login` → `project bind <slug>` → `sync rehydrate` (config deploy first, then documents + workstate pull)
`publish`	`push`, `list`, `adopt`, `check` — team catalog (select local artifacts to share; not a second home for the repo). Distinct from personal `sync`
`settings`	Read/write config in two scopes: repo `<key> [value]` (committed `.satelle/satelle.toml`; no args lists all) is the default; `--global server <url>` sets the machine-wide hosted server in `~/.satelle/config.toml` (no login; sign in after via the UI or `login`)
	`init`, `reindex`, `status`, `serve`, `version`

Both the CLI and the web server reach data the same way — through one verb registry (CLI / web → verb.Dispatch → store), so the two surfaces never drift.

Workflows & gates — the agent model

satelle governs work as a gated workflow: a story or task moves through a lifecycle of steps, and it is done only when its status says so — reached through every gate on the path.

The agent is the executor — it does the work and drives the story forward.
satelle is the gatekeeper of status — each forward transition is judged by an isolated, fresh-context reviewer (an agent -p rubric, or a deterministic functional check). Accept enacts the transition; reject pushes notes back. A reviewer is read-only — it judges, never mutates. Each gate is one isolated, fresh-context call over a payload satelle builds; satelle does the context selection, the reviewer reads what it needs through its read-only tools.

Workflows are authored substrate in the DOT standard (Graphviz): a node-centric graph where each node is a step carrying an agent (executor/reviewer) and a gate is named prompt="@skill:NAME" on a reviewer node or an edge (the legacy edge reviewer_skill= attribute still parses). The embedded satelle-baseline-workflow (backlog → in_progress → done) is the order-zero default; a repo overrides it under .satelle/workflows, and a YAML lifecycle is auto-converted to DOT on ingest. How each agent runs is bound in .satelle/agents.toml — the reviewer's agent CLI (claude works; codex is a selectable stub) and its read-only grant; the executor runs in-loop.

Process is configuration — change the workflow or its skills, change the process, with no binary release. See satelle help reviewer-checks and the satelle-agent-model and satelle-dot-standard principles.

Architecture

Pure-Go SQLite (modernc.org/sqlite, no cgo) — one static binary.
Gated workflows: authored DOT lifecycles drive each story; isolated reviewers gate status transitions, with the agent backend bound per repo.
System-of-record split: stories/tasks/ledger are dynamic SQLite rows; authored markdown is the source of truth, synced into a SQLite index by a directory monitor.
Config: per-repo .satelle/satelle.toml with defaults for every setting and a gitignored satelle.local.toml overlay. Optional stories_keep_closed (count) and stories_keep_days (age) prune closed stories' attachment dirs under .satelle/stories — moving them to .satelle/backups/stories/; a non-terminal story's dir is always kept.

See docs/spec.md, docs/architecture.md, and docs/agent-model.md (the operating model: reviewer premise, DOT workflows, isolated fresh-context review).

Development

go test ./...           # unit + package tests (also run in CI)
make integration        # black-box CLI + browser end-to-end (local only)

The integration suite (in tests/, behind the integration build tag) runs against a real binary and drives the web front end in headless Chrome (chromedp) — tab switching, inline expand, live filtering, and realtime updates are all asserted in a real browser, not eyeballed. It needs a Chrome/Chromium binary (SATELLE_CHROME overrides the path); it runs locally only, not in GitHub CI, because it needs a browser and the running binary. make integration builds satelle once and passes it via SATELLE_BIN (point that at any binary to test it directly). Releases are cut by .github/workflows/release.yml when .version is bumped; CI (test.yml) runs unit tests + build/vet/gofmt only.

satelle dogfoods itself — this repo is set up with satelle init, and its remaining build phases are tracked as stories in the local database.

License

MIT — see LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api Package api provides reference wire types for the satelle hosted API.	Package api provides reference wire types for the satelle hosted API.
cmd
satelle command
internal
agentcli Package agentcli abstracts the headless agent CLI the quality-management spine shells out to for isolated reviews and summaries.	Package agentcli abstracts the headless agent CLI the quality-management spine shells out to for isolated reviews and summaries.
agentstep Package agentstep is satelle's isolated-agent dispatch engine — the quality-management spine that runs a fresh-context agent over a workflow step and folds its result back in.	Package agentstep is satelle's isolated-agent dispatch engine — the quality-management spine that runs a fresh-context agent over a workflow step and folds its result back in.
agentvalidate Package agentvalidate is the store-free, deterministic check of the agents layer (.satelle/agents.toml) and each workflow's agent= node bindings.	Package agentvalidate is the store-free, deterministic check of the agents layer (.satelle/agents.toml) and each workflow's agent= node bindings.
app Package app is satelle's local bootstrap (build order step 3).	Package app is satelle's local bootstrap (build order step 3).
arbor Package arbor is V5's structured logger.	Package arbor is V5's structured logger.
buildinfo Package buildinfo holds satelle's build identity — the version, commit, and build time stamped into the binary at release time via -ldflags.	Package buildinfo holds satelle's build identity — the version, commit, and build time stamped into the binary at release time via -ldflags.
cli `satelle agent` selects the headless agent CLI the quality-management spine shells out to for isolated reviews/summaries (the install-time choice, sty_b6973a7b).	`satelle agent` selects the headless agent CLI the quality-management spine shells out to for isolated reviews/summaries (the install-time choice, sty_b6973a7b).
config Package config is satelle's trimmed TOML configuration, ported from satellites' internal/cliconfig with the server/token/credstore surface dropped (the OSS tier is always local — no remote dispatch).	Package config is satelle's trimmed TOML configuration, ported from satellites' internal/cliconfig with the server/token/credstore surface dropped (the OSS tier is always local — no remote dispatch).
docindex Package docindex is satelle's directory monitor for authored markdown.	Package docindex is satelle's directory monitor for authored markdown.
help Package help carries satelle's embedded help topics — product documentation that ships in the binary (every repo gets it) and is surfaced by BOTH the CLI (`satelle help [topic]`) and the local web server (`/help`).	Package help carries satelle's embedded help topics — product documentation that ships in the binary (every repo gets it) and is surfaced by BOTH the CLI (`satelle help [topic]`) and the local web server (`/help`).
hosted Package hosted is the client half of satelle's hosted-server integration (sty_2fc93374): the OAuth 2.1 + PKCE login flow, a per-user credential store, and an authenticated HTTP client with transparent refresh-on-401.	Package hosted is the client half of satelle's hosted-server integration (sty_2fc93374): the OAuth 2.1 + PKCE login flow, a per-user credential store, and an authenticated HTTP client with transparent refresh-on-401.
lease Package lease persists an EXPLICIT, OWNED engagement seat for satelle work items (sty_8426b9c0).	Package lease persists an EXPLICIT, OWNED engagement seat for satelle work items (sty_8426b9c0).
ledger Package ledger is satelle's append-only event log — the "evidence" dynamic primitive.	Package ledger is satelle's append-only event log — the "evidence" dynamic primitive.
logfile Package logfile is the single, shared rotating-append writer for satelle's flat evidence logs under .satelle/logs (the operation log and the reviewer log).	Package logfile is the single, shared rotating-append writer for satelle's flat evidence logs under .satelle/logs (the operation log and the reviewer log).
oplog Package oplog is satelle's flat-file OPERATION log — an append-only, plain-text record of every state-mutating CLI operation, written under <dataDir>/logs/operations.log (sty_be257fef).	Package oplog is satelle's flat-file OPERATION log — an append-only, plain-text record of every state-mutating CLI operation, written under <dataDir>/logs/operations.log (sty_be257fef).
store Package store opens the per-repo sqlite database (.satelle/satelle.db) and wires the dynamic-primitive stores plus the authored-doc index onto the one shared handle.	Package store opens the per-repo sqlite database (.satelle/satelle.db) and wires the dynamic-primitive stores plus the authored-doc index onto the one shared handle.
structure Package structure holds satelle's DETERMINISTIC structural-conformance checks for authored substrate — the spine that defines what a valid skill, workflow, principle, or story draft IS.	Package structure holds satelle's DETERMINISTIC structural-conformance checks for authored substrate — the spine that defines what a valid skill, workflow, principle, or story draft IS.
subsync Package subsync materialises a versioned config bundle into a repo byte-for-byte (epic:scoped-sync, order:5).	Package subsync materialises a versioned config bundle into a repo byte-for-byte (epic:scoped-sync, order:5).
verb Package verb is satelle's single execution path.	Package verb is satelle's single execution path.
web Package web is satelle's local web server — a project page for one repo, rendered through verb.Dispatch (the same seam the CLI uses).	Package web is satelle's local web server — a project page for one repo, rendered through verb.Dispatch (the same seam the CLI uses).
wfdot Package wfdot parses a workflow's fenced ```dot block into a neutral spec — the SINGLE DOT-to-spec path shared by the web diagram, the reviewer gater, and the commit/edit hooks (so the grammar is defined once, never copied).	Package wfdot parses a workflow's fenced ```dot block into a neutral spec — the SINGLE DOT-to-spec path shared by the web diagram, the reviewer gater, and the commit/edit hooks (so the grammar is defined once, never copied).
wfgovern Package wfgovern is the leaf package for workflow selection: which workflow governs a work item (stamp, then category/kind priority).	Package wfgovern is the leaf package for workflow selection: which workflow governs a work item (stamp, then category/kind priority).
workitem Package workitem is satelle's unit-of-work dynamic primitive — stories and tasks.	Package workitem is satelle's unit-of-work dynamic primitive — stories and tasks.
workspace Package workspace aggregates several satelle repos into one read-only view.	Package workspace aggregates several satelle repos into one read-only view.