Metadata-Version: 2.4
Name: striatum-orchestrator
Version: 1.53.0
Summary: Local-first orchestration for terminal-based AI coding agents
Author: Hal Britt
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/halbritt/striatum
Project-URL: Repository, https://github.com/halbritt/striatum
Project-URL: Issues, https://github.com/halbritt/striatum/issues
Project-URL: Changelog, https://github.com/halbritt/striatum/blob/main/CHANGELOG.md
Keywords: ai-agents,cli,local-first,orchestration,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.1
Requires-Dist: markdown-it-py>=4.0
Provides-Extra: daemon-pg
Requires-Dist: psycopg[binary]>=3.2; extra == "daemon-pg"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# striatum

Local-first orchestration for multiple terminal-based AI coding agents.

`striatum` is a small, repo-local control plane for coordinating AI
coding agents that live in terminals: Codex, Claude Code, Gemini
CLI, or any other model runtime that can be represented as a
command. It is built for workflows where several agents need to
draft, review, synthesize, repair, and report on work without
relying on a hosted coordinator or hidden chat transcripts.

The important distinction is this: per
[D094 / RFC 0043](docs/rfcs/0043-postgres-as-sole-substrate-and-daemon-required-runtime.md),
the authoritative live state is the daemon-owned PostgreSQL
instance, scoped per registered target repository, for runs, jobs,
sessions, queue messages, leases, blockers, verdicts, artifacts,
and events. `.striatum/` survives next to each target repo as
operational scratch (supervised wrapper FIFOs, pidfiles, the
capability-token cache). Repository files (prompts, findings,
ledgers, syntheses, decisions, handoffs, redacted evidence
exports) are durable provenance, not the live message bus.
Marker files, tmux pane state, terminal output, and provider
hooks are useful for humans, but they do not advance state.

Existing repos with a populated `.striatum/state.sqlite3` migrate
to the new substrate with
[`striatum daemon migrate-repo-local`](docs/POSTGRES_TRANSITION.md);
the daemon is a hard prerequisite for every Striatum verb after
D094, and `--no-daemon` is retired. RFC 0048 covers the remaining
handler-port work where some daemon RPC routes still delegate to
the SQLite-backed CLI path under a test-harness escape.

## Status

Per-version release notes live in [`CHANGELOG.md`](CHANGELOG.md);
the latest tagged version is the source of truth. The package is
published to PyPI as `striatum-orchestrator` (the bare `striatum`
name on PyPI is unrelated); the Python module name is still
`striatum`. RFC status lives in
[`docs/rfcs/README.md`](docs/rfcs/README.md); accepted and
proposed RFCs span RFC 0001 through the RFC 0048 substrate-port
proposal.

## Install

From PyPI:

```bash
pip install striatum-orchestrator
striatum --help
```

From a checkout of this repository:

```bash
make install
.venv/bin/striatum --help
```

For development without installing the console script:

```bash
PYTHONPATH=src python3 -m striatum.cli --help
```

Run the tests with:

```bash
make test
```

## Quick Start (Human Operator)

You will run `striatum` commands by hand.

```bash
TARGET_REPO=/path/to/your/repo
WORKFLOW=examples/code-change-flow/workflow.json   # or choose a type in docs/WORKFLOW_TYPES.md

striatum --repo "$TARGET_REPO" init --json
striatum --repo "$TARGET_REPO" workflow validate "$WORKFLOW" --json
striatum --repo "$TARGET_REPO" run prepare --workflow "$WORKFLOW" --json
striatum --repo "$TARGET_REPO" run start --run-id <run_id> --json
striatum --repo "$TARGET_REPO" dashboard --run-id <run_id> --once
```

From here you register a session and claim work. The full
operator playbook is [`docs/HOW_TO_HUMAN.md`](docs/HOW_TO_HUMAN.md).

## Quick Start (Coding Agent)

You will install the runner, install the *agent skill bundle*
(RFC 0015), and hand the agent a target repo with a workflow
file in it. The agent does the rest. For first-time setup,
combine `--with-skills` and `--with-ddd-layout` (RFC 0021) so
the target repo gets both the agent-facing skills and the
human-facing DDD doc layout in one command:

```bash
TARGET_REPO=/path/to/your/repo
striatum --repo "$TARGET_REPO" init \
  --with-skills claude_code \
  --with-ddd-layout \
  --json
# now point your Claude Code session at $TARGET_REPO and tell it:
#   "drive the workflow at <path>/workflow.json using striatum"
```

The single command above initializes `.striatum/`, writes the
agent skill bundle to `.claude/skills/striatum-*/`, and
scaffolds the seven canonical human-facing DDD documents
(`docs/SPEC.md`, `docs/PRD.md`, `docs/DECISION_LOG.md`,
`docs/UBIQUITOUS_LANGUAGE.md`, `docs/DDD.md`,
`docs/rfcs/README.md`, `docs/rfcs/0001-template.md`).
Existing files are preserved; pass `--ddd-layout-dry-run` to
preview, `--ddd-layout-force` to overwrite (records
`prior_sha256` for audit). For agents without a skill
convention, `striatum skills install --profile generic`
writes a single `STRIATUM_AGENT_GUIDE.md` you can paste into a
system prompt. The long-form companion to the bundle is
[`docs/HOW_TO_AGENT.md`](docs/HOW_TO_AGENT.md).

## Web UI

```bash
striatum --repo "$TARGET_REPO" serve --web
# bound port is in the startup envelope; pass --port for a fixed one
```

The web UI (RFC 0022) is server-rendered Jinja2: real HTML
pages at `/`, `/run/<id>`, `/run/<id>/job/<id>`,
`/run/<id>/artifact/<id>`, `/workflows`, `/chat`, and `/doctor`.
Run/workflow filters, localtime toggle, graph tooltips, keyboard
shortcuts, and doctor grouping are built as vanilla-JS progressive
enhancements. The dependency graph renders as inline SVG with
state-colored nodes that click-navigate. Light + dark mode follow
`prefers-color-scheme`. Localhost-only by default; mutations gated
behind `--allow-mutations`.

Chat workflow generation follows preview-then-confirm: the preview tool
writes nothing, and the write tool is hidden unless mutations are enabled
and still requires a separate browser-side operator confirmation.

Operator AI sessions can drive a dogfood end-to-end through the
[MCP dogfood-lifecycle chat tools](docs/MCP.md#dogfood-lifecycle-tools)
(RFC 0040 V1) instead of bash CLI invocations with hand-copied
session/lease/message ids. New workflows pick up the per-model
"no-questions" harness-profile fragments automatically; existing
workflows can be backported with `striatum workflow upgrade <path>`.
See [`docs/HARNESS_FRICTION_PATTERNS.md`](docs/HARNESS_FRICTION_PATTERNS.md)
for the long-form record of the operator-side friction patterns
addressed by V1.

## Optional Multi-Repo Registry And Sweep

```bash
striatumd --max-sweeps 1 --json              # foreground sweep process
striatum repo add /path/to/target --json
striatum dashboard --all --json
striatum --daemon --repo /path/to/target status --json
```

RFC 0028 V1 is local-first and optional. It adds registry-backed
multi-repository read visibility, daemon audit metadata, resources-only
daemon MCP, and a foreground recovery sweep process. It does not ship a
daemon RPC server in V1: CLI and MCP clients open the owner-only registry
SQLite directly under token/capability checks. Direct repo-local CLI mode
remains the default. `dashboard --all` is registry-backed and requires a
daemon token; run `repo add` or `daemon start` first to bootstrap the local
admin token, or pass an explicit token through the client surface.
`repo add` registers an already-initialized repository by default; use
`repo add --init` only when you intentionally want registration to
initialize the target. V1 does not add daemon-owned supervision, MCP
mutation tools, sealed apply/signing, hosted service semantics, audit
retention/rotation, or stronger provenance than the selected workflow
`provenance_mode` already provides.

RFC 0033 V2 accepts system PostgreSQL as the daemon-owned storage
substrate for daemon-global registry, audit, capability, scheduler, and
RPC-session state. Configure it with `STRIATUM_DAEMON_DB_URL`, daemon
config, or an explicit `--postgres-url` client surface. The cutover
command is `striatum daemon migrate --from sqlite --to pg` (`--dry-run`
inspects first; `--keep-sqlite-readonly` keeps the V1 file as an audit
tombstone). RFC 0043 / D094 then moves per-repository workflow state
into the same daemon-owned Postgres under a `repository_id` scope;
existing repos cut over with `striatum daemon migrate-repo-local`
(see [`docs/POSTGRES_TRANSITION.md`](docs/POSTGRES_TRANSITION.md)).

RFC 0030 and RFC 0031 add the daemon V2 RPC/supervision/apply
foundation on top of that substrate: envelope-v1 JSON, version
handshake, method registry, request/audit helpers, daemon supervisor
metadata, repo-local supervisor pointers, and apply receipts. RFC 0032
adds the V2 cross-repo schema/migration and daemon MCP mutation
capability-gating foundation; the full two-repo daemon end-to-end test
harness remains deferred. Hosted service semantics and
malicious-local-operator-resistant sealed apply remain out of scope.

## What It Is For

striatum is for long-running, review-heavy agent workflows where
"just tell three agents to work in tmux panes" stops being
enough. It gives the human and coordinator a stable answer to
questions like:

- What run is active, on which branch was it confirmed, and
  which jobs are claimable, blocked, in review, or waiting on a
  human?
- Which session owns a lease? What artifact was required, where
  was it written, what hash was recorded?
- Did a review return `needs_revision`, and did the workflow
  declare a safe cycle for that?
- Can I commit a redacted evidence summary without committing
  live SQLite state or transcripts?

The runner is intentionally conservative. It coordinates work; it
does not decide that an agent is done because a terminal printed
a phrase. Agents and humans move the workflow by calling
`striatum` commands.

striatum is a domain-driven workflow runner: the vocabulary in
[`docs/UBIQUITOUS_LANGUAGE.md`](docs/UBIQUITOUS_LANGUAGE.md) is the
*model*, not just documentation; the CLI verbs are the only legal
mutations. [`docs/DDD.md`](docs/DDD.md) explains why the
vocabulary is load-bearing instead of bookkeeping.

## Documentation Map

| File | When to read |
|---|---|
| [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) | First 15 minutes; forks human-operator vs. coding-agent setup. |
| [docs/HOW_TO_HUMAN.md](docs/HOW_TO_HUMAN.md) | The operator's long-form playbook; every CLI verb in the order you use it. |
| [docs/HOW_TO_AGENT.md](docs/HOW_TO_AGENT.md) | Long-form companion to the RFC 0015 agent skill bundle. |
| [docs/WORKFLOW_TYPES.md](docs/WORKFLOW_TYPES.md) | Which workflow shape and lane set to choose; current starters, examples, defaults, and chooser roadmap. |
| [docs/WRITING_WORKFLOWS.md](docs/WRITING_WORKFLOWS.md) | How to author your own `workflow.json`. |
| [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) | Flat list of every CLI verb and stable exit codes. |
| [docs/POSTGRES_TRANSITION.md](docs/POSTGRES_TRANSITION.md) | Operator runbook for the D094 / RFC 0043 PostgreSQL cutover and per-repo migration. |
| [docs/SPEC.md](docs/SPEC.md) | The implementation contract; the source of truth when this page disagrees with the runner. |
| [docs/INDEX.md](docs/INDEX.md) | Every doc in `docs/` with a one-line summary. |

## License

Apache-2.0. See [`LICENSE`](LICENSE).
