Installation

A user install — the only installation scope. It configures whichever CLI it finds, and creates a private Python runtime used by installed commands.

Requirements

Python 3.9 or newer.
One of: Claude Code, Codex, or Grok Build.
Windows, macOS, or Linux.

Use uv run --no-project python as the interpreter — a bare python may be a Windows Store stub. The installer's floor is Python 3.9.

Install

$ git clone https://github.com/DanMcInerney/orchflows
$ cd orchflows
$ ./install.sh          # install.cmd on Windows

The installer configures whichever host CLI it finds. Each host keeps its own user-scope surface under its own home, and each home has an override the installer follows: CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME.

What it installs

A private runtime at ~/.orchflows/runtime — a Python environment used by installed commands even when installation starts from an active project environment. Dependencies are declared in requirements-runtime.txt with exact hashes.
The host block at ~/.orchflows/host-block.md — the always-on instruction layer and routing table every turn already pays for.
Per-host surfaces — skills, role agents, and config, merged into whichever host's home it found.

A custom skill, standard, or workflow declares its own requirements.txt beside it, and orchflows sync builds each its own environment. Dry runs (--dry-run) create nothing.

Hosts

Host	Home override	Note
Claude Code	`CLAUDE_CONFIG_DIR`	Default when `$ORCHFLOWS_HOST` is unset.
Codex	`CODEX_HOME`	Role agents and a `[subagents]` block.
Grok Build	`GROK_HOME`	Skills at `~/.grok/skills/`, one installer-owned rules file.

Update

$ git pull
$ ./install.sh

To check whether what's installed still matches the checkout you're standing in: python install.py doctor --quick.

Uninstall

$ python install.py --user --uninstall

Uninstall removes only what it generated, and retains the private runtime for explicit manual cleanup.

Observe

The local UI shows the current workflow graph without changing it. From a checkout:

$ uv run --no-project python reader/scripts/ui.py

It binds only to 127.0.0.1, serves its prebuilt assets offline, and exposes metadata rather than prompts, tool output, or transcript contents.