turnwright

Shape your code
at the lathe.

A coding agent for the terminal. The loop, tools, permissions, sessions, skills and compression all come from agentscope-go; turnwright wires them to one JSON-RPC seam and a TypeScript TUI.

watch it work ↓

darwin · linux — x64 / arm64 · windows via wsl2

turnwright session — highlight replay● working
❯ explain what this repo does
✶ Reading the layout: Go engine, TypeScript TUI, one JSON seam…
◆ turnwright is two halves: a Go engine assembled on agentscope-go,
↑0 ↓02.4s / 19.8s
01

Watch a real turn

A representative session in the real event vocabulary: streaming text, tool calls, an approval answered with y, a patch, a theme switch. Scrub it, chapter it, run it at 2×.

turnwright session — full replay● working
❯ explain what this repo does
✶ Reading the layout: Go engine, TypeScript TUI, one JSON seam…
↑0 ↓00.9s / 27.9s
02

Try it yourself

A faithful fake terminal — same commands, same warnings, same approval dialog. Nothing leaves your browser.

playground — try turnwright in your browserpermission accept_edits
❯ /help
• /help — list commands /model [name] — switch model /sessions — resume a saved session /theme [name] — switch theme /permission <mode> — set permission mode /status — show session status /vim — toggle vim keybindings /compact — compact context (pending upstream API) /clear — clear the conversation view /quit — exit
03

Two halves, one seam

The engine never renders; the TUI never decides. Everything crosses LCP — which is why the TUI is replaceable and the engine is testable without a terminal.

turnwright architecture A Go engine assembled on agentscope-go speaks LCP, a JSON-RPC 2.0 NDJSON protocol over stdio, to a replaceable TypeScript TUI. agentscope-go — agent loop · tools · permissions · sessions · skills · MCP · compression turnwright-engine Go · assembly layer serve (LCP) · -p (print) turnwright TUI TypeScript · OpenTUI + React replaceable client LCP JSON-RPC 2.0 · NDJSON · stdio approvals ⇄ approval/request agent/event · 1:1 forwarding
every capability crosses one seam — protocol reference · getting started
04

Spec sheet

Eight machined plates. Each one links into the documentation that proves it.

01 ±0 keys

Nine providers

anthropic to ollama — one credential env var each; defaults per provider, base-URL override for proxies.
02 y / n / a

Five permission modes

default, accept_edits, explore, bypass, dont_ask — from ask-everything to deny-everything-that-would-ask.
03 cwd → /

Skills & MCP

SKILL.md skills discovered from cwd to root; .mcp.json servers, stdio or http, failures skipped not fatal.
04 atomic writes

Sessions & resume

every turn checkpointed per project; /sessions picker, --continue newest, --resume exact id.
05 0 code changes

Theming & branding

theme overrides for colors, icons, motion; [brand] renames and repaints the whole product.
06 exit 0|1

Print mode / CI

-p one-shot turns as text or stream-json NDJSON; approvals auto-denied, exit codes you can gate on.
07 ≤ 64 KB

Vim & @file

normal/insert modes with real motions; @path attaches file contents, tab-completed, capped at 64KB.
08 v1

Replaceable client

the TUI is one LCP client among any: 13 methods, one NDJSON seam, versioned protocol.
05

Make it yours

Branding is data. Rename it, repaint it, ship your fork — the config below is the entire change.

turnwrightshape your code at the lathe
turnwright● readyclaude-sonnet-4-5⎇ mainaccept_edits
~/.turnwright/config.toml
[brand]
name    = "turnwright"
tagline = "shape your code at the lathe"
accent  = "#F59E0B"
theme   = "turnwright-dark"
06

Install

npm

npm i -g @turnwright/cli
turnwright

per-platform engine via optionalDependencies · bun ≥ 1.4 on PATH

source

go build -o turnwright-engine ./cmd/turnwright-engine
pnpm install && pnpm dev

Go 1.26+ (per go.mod) · Bun ≥ 1.4 · pnpm

credentials

export ANTHROPIC_API_KEY=…
# or --provider ollama, no key

seven provider env vars auto-detected · list

All documentation →