@nutteen/symphony

Symphony is a dev-machine runner that polls the issue tracker and dispatches host-installed agent CLIs against external workflow files.

Install

When both ist and Symphony need to be installed or updated:

npm install -g @nutteen/ist @nutteen/symphony

When ist already exists:

ist --version
ist auth status
npm install -g @nutteen/symphony

Host prerequisites are not bundled in this package: Node 20+, ist, git, and whichever tools a workflow needs, such as gh, claude, codex, and project build tools. Symphony invokes those CLIs on the host and uses their normal host auth/config.

Foreground Mode

symphony run ~/symphony-runner/workflows/IST.md --format human

Foreground mode runs one workflow file and uses workspace.root from that workflow.

Managed Mode

symphony --config ~/symphony-runner/flows.yaml start
symphony status
symphony logs IST -f
symphony logs IST --json
symphony stop IST
symphony stop --all

Managed config is a start plan:

runtime_dir: ~/.symphony
flows:
  - name: IST
    workflow: ~/symphony-runner/workflows/IST.md
    workspace_root: ~/symphony/workspaces/IST

runtime_dir stores Symphony runner state: PID files, JSONL logs, and runtime records. workspace_root stores per-issue agent workspaces and overrides the workflow file's workspace.root for that managed flow. Observation commands read runtime records and do not require the config file.

Runtime directory precedence is:

CLI --runtime-dir > config runtime_dir > SYMPHONY_RUNTIME_DIR > ~/.symphony

Workflow files stay external to the npm package.