Originated from OpenAI Symphony, Lorenz lets you declare work on a tracker (in-memory, Obsidian markdown files, Linear, Jira, Slack, Discord) and manages the dispatch, execution, and convergence of concurrent agent sessions until they reach a specified terminal state. It is harness-agnostic through the Agent-Client Protocol, running agents on local machines, static SSH boxes, or (experimental) cloud-brokered VMs.

Features

Any tracker Linear, Jira, Slack, Discord, Obsidian, local files, or in-memory.

Harness-agnostic Codex, Claude, or anything that speaks the Agent-Client Protocol.

Concurrency control Global and per-host caps, with routing labels to share one project across instances.

Retry and backoff Rate-limit aware, with stall detection and automatic requeue.

Two operator views An Ink terminal dashboard and a web dashboard over one runtime snapshot.

Local, SSH, or cloud workers Disposable local boxes, static SSH hosts, or brokered VMs on demand.

Quickstart

Running Lorenz is as easy as:

npx lorenz WORKFLOW.md

The full CLI surface:

lorenz [--once] [--dry-run] [--no-tui] [--port <port>] [--logs-root <path>] [path-to-WORKFLOW.md]
lorenz runs [--issue ID] [--failed] [--cost] [--retries] [--id RUN_ID] [--limit N] [--json]

--logs-root <path> writes logs under <path>/log/lorenz.log. With no workflow path the CLI reads LORENZ_WORKFLOW, then ./WORKFLOW.md. See CLI for every flag and command.

Runtime needs depend on the workflow: tracker credentials such as LINEAR_API_KEY or DISCORD_BOT_TOKEN, codex on PATH for Codex runs, a Claude ACP bridge for Claude runs, and SSH access for remote workers. See Getting started for the full list. Run commands from the repository root unless a command says otherwise.

How It Works

Lorenz polls a tracker for eligible issues, dispatches each one to a worker as a concurrent agent session, and drives it through its run lifecycle until it reaches a terminal state, honoring concurrency caps, retries, and rate limits along the way. The polling, dispatch, and run lifecycle are covered in How it works.

Dashboards

Lorenz ships two operator views over the same runtime snapshot: an Ink terminal dashboard (TUI) and a web dashboard served by the observability API.

Terminal dashboard (TUI)

The flight board: every issue in the pipeline is one row in a single lane table, windowed around the cursor — a fleet of 100 concurrent agents fits any terminal.

Web dashboard

Documentation

The published documentation site is at ryanlyn.github.io/lorenz, built from docs/. Start here:

• Getting started - install, write a WORKFLOW.md, run your first issue.
• How it works - the polling, dispatch, and run lifecycle.
• Configuration reference - every front-matter key, default, and meaning.
• Trackers - Linear, Jira, Slack, Discord, local, and memory sources of issues.
• CLI - commands, flags, and run history.

Configuration

Configuration lives in the YAML front matter of a workflow file. The Markdown body below the front matter is the agent session prompt, rendered as Liquid with issue-context variables. See Workflows for the file format and a quickstart example.

Full Reference

Every front-matter key, its type, verified default, and meaning are in the Configuration reference. workspace.root supports ~ and whole-value $VAR expansion, and LORENZ_WORKSPACE_ROOT overrides it at runtime.

Linear

Linear is the default tracker: issues live in a Linear project, read access uses LINEAR_API_KEY, and project selection uses project_slug. Route labels such as Lorenz:backend let multiple instances share one project. Setup and configuration are in Linear tracker. Other sources (Jira, Slack, Discord, local, memory) are covered under Trackers.

Workflow Prompt

The prompt body reads public issue and run fields as Liquid variables, such as {{ issue.identifier }}, {{ issue.title }}, {{ issue.description }}, and {{ attempt }}. The complete variable list is in the Workflow prompt reference.

Skills

The skills/ directory holds orchestration skills (lorenz-commit, lorenz-push, lorenz-pull, lorenz-land, lorenz-debug) referenced by the example workflows. Lorenz installs skills into .lorenz/skills/ in each prepared workspace before the agent starts. See Skills for how agent.skills and tool-pack skills are resolved.

Observability

The terminal dashboard is a flight board: every issue in the pipeline (running, reserving, retrying, blocked) is one row in a single lane table under a fleet status bar with throughput, token, and rate-limit vitals, and any running agent can be narrowed into an interactive detail card. The web dashboard exposes the same runtime snapshot over a local HTTP server, started with --port or server.port. Routes, the WebSocket stream, and /mcp tool serving are documented in Observability.

Requirements

mise manages Node 24 and pnpm 9 from mise.toml:

mise trust
mise install
pnpm install

Run

Build, then run the CLI against a workflow file:

pnpm build
pnpm start -- WORKFLOW.md
pnpm start:once -- --dry-run --no-tui WORKFLOW.md

Workspace Layout

apps/cli is the composition root; packages/* is the provider-agnostic engine; extensions/* are the tracker backends; test/ holds workspace-level tests. The layering rules and the recipe for adding a tracker live in Architecture and the Source map.

Testing

mise run tidy
mise run check

mise run tidy formats and applies lint fixes. mise run check runs typecheck, build, tests, and lint. When running Vitest directly, rebuild first so tests exercise the current compiled packages.

Live Tests

Live tests are opt-in and launch real CLIs or services in isolated workspaces:

pnpm test:live:codex
pnpm test:live:linear-codex
pnpm test:live:claude
pnpm test:live:ssh

LORENZ_LIVE_SSH_WORKER_HOSTS is a comma-separated list of real SSH workers. When it is unset, the SSH live test can use disposable local workers if Docker, ssh-keygen, and Codex auth are available. LINEAR_API_KEY is required for Linear live tests, and LORENZ_TS_CLAUDE_ACP_BRIDGE_COMMAND enables the Claude live tests.

Packaging

pnpm build
pnpm --filter @lorenz/cli pack --dry-run

The CLI package includes the built binary. Workspace documentation, workflow fixtures, and test evidence stay at the workspace root.

Compatibility Contracts

The checked-in workflow files (WORKFLOW.md, WORKFLOW.local.md, and WORKFLOW.chat.md) are executable fixtures. pnpm test guards workflow docs, prompt rendering, dashboard snapshots, runtime behavior, and CLI documentation. Update the fixture and the matching test together when the public contract changes.

License

This project is licensed under the Apache License 2.0.