@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.

Control Tower

symphony control-tower (alias: symphony monitor) gives a read-only snapshot of active runs, queue depth, proof completion, stale heartbeats, and token/cost data without needing the config file:

symphony control-tower                         # human-readable table (default)
symphony control-tower --json                  # automation-friendly JSON report
symphony control-tower --flow IST              # narrow to one flow
symphony control-tower --recent 10             # show only the 10 most recent runs (default: 25)
symphony control-tower --stale-after-ms 60000  # override stale-heartbeat threshold

The report covers:

• Flow status — running/stopped per managed flow with PID and start time
• Run snapshots — per-issue phase, ticket status, branch, PR link, attempt counts, and heartbeat age
• Queue summary — eligible and skipped tickets per tracker status
• Cost aggregates — input/output tokens and estimated cost per agent session
• IST connection status — whether the tracker API is reachable

Missing token, cost, and proof data is shown as unavailable or not captured rather than zero. Sensitive values (tokens, API keys) are redacted from all output.

OKF Context

Symphony can fetch Organizational Knowledge Framework (OKF) wiki bundles and inject them into the agent prompt before each dispatch. Enable it in the workflow front matter:

okf_context:
  enabled: true
  bundles:
    - project: IST
      slug: my-knowledge-bundle      # wiki page slug for the bundle root
      labels: [ui]                   # only inject for issues that carry all these labels
      tags: [astryx]                 # filter wiki pages by tag
      types: [Runbook]               # filter wiki pages by type
      include_body: true
      max_chars: 12000               # truncate combined context at this character limit

Each bundle maps to one ist wiki okf-context call. Multiple bundles are concatenated (separated by ---) and appended to the rendered prompt. A bundle is skipped for an issue if the issue does not carry all of the bundle's labels. Bundles with an empty labels list apply to every issue.

Full bundle fields: project, slug, labels, tags, types, resource_prefixes, slugs, include_body, max_chars.