Lorenz docs

Lorenz is a control plane that turns tracker issues into coding-agent runs. It watches a tracker (Linear, Jira, a local board, Slack) for issues in active states, prepares an isolated workspace for each one, renders a prompt, and runs Codex or Claude over the Agent Client Protocol until the issue reaches a terminal state. Lorenz derives from OpenAI's Symphony.

Start here

Pick the path that matches what you came to do.

Operators and users running Lorenz against a tracker:

1. Getting started
2. How it works
3. Workflows
4. CLI
5. Trackers
6. Observability
7. Troubleshooting

Extension authors adding a tracker, tool pack, executor, or worker driver:

1. Architecture
2. Source map
3. Extensions
4. Tracker provider
5. Tool pack
6. Agent executor
7. Worker driver

Integrators and spec readers who need exact contracts:

1. Reference
2. Configuration
3. Workflow and prompt
4. CLI reference
5. HTTP API
6. Events
7. Tracker tools
8. Spec
9. Glossary

Evaluators deciding whether Lorenz fits:

1. How it works
2. Architecture
3. Security
4. Roadmap

The docs tree

Top level

• Getting started - fresh checkout to first run
• How it works - concept-first end-to-end walkthrough
• Architecture - layered package graph and extension axes
• Source map - which package owns which file
• CLI - the daemon, runs, and doctor
• Workflows - the WORKFLOW.md config and prompt
• Dispatch - eligibility, ordering, routing, caps, retries
• Workspace - per-issue directories, hooks, and cleanup
• Agent orchestrator - poll loop, state, reconciliation
• Observability - the dashboards and run views
• Security - trust boundary and isolation posture
• Troubleshooting - symptoms mapped to cause and fix

Trackers

• Overview - what a tracker provides to dispatch
• Linear - project selection, credentials, GraphQL tool
• Jira - Jira Cloud over REST or MCP
• Local board - a directory of Markdown issues
• Slack - mentions in channels as issues
• Discord - bot and managed-role mentions with native issue threads
• Memory - in-process fixture from an env var

Agents

• Overview - the agent kind and executor axes
• Codex - running Codex as the coding agent
• Claude - running Claude Code as the coding agent
• ACP bridges - the subprocess that runs a turn
• Skills - reusable playbooks overlaid into the workspace

Workers

• Overview - host, SSH fleet, or warm pool
• Static SSH - sharding runs across fixed hosts
• Worker pool - provisioned, leased, reaped machines
• Docker - disposable local containers as workers

Features

• Overview - capabilities you turn on in WORKFLOW.md
• Context ensembles - parallel attempts at one issue
• Dispatch routing - sharding work with route labels
• Run history - the lorenz runs post-mortem record
• Secret resolution - keeping credentials out of config
• Workflow hot reload - tuning config without a restart

Extensions

• Overview - the four contracts and the registry pattern
• Tracker provider - recipe for a new tracker backend
• Tool pack - recipe for agent-facing tools
• Agent executor - recipe for how an agent runs
• Worker driver - recipe for provisioning workers
• Out of tree - loading a driver without forking

Reference

• Overview - the code-accurate contracts index
• Configuration - every WORKFLOW.md front-matter key
• Workflow and prompt - the Liquid prompt contract
• CLI - every command, flag, and exit code
• HTTP API - routes, WebSocket, and MCP mount
• Events - every event name and when it fires
• Tracker tools - the agent tool surface and query DSL
• Spec - implementation-neutral contract for the service
• Glossary - the vocabulary defined once

Roadmap

• Roadmap - what is unwired, reserved, or future work

Notes

Diagrams render as inline SVG embedded in each page; no external image service or rendering step is involved. The repository README.md is a short overview; this section is the full documentation.