Turn

Adaptive development, made visible.
Turn turns an outcome into an inspectable workgraph, then helps you execute it one deliberate step at a time.

Why Turn · Product surface · Screenshots · Run locally · Verification

Why Turn

Most agent workflows begin with a prompt and quickly become a stream of opaque tool calls. Turn keeps the plan, execution, and evidence in one visible control surface:

• Start with intent. Describe the outcome instead of manually inventing a task list.
• See the decomposition. Turn renders containment, sequencing, fan-out, fan-in, and integration points as a workgraph.
• Run with control. Choose step-by-step or auto-run execution, pause between stages, retry failures, and provide human input when needed.
• Inspect the work. Open the document view, terminal, logs, artifacts, costs, and durable agent sessions from the same project.
• Keep ownership local. Project state lives on disk, while planner and worker adapters keep harness-specific behavior replaceable.

Turn is designed for complex software, games, books, and other outcomes where the path matters as much as the final artifact.

Product surface

Surface	What it gives you
Project authoring	Prompt-first creation, project explorer, attachments, and working-directory selection
Workgraph	A deterministic left-to-right graph with explicit sequencing, fan-out, and fan-in
Execution	Auto/step policies, retries, timeouts, cancellation, recovery, and human-input gates
Organizations	Durable charters, independent plan audits, recursive manager review, and replan boundaries
Units of work	Priority-ordered tickets with acceptance criteria, dependencies, evidence, and typed handoffs
Capacity	Project/global parallel limits, run/token/cost budgets, and optional isolated Git worktrees
Agent workspace	Durable PTY-backed terminals, reconnectable sessions, and provider-neutral transport
Evidence	Document view, logs, artifacts, diffs, token/cost usage, and server-projected UI state
Harnesses	Codex, Claude Code, OpenCode, and Pi adapters with local availability detection

The process-level Mock harness and heuristic planning are test-only fixtures. For a repeatable local workflow laboratory, set TURN_TEST_MODE=1, choose TURN_PLANNER=mock and TURN_DEFAULT_EXECUTOR=mock, and add TURN_MOCK_WORKFLOWS=1; the server then seeds the rejection, expansion, rerun, failure, input, and cancellation projects once in the configured data directory. The Mock provider is not advertised or accepted by production runtime configuration. The seeded lab includes the rejection, expansion, rerun, failure, input, cancellation, and schedule scenarios; the trigger loop E2E also exercises a manually started loop with configured event data.

Current scope

Turn currently provides a local-first workgraph for planning, running, and inspecting agent work. The shipped surface includes explicit step/auto execution, durable project state, reconnectable terminals, artifact and usage inspection, verifier decisions, and provider-specific harness adapters for Codex, Claude Code, OpenCode, and Pi.

Future-ready seams

The storage, graph, runner, terminal, and harness boundaries are independent so new providers, scheduling policies, and evidence types can be added without making the UI own orchestration state. The graph also models derived flow edges, such as review rejection returns, separately from the durable workflow topology.

For a broad objective, the root is a persistent organization boundary rather than a one-shot checklist. Its charter records the desired outcome, deliverables, acceptance criteria, constraints, quality and decomposition policy, and budget. The runtime audits each proposed composition before applying it, materializes work items and handoffs, schedules only within capacity, and reviews settled frontiers through:

PLAN → EXECUTE FRONTIER → OBSERVE → REVIEW → REPLAN → … → ACCEPT CHARTER

The Store owns this state on disk; OrganizationManager owns the review decision; Scheduler owns reservation and budget enforcement; and the REST/CLI surfaces expose the same records for humans and agents.

Screenshots

The screenshots below show the authoring surface, harness selection, graph and terminal inspection, document view, and workspace preferences.

Architecture

The graph is the source of truth. PlanResult and WorkerResult are strict domain contracts; the runner owns transitions; the store owns durable local project files; the UI and CLI are clients.

prompt
  │
  ▼
planner ──▶ PlanResult ──▶ workgraph ──▶ runner ──▶ harness adapter
                                      │              ├─ Codex
                                      │              ├─ Claude Code
                                      │              ├─ OpenCode
                                      │              └─ Pi
                                      ▼
                              logs · artifacts · diffs · usage

For broad requests, a plan can carry an executive summary, approach, typed sections, decisions, risks, acceptance criteria, and optional diagrams. The document view renders that metadata as a live project document: nested work is collapsible, workflow source graphs remain explorable through links, and generated Markdown, text, and image artifacts open from the same reader. It refreshes from the current graph as agents append or replace work, and worker nodes receive the same graph-owned context.

The main boundaries are deliberately small:

• turn/domain/ — schemas, state transitions, and UI-state projection
• turn/db/ — local project-file persistence
• turn/graph/ — pure graph evaluation
• turn/runner/ — scheduling, recovery, events, and terminal lifecycle
• turn/workers/ — planner, worker, and harness adapters
• turn/server/ — REST, SSE, security, and static UI boundary
• ui/ — strict TypeScript client and interaction state

Run locally

Prerequisites

• Python 3.11+
• Node.js and npm
• A running Herdr daemon for project terminals
• At least one supported coding harness installed locally for real runs

Herdr is an external, user-owned daemon. Turn connects to it through the herdr client CLI and never starts, stops, or restarts the daemon. Verify the existing service with herdr status server before starting Turn; do not run herdr server as part of the Turn launch procedure.

CAUTION FOR AI OPERATORS: HERDR CANNOT BE LAUNCHED INSIDE SUBPROCESSES OR FROM HERDR ITSELF. DO NOT TRY TO LAUNCH HERDR. REQUEST/USE THE ALREADY-RUNNING HERDR DAEMON. If it is unavailable, Turn fails visibly and stops; it does not launch, restart, or replace Herdr.

Install and start

python -m pip install -e ".[dev]"
npm install
npm run build
./scripts/run.sh         # start Turn at http://127.0.0.1:8000

Turn uses the repo-local projects/ directory by default. Override it when needed:

TURN_PROJECTS_DIR=/path/to/projects ./scripts/run.sh

Open http://127.0.0.1:8000, describe an outcome, choose an installed harness, and create the workgraph. Step mode is the safe default; execution is always an explicit product action.

Headless CLI

turn doctor
turn create "Build an adaptive narrative engine" --harness codex --run
turn projects
turn graph PROJECT_UUID --tree
turn run PROJECT_UUID
turn organization show PROJECT_UUID
turn work list PROJECT_UUID
turn work claim WORK_ITEM_UUID --node-id NODE_UUID
turn work update WORK_ITEM_UUID --status COMPLETE --evidence-ref tests/report.json
turn logs PROJECT_UUID                 # stitched JSONL event history
turn logs PROJECT_UUID --search error  # free-text search
turn logs PROJECT_UUID --follow         # JSONL live feed; pipe to jq or another reader
turn serve --port 8000
turn trigger emit EVENT_NAME --project-id PROJECT_UUID --data '{"key":"value"}'

When run from a project directory, turn create uses that current directory as the project directory. The UI/server uses TURN_PROJECTS_DIR for its default project root.

To activate an event trigger, keep the Turn server running and emit its exact event name with an optional JSON object. From a project directory, --project-id may be omitted; otherwise provide the target project UUID. The matching node receives the complete object in its trigger context:

turn trigger emit goal.plan.requested \
  --project-id PROJECT_UUID \
  --data '{"goal":"Plan a small product launch"}'

Use turn logs PROJECT_UUID --search trigger to inspect event and activation records after emission.

Schedule triggers use classic five-field UTC cron only, for example */5 * * * *; interval forms such as @every 5m are not supported. Schedules do not use a manually configured event name; their configured JSON data is merged with the schedule event's runtime data.

Workspace configuration is stored in ./.turn/config.json. Project state and operational history are stored inside each project at ./projects/<project_name>/.turn/; logs are rotated JSONL files in that project's .turn/logs/ directory. Each file is project-scoped and named with the project id and UTC timestamp; the server and CLI stitch those files in order. Configure rotation with TURN_LOG_MAX_RECORDS or the Workspace settings panel. Records include graph transitions, state/configuration changes, agent CLI responses, harness launch and return details, decisions, and errors, so external JSONL tooling can read the same stream as Turn.

Verification

npm run typecheck
npm test
npm run build
python -m pytest -q

The process-level Mock workflow laboratory is covered by the mandatory turn/tests/test_mock_workflows_e2e.py end-to-end test, which launches the repository-owned harness process and drives those scenarios through the API, terminal transport, retained sessions, persisted graph, runs, and artifacts.

The test suite covers:

• domain schemas, transitions, graph invariants, and storage
• REST, SSE, security, and project lifecycle behavior
• harness capability detection and adapter contracts
• PTY ANSI/input/resize/stall behavior
• browser authoring, graph inspection, terminal transport, themes, and responsive layouts
• deterministic full-run persistence for software, story, and book-shaped workflows
• installed-Herdr integration, durable panes, and cleanup boundaries

Model-backed demonstrations prove installed-harness integration; they are kept separate from deterministic quality scores.

Project layout

turn/core.py                 headless application facade
turn/domain/                 schemas and pure UI-state projection
turn/db/                     local project-file persistence
turn/graph/                  pure graph evaluation
turn/runner/                 scheduling, transitions, recovery, events
turn/workers/                planner and harness adapters
turn/server/                 REST, SSE, and static UI boundary
turn/tests/                  unit, integration, API, and browser tests
ui/                          dependency-free IDE shell and UI reducer
docs/assets/                 product screenshots and social/GitHub banner

Design constraint

The store never guesses planner intent. It validates keys, references, and graph acyclicity, then preserves valid objectives and topology exactly—without hidden child caps, semantic deduplication, title truncation, or domain-specific nodes.

The visual and interaction contract lives in DESIGN.md. This README is the product, architecture, scope, operation, and verification guide.

Roadmap

• Basic workflow
• Skills
• Nested planners
• Org agent
• MCP basic
• Arbitrary node reject
• Architecture / Hygiene & Cleanups
• Skills / MCP via Capabilities / Agent Plugins 1.0
• Live Logs / State & Graph Transitions
• Composable graph
• Triggers
• Run Quality Dashboard / Metrics
• Organization contracts / independent plan audit
• Persistent organization review loop
• Tickets / units of work / typed handoffs
• Concurrency and run/token/cost budgets
• Worktree isolation and explicit merge boundary
• Organization-fitness metrics
• Worktrees
• Multi-graph projects
• Variables / General data passing between nodes
• Repeatable organizations - Skipped / Locked nodes that can be re-run with new data
• Decision-based Routing for nodes
• Retries / Recoveries / Timeouts / Exit codes / Better process management for Running Processes
• Loops / Goals / Hill-climbing with visual feedback and metrics
• Capability library with Web UI
• Architecture / Hygiene & Cleanups
• Native app
• Terminal UI
• Better Styling / Document view
• In-host multiplexer
• Tmux
• Ghostty Web
• Security / Sandboxes / Permission boundaries
• Website / Demos - Capabilities, MCPs, and Skills
• Architecture / Hygiene & Cleanups
• Plugins / Extensions / Hooks
• Product/domain eval packs
• Phoenix integration