User guide

User guide#

Learn how to install Twine, run your first workflow, and work with coding agents in your folders.

Install#

Twine requires macOS 26+ on Apple Silicon.

Install it with Homebrew:

brew install --cask standing-desks/tap/twine-ade

Then open Twine from Applications.

To install manually instead, download the .dmg from the latest release, open it, and drag Twine onto the Applications folder in the disk image. Wait for the copy to finish, eject the Twine disk image in Finder, and open Twine from Applications.

Releases are Developer ID signed and notarized. The license is included inside the installed app bundle.

To update a Homebrew install, quit Twine and run brew update && brew upgrade --cask standing-desks/tap/twine-ade. To update a manual install, quit Twine, open the new DMG, and drag Twine into Applications, choosing Replace when Finder asks. Your saved work and settings are retained.

Run your first workflow#

Open Twine and choose Open Folder… (⌘O) to select the folder you want to work in.
Create a session to keep the workflows for your task together.
Add a workflow in a new tab (⌘T). Choose Terminal for a shell, or Single agent to work with a coding agent. For an agent workflow, install and authenticate its harness separately, then select it in Twine's launch form.
Start the workflow and enter your command or task in its terminal.

You can return to the session later to review its output or continue working. The sections below explain how to use more workflows and organize your work.

Folder windows#

Open Folder… (⌘O) reuses an empty window or opens another window when a folder is already open. New Window (⌘N) opens a start page. Opening a folder that is already open focuses its existing window, including when opened through a symlink.

Each window has independent sessions, terminals, file tabs, and navigation. Menu commands act on the focused window. Settings, recent folders, and custom workflow types are shared. Closing a window stops only its folder's processes; Close Folder returns that window to the start page. Quitting stops every window's processes and restores all open folders on the next launch. Unavailable folders show an explanation and can be closed without reopening them next time.

Use View → Zoom In (⌘+), Zoom Out (⌘−), and Actual Size (⌘0) to scale the interface from 50% to 200%. Zoom applies to every window, including terminals, editors, previews, and dialogs, and is remembered between launches.

Files#

The sidebar starts open. Toggle it with the toolbar button or ⌃⌘S to browse the folder or make more room for terminals. Expanding a directory loads only its children; empty directories remain visible. Twine refreshes expanded directories and the selected file when they change, including changes made by shells and agents.

Files also shows Git status for each repository’s primary checkout, including repositories inside a non-Git folder. Repository roots use the same folder icon and change dot as other directories. Badges mark modified (M), added (A), deleted (D), renamed (R), copied (C), type-changed (T), untracked (?), and conflicted (!) paths. Filled badges indicate staged changes; a file can have both staged and unstaged badges. Click a badge for details. Deleted tracked paths remain visible with a strikethrough; folders with changed descendants have a dot.

Git status refreshes automatically and is read-only. A clean checkout can still have commits ahead of its upstream. Additional linked worktrees are not included yet. Discovery skips Git internals and common dependency/build directories; if discovery reaches a limit, open a smaller folder to inspect the remaining repositories.

Select a file to make small edits to UTF-8 text up to 2 MiB. Use ⌘Z to undo, ⇧⌘Z to redo, and ⌘L to go to a line. Edits save automatically after a short typing pause, including in background tabs. You can keep typing during saves or press ⌘S to save immediately, even with autosave disabled or a longer delay. Configure autosave in Settings. Unsaved changes show “Edited” in the header. Settings still require an explicit Save. Before saving, Twine checks whether the file on disk has changed. If it has, choose Reload to discard your edits or Overwrite to save them; Cancel keeps the edits without changing the file. Autosave pauses after a conflict or save failure. Use File → Save or ⌘S to retry; successful saving or reloading resumes autosave. Disk updates refresh clean files and never replace unsaved edits. ⌘W closes the file and returns to the workflow. Binary files, larger files, deleted paths, symbolic links, and special files show an explanatory state. Up to 256 directories can be expanded at once.

The native editor automatically highlights HTML, CSS, Swift, Rust, Python, C, C++, C#, Go, Java, Ruby, JSON, JavaScript/JSX, TypeScript/TSX, TOML, YAML, and shell files. HTML and Markdown files open in Preview; switch to Source to edit with highlighting. Markdown previews follow local links. It detects languages from filenames and script shebangs. Use the language menu in the file header to choose a language, restore Automatic detection, or select Plain Text. The choice stays with that open file tab and never changes the saved text. Colors update as you type and follow the system appearance. Unknown languages and files that exceed the highlighting work budget remain editable as plain text. Shell highlighting uses the Bash grammar; embedded languages in HTML <script>/<style> blocks, strings, or Markdown code fences are not highlighted separately.

Memories#

Choose Memories at the bottom of the sidebar to inspect local Codex and Claude Code memory. It expands below compact Files and Sessions headers; clicking Memories again collapses its navigation while leaving the reader open. Click Files or Sessions to restore the normal sidebar lists.

Switch between This workspace, Global, and Other workspaces. Each location remembers its selected source, search, harness and kind filters, and source-list position, including after relaunch. Other workspaces has a store picker for memories from other checkouts or stores that cannot be associated with the open folder. Rows identify their harness and, for other workspaces, their store. Search filenames and paths, filter by harness or kind, and use the refresh arrow to rescan disk. The reader's info button shows the full path, provenance, type, and modification date.

Markdown opens rendered, with headings, lists, tables, and links. Switch to Markdown to inspect the original text, including any frontmatter. Choose Edit to open a local Markdown file in Twine's editor. Memory edits follow the same autosave setting and delay as other file edits. Use File → Save or ⌘S to save immediately, or to save manually when autosave is disabled. If the harness changes the file, Twine offers Reload or Overwrite before replacing it. Unsaved edits remain in their file tab when you return to Memories.

SQLite records, settings summaries, and other non-Markdown sources remain read-only. The viewer includes generated memory, instructions, rules, agent memory, skills, and extension resources. A file existing on disk does not prove that a running harness has loaded it. Folder-associated files can live outside the opened folder. Rendered memories do not load remote images or scripts; clicking an external link opens your browser.

Memory viewing uses local files without starting a harness or requesting cloud memory. Known synchronized Claude mirrors are excluded. Missing, unreadable, binary, or oversized sources show an explanation. Text reads are limited to 2 MiB; discovery is bounded to 1,024 sources and directory entries, 32 databases, and 256 recent extraction records per database. Memory trees are scanned eight levels deep and folder instructions six levels deep. The checked-locations menu shows discovery diagnostics. Return to workflows by clicking the Sessions header.

Agent workflows#

Choose Adversarial, Coordinator, or a saved workflow from a new tab. Pick a harness for each agent, and optionally its model and effort level, then start it. Supported harnesses are Codex, Claude Code, pi, Antigravity (agy), OMP (omp), and OpenCode (opencode), installed on your shell's PATH. Choose a model and effort level from the options shown in the launch form. Claude Code also accepts a model name you type yourself. Where available, YOLO lets the harness run without asking for permission before each action. Pi does not ask for permission, so it has no YOLO option. Built-in workflows wait for a task in the first agent's terminal. Instructions use the harness instruction channel. Setup does not start agent work. Work moves through the graph's links. Harnesses run directly in the open folder. Each agent has a terminal subtab. Review rounds reuse the agent's live harness conversation when it remains available. After an agent completes its work, its terminal stays interactive. After a workflow completes or reaches its review limit, give a start agent another task to start a new cycle with the same conversations and trace history. Older stage workflows also have Individual mode for separate follow-up conversations. Restored workflows resume recorded harness conversations when all unfinished active agents have compatible session handles.

Click the + button to open a new tab. The workflow chooser has two grids: Built-in and Your workflows. Choose Create your own to open the native graph editor in that tab. Add agents and enter their instructions. Drag agents to move them. Drag between an output circle and an input circle to connect agents. You can start at either end. Ports of the same type cannot connect. You can also click the circles. Click an agent or link to change its settings. The editor has compact cards on a dotted canvas. Use Fit to see the full graph. The name and description fields are above the canvas. A valid receiving card lights up as you drag a connection. You can also use Connect to… under Actions in agent settings or in a card's context menu. Settings keep your draft edits when you click outside them. The Agent view contains the name, color, and instructions. Choose a color to tint the card and its outgoing links. Incoming work settings appear when an agent has multiple input links. Use When work ends to send a result or make a review decision. Right-click an agent and choose Duplicate agent to add another agent with the same settings. Switch to Launch defaults to set optional harness, model, effort, and permission choices. These choices fill the launch form. You can change them before starting. Right-click empty canvas space for workflow settings and the activation limit under Advanced. Double-click empty canvas space to add an agent at that point.

Each graph node is an agent. Agents with no forward input links start the workflow. If there are multiple start agents, they receive the same task and can work at the same time. A Work complete link sends a complete result. An Item ready link sends one piece while the source keeps working. A busy receiver queues new pieces. Use Start as work arrives to process items one at a time, or Wait for every incoming link to wait for one result from each input. Use Approved and Changes requested links for review. Add another event in a link's popover to send both pieces and a final result between the same agents.

Agents with no forward output links return the final results. Feedback links do not change which agents start or return results. Workflow settings offer Wait for all results, Choose a result, and Compare times. Each option waits for active work to stop. Choose keeps all outputs and lets you select one. Compare times shows the time from task delivery to explicit completion for each final agent. A bounded activation limit stops repeated feedback loops. A graph can use up to five agents and 64 links.

Enter a name and use Save or ⌘S. Use ⌘Z to undo edits. The editor enables Save when the current graph is valid. From a launch form, Edit Workflow opens the editor in the same tab. Changes to a built-in save as a user workflow.

Adversarial and Coordinator ship as TOML files and use the same agent graph format as user workflows. Adversarial connects an Implementer to a Reviewer. The Reviewer can approve the result or send feedback. Coordinator connects a Planner to Worker 1 and Worker 2. Both workers receive the plan and work on their named parts. Their results go to a Coordinator, which waits for both and checks the combined work. The default files are included in Twine.app/Contents/Resources/workflows.

Start a graph, then enter the task in the first agent's terminal. Use Results to read all final outputs, select a result, or compare times.

Twine saves user types as versioned TOML files in $XDG_CONFIG_HOME/twine/workflows. The default path is ~/.config/twine/workflows. Copy a .toml file to this directory to share or import a type. You can rename the file and keep it in version control. Keep its id when you move or share it. Use Create your own or edit a built-in to create a separate identity. The chooser refreshes after file changes. Invalid files are skipped. A save conflict preserves external edits. Reopen the type to load those edits before you save again.

New graph files contain schema_version = 2, an id, a version, and a definition. The definition has roles and a graph. Each graph edge has a stable id, from, to, and event. Events are done, piece_ready, feedback, and approved. Endpoints use role IDs. Version 1 files with task and finish endpoints remain readable. Receive rules are any or all; Finish is all, choose, or timed. Saved versions stay in .history. Existing SQLite types export once; a deleted exported file stays deleted. Started workflows keep their complete original definition. Older ordered stage definitions remain readable. The editor converts them to graphs before saving. New saves must use graphs.

Agents send work through their links when they explicitly report completion. Terminal text and process exits do not advance a workflow.

Mark done… is always available for an unfinished active role, including after its process exits. Its form also supports review decisions and worker assignments. Review loops stop at the type's limit; Cancel workflow stops all its agents. Runs restored after quitting or a crash resume their unfinished active agents when every one has a recorded harness session. Otherwise they remain interrupted with their saved output. The Traces panel shows each role's stage invocations on compact agent tracks in shared start order, with equal spacing regardless of pauses. Select a step to focus a seven-step window and inspect its stage changes, completions, and handoffs; this history survives reopening the app.

Traces opens in Overview, with steps in start order. Switch to In Depth to inspect the selected step on a timeline of elapsed time: tool calls, parallel subagents, and previews of their inputs and outputs. Search the activity, show only failures, and jump from an activity to its recorded output.

Claude Code, Codex, pi, and OMP can show prompts, tool calls, and responses in Traces. Select a step to jump to its recorded terminal output. Antigravity and OpenCode show workflow activity but do not record individual prompts or tool calls, so In Depth has no detailed activity for them. If detailed tracing is unavailable, you can still use the agent's terminal and review its saved output. Twine leaves your harness configuration files unchanged.

Configuration#

Twine reads $XDG_CONFIG_HOME/twine/config.toml at startup, falling back to ~/.config/twine/config.toml when XDG_CONFIG_HOME is unset, empty, or relative. It creates a small starter config and themes/twine_dark.toml and themes/twine_light.toml beside it on first launch. Existing files are never overwritten. When upgrading from Silica, customized default palettes are copied into the new default files once; untouched palettes adopt the Twine colors. Silica remains available through themes/silica_dark.toml and themes/silica_light.toml imports.

Choose Twine → Settings… or press ⌘, to edit the config file in a popup attached to the current window. Save with ⌘S or File → Save. Valid settings apply immediately to every open folder; invalid settings keep the previous file and active settings. Unsaved edits are protected when closing the window or quitting, and external file changes prompt you to reload or overwrite.

[appearance]
color_scheme = "system" # "system", "light", or "dark"

[terminal]
font_family = ""
font_size = 13.0

[editor]
autosave = true
autosave_delay_ms = 500

File edits autosave by default after a 500 millisecond typing pause. Set editor.autosave = false to save manually, or change editor.autosave_delay_ms to a positive whole number of milliseconds (for example, 2000 for two seconds). Saving Settings applies these changes immediately to every open file tab. ⌘S always saves immediately, including when autosave is disabled. Settings, workflow designs, and session forms use explicit saving through File → Save or ⌘S; session names also accept Return.

Terminal settings apply to live shell and agent terminals, including Bento panes, and terminal history. When font_family is omitted or empty, Twine uses its private bundled Hack Nerd Font at 13 points by default, including bold and italic faces. The bundled font is available only inside Twine; it is not installed into Font Book or exposed as a selectable family. To choose a custom font, install it in macOS and set its family name (for example, font_family = "JetBrains Mono"). Custom names resolve only to installed fonts, including a separately installed copy of Hack Nerd Font. Twine checks that i and w have equal character widths, allowing Nerd Fonts whose icons are wider. An unavailable font or one that fails this check falls back to system monospace with a warning. font_size defaults to 13 points and accepts sizes from 6 through 72, including fractional sizes such as 13.5. appearance.color_scheme selects system, light, or dark appearance for all app windows.

Select a different palette for each appearance with an optional [theme] table:

[theme]
light = "twine_light"
dark = "twine_dark"

Names omit the .toml extension and resolve to themes/<name>.toml beside the main config file. Either key can be omitted to keep its default. Spaces in filenames are supported; use a filename basename rather than a path. For example, choose light = "catppuccin_latte" and dark = "catppuccin_mocha", or select silica_light and silica_dark to restore Silica.

Selected theme files supply terminal colors for that appearance only; other settings in those files apply only when loaded through a global import. A theme can import another color file. Missing or invalid selected files produce configuration diagnostics and use the complete defaults. Unselected theme files are left alone. The starter config includes only appearance, font, and theme choices; use this guide for additional options.

A top-level import loads one or more complete TOML configuration files. Put it before any table headers in config.toml:

import = ["themes/twine_dark.toml", "fonts.toml"]

[terminal]
font_size = 14.0

[terminal.colors]
# Settings here override the imported files.
background = "#101820"
foreground = "#e5e1cf"
cursor = "#8fbe5c"
selection = "#34495e"

A single file can also use import = "themes/twine_dark.toml". Files merge in the order listed: later imports override earlier imports, then the importing file overrides them all. Tables merge recursively, so overriding terminal.font_size preserves an imported terminal.font_family. Individual terminal colors merge by name. Global imported colors override the selected palettes in both appearances, and inline [terminal.colors] values override those imports. Defaults fill omitted settings after merging. Imported files can contain any supported settings, including appearance and terminal fonts.

Imports accept absolute paths, ~/ paths, and paths relative to the file containing the import. Imported files can have their own top-level imports. Cycles are rejected, including cycles through symlinks; each import tree is limited to 64 levels and 256 documents. Invalid imported settings cause the complete config to fall back to defaults even if a later file overrides that setting. Diagnostics identify the original file, line, and key. Missing imported files are reported and never created.

Terminal colors normally come from themes/twine_dark.toml in dark mode and themes/twine_light.toml in light mode, unless a [theme] selector chooses another file. Those files use the same config tables, so they can also be imported directly. A full palette import applies the same colors in both appearances. Partial imports and local overrides replace only supplied colors; omitted colors retain the corresponding default theme values.

For example, the default dark theme contains:

[terminal.colors]
background = "#262626"
foreground = "#faf1f3"
cursor = "#007aff"
selection = "#3f638b"
black = "#1c1c1c"
red = "#ff8d7a"
green = "#00d9b2"
yellow = "#eba800"
blue = "#5b98e6"
magenta = "#ff82b3"
cyan = "#00cafa"
white = "#faf1f3"
brblack = "#abb3cd"
brred = "#ffaea0"
brgreen = "#00df75"
bryellow = "#ffd166"
brblue = "#82b7ff"
brmagenta = "#d896fe"
brcyan = "#62e3ff"
brwhite = "#ffffff"

Colors must be #RRGGBB strings. Set ANSI colors individually with black, red, green, yellow, blue, magenta, cyan, and white. Bright variants use the br prefix: brblack through brwhite. Legacy ansi arrays remain readable; named colors override their corresponding slots. The same tables and keys work in config.toml and all imported files. Saving settings in Twine updates shell and agent terminals, Bento panes, saved output, and minimaps.

Omitted settings use defaults. Invalid TOML, invalid values, or file errors (including theme files) use the complete defaults; unknown keys are ignored with a warning. Diagnostics include the file, line, and key (or <document> when a syntax error has no identifiable key). They appear in macOS Console under the com.twineproject.Twine subsystem, without logging config values.

Terminal panes#

Use the two buttons at the top right, ⌘D to split right, or ⇧⌘D to split down. Each split starts a shell in the same folder; run any command or coding agent there. Up to four panes share the same Bento styling and draggable dividers as agent workflows. ⌘[ and ⌘] move keyboard focus. Each pane has a close button; ⌘W closes the focused pane, and closing the tab closes its panes. Pane layouts survive reopening. The Traces panel combines all panes in a tab into one set of tracks, and selecting an event focuses its owning pane.

Paste a clipboard screenshot with ⌘V, or drop images and files onto any terminal or agent pane. Clipboard images become private PNG files in the temporary directory; Twine inserts their quoted paths so the shell or harness can read them. File drops use their original paths. How much output remains in live scrollback depends on the harness's terminal display mode.

Terminal transcripts#

Every terminal and agent pane has a compact minimap at its right edge. Hover or focus the 14-point rail to expand it over the output; expansion does not change the terminal's columns. Click or drag the visible-region indicator to scroll. With the rail focused, use the arrow, Page Up/Down, Home, and End keys. Return to live resumes following the latest output. Each Bento pane keeps its own position.

Minimap points use the same step IDs, numbers, role colors, and selection as Traces. Selecting a point opens that step in Traces and scrolls the live terminal to its recorded position. Points are placed by terminal row; the Traces panel spaces steps by start order. Loading Older traces adds those steps to the map when their output is still available. Output without an available anchor remains scrollable without a guessed point. Historical output also has its own minimap.

Twine saves terminal output under ~/Library/Application Support/Twine/transcripts/. Terminal IDs remain unique across launches. Closing a terminal preserves output already accepted for recording. Reopening a folder restores recorded output and scrollback. Shells append a fresh prompt. Single agents resume their exact recorded harness session, retaining earlier output. Codex and Claude Code use session IDs; pi and OMP use session files. Antigravity and OpenCode support exact-ID resume but don't expose launch observers, so use Resume Session… to supply the conversation/session ID once. The same action is available for older tabs without a captured session. Twine never guesses the latest conversation. Cancelled or failed agents remain stopped. Saved output opens earlier invocations, including an idle shell with no trace step. Live views and ANSI replay retain up to 100,000 rows in memory; the raw transcript limits below apply independently. New workflows appear in Traces once their terminals are active.

Saved output is capped at 64 MiB per terminal and 512 MiB across all terminals. Older output expires when storage or metadata limits are reached. Expired output remains unavailable after reopening Twine.

Click an anchored event in trace details to select its workflow and agent and scroll the mounted terminal to that point. Return to live scrolls back to the latest output. If a point belongs to an earlier invocation or has left scrollback, Twine opens a read-only snapshot of the saved output instead. A restored workflow's Saved output menu opens earlier invocations. Saved output replays cursor movement and recorded terminal sizes; resizing the window only changes its viewport. It displays text without terminal colors or images. Events without an anchor keep their details without a jump action.

Saved output needs the earlier terminal output and its recorded sizes to display correctly. If either has expired, Twine shows Output no longer available.