What Tau core is

Tau core is Pi in a window, plus threads. This document is the list. Anything not on it is an extension, and safe mode (npm run start:safe) must show exactly this list and nothing more.

In core#

Transcript

• user, assistant and notice messages, streamed
• how much of a turn's work is shown: transcriptDetail, one of focused, detailed and everything. focused reads a settled turn as prose — one "Worked for 2m 14s" row that opens in place, one self-replacing line while it runs, and a sentence per run of tools ("Read 3 files and ran 2 commands"); detailed stops folding, opens every group and shows thinking open; everything adds full tool output, arguments and timestamps. The default is a preference (Settings → General); the palette sets it, ⇧⌘T cycles it, and a level set from the palette belongs to the thread on screen until another thread takes the override. showThinking migrated to detailed
• thinking as one "Thought" row before the answer ("Thinking…" while it streams), folded in focused and open from detailed upwards; the transcript keeps the reader's toggle when the row scrolls out and back
• tool calls with live output, elapsed time and stop; presentation of a tool is an extension concern, its existence is not, and so is which rows fold: a failure never folds, and a batch a tool card claims (registerToolCard) is never folded, grouped or hidden. A runtime that keeps no journal Tau reads gets its cards back after a restart when its backend offers activityHistory (src/main/turn-activity-store.ts is the store it may use)
• Pi extension dialogs: select, confirm, input, editor; notifications. A question that takes typed text takes the files waiting in the composer with its answer; the host names them by path in the answer (src/main/answer-attachments.ts)
• bounded history paging
• a thread whose runtime does not start still opens: when a backend's open fails (its CLI is missing, say), the thread opens read-only from what its provider keeps (src/main/unavailable-thread-backend.ts), its index entry carries runtimeError, and a banner above the transcript says why, with Try again (the next switch tries the runtime again) and Providers
• a failed turn says so where it happened: the host keeps why a thread's last turn failed (turnError on its index entry, from Pi's error stop or a backend's turn-settled error) until the next prompt; the transcript ends with that error line and the rail row reads "Failed", beside the toast

What a turn's rows are is derived, not decided in a component: src/workbench/transcript-folding.ts turns one turn's tool records into fold, live, group and card rows and holds every rule about them — the fold's label and duration, the trailing-tool exemption, the action classes a summary counts, the tense the live line speaks in. WorkRows.tsx draws those rows and owns only what a reader toggled.

Composer

• text, images, queued steering and follow-up messages, abort. A message sent during a run waits at the end of the transcript as a dashed bubble (QueuedMessages.tsx): the arrow sends it now, the X returns it to the composer, Stop returns the whole queue, thread.steerQueuedMessage sends the oldest. The host keeps the queue (src/main/queued-messages.ts, <userData>/queued-messages.json) and sends its head when the thread settles, so it outlives the window and a restart; a queue restored on start, stopped or stopped by a limit is held until the user sends from it, and one of a thread the restart continues follows that continuation
• a turn a provider's usage or rate limit stopped (src/main/provider-limits.ts reads the message; a runtime may name the limit and its reset itself) leaves the thread Limited instead of Failed: the rail badge and the end of the transcript say when the limit resets, "Resume at reset" continues it then by itself (src/main/thread-limits.ts, kept in <userData>/thread-limits.json), "Resume now" continues it at once, and its queue waits meanwhile
• the interaction mode a thread's turns run in: default or one its runtime offers (plan), a capability of the backend (mode) like the thinking level; the catalog carries mode and modes, set-mode changes it, a draft keeps the one its thread starts in. What a mode means and how it is shown are kits' (Plan Kit)
• Edit from here under a prompt of the user's, where the runtime keeps a tree: the conversation goes back to before it and the prompt returns to the composer
• which chord sends: sendShortcut, one of ↵, ⌘↵ once the draft has several lines, and ⌘↵, a preference of this client (Settings → General → Send with). It is core because safe mode has to be able to send; what the send chord does while a turn runs (queue or steer) is a prompt hook's answer (streamingDelivery), queueing when nobody answers
• the slot inside the input frame that extensions fill with typed context (registerComposerInline), and file attachments beside images for a runtime whose adapter declares them
• chips inside the text (ComposerChipLayer.tsx, a chunk of its own loaded after the textarea is up, with composer-chips.ts and useComposerChips.tsx; composer-chip-token.ts is what the send path needs): the editor stays a textarea. A chip is a token in the draft (U+2063, two figure spaces for the icon, the label with no-break spaces, U+2063, so no line breaks inside it); while the text holds a chip, a mention or the selected skill, the textarea's glyphs turn transparent and a mirror behind it draws the same characters, one block per line, with the chips styled, so both wrap alike. Images and an inline contribution's chips become tokens at the caret; Backspace takes a chip whole, the caret steps over it, a click opens its popover (details, Remove, a kit's Detail), a chip whose token was deleted is dropped at the send, and a chip is sent as its label. Vim, Readline, history, ! shell and the menus keep working on the text as before; during IME composition the textarea draws its own text
• folding while scrolling: scrolling back through the transcript folds an idle one-line composer to its text line (useComposerCollapse.ts), a key, a press or the transcript's end opens it; this client's own choice (Settings → General, client storage tau:composer-fold)
• the footer under the prompt, one slim row as in the workbench design (ComposerFooterControls.tsx, composer-footer-layout.ts, ComposerMenu.tsx): the model as a filled pill with its marks inside, the reasoning level as text (a click opens the model picker at its thinking column), the kits' row controls, one "…" menu, and the round send (K91). The menu holds "Attach files" (drag and paste take files too), "Compact context" with the share used, and every placement: "menu" control (access, mode, stash, service tier); the context dial comes back into the row from 75 % on. Send is always there, resting in a paler accent while there is nothing to send; while a turn runs it steers or queues (its tooltip names the chords: ↵, ⌘↵, ⌥↑, ⇧↵, $ skills, / commands, @ files), and a quiet stop (ring and square, red under the pointer) sits before it, apart from it; Esc and "Stop the run" in the palette stop too. Placeholders are short: "Ask anything, or hand it work…", "Steer, or queue a follow-up…" while a turn runs, "Answer in text…" for a question. As the composer narrows, the kits' chips drop their labels and then move into the menu; model and reasoning stay longest, so the model's name is cut only when nothing else is left. The menu's trigger answers to the data-composer-shortcut ids of what it holds. The thread's cost is in the thread's head, and there is no checkout row under the composer: a running thread's branch is a menu in its head (Workspace Kit), and a new thread chooses where it runs in "Run on" and "Branch" (K84)
• a new thread is a chat (design 1k, 1o): the empty conversation says "What should <project> do next?" with one sentence in the middle, the composer sits where a thread has it (at the bottom, on a phone too), and under the heading and its sentence a row of pills (draft-actions, K98): core's project (a click opens the project picker at the pill and moves the draft), Machines Kit's "Run on" and Workspace Kit's branch, each opening its popover (a sheet on a phone or tablet); the draft's footer holds the model, the level, "…" and send. "New thread" (⌘N, the rail's "+", the palette, a phone's button) asks for the project first, so a thread never starts in the wrong one: a popover-style picker (a bottom sheet on touch) with search, the project in context first and selected, then the most recently used, each with its icon and machine, and "Add project…" last; ↑↓ ↵ Esc. One project starts at once; none opens "Add project". The head reads "New thread" alone (K104): the pills already say project, machine and branch. Every project mark (pill, picker, rows, the phone's lists) draws the icon a kit published with setProjectIcons (Workspace Kit's Project settings) before the host's own
• questions and approvals as one card on the composer (ExtensionPrompt.tsx, design 1n): head with the kind, who asks and "pick one/any", the question, options with a second line, "Or type an answer below" and the primary action in the card; the composer's placeholder is "Answer in text…". While a turn waits on one, its live line says so with a spinner: "Waiting for permission to edit" (or to run a command) for an approval, "Waiting for your answer" for a question
• the slash, $ and @ menus: one list of 32 px rows, name and description on one line, the source as a quiet note
• Pi commands: extension commands, /skill: and prompt templates, as Pi reports them
• model, thinking level, context usage and compaction; what the thread has spent so far, and apart from it what a subscription covered with its API value (UiThreadUsage.subscription, priced by core with the user's modelPrices)

Threads

• the thread index across projects, and one live runtime per open thread
• new, resume, fork, duplicate, rename, tree navigation, recovery of a broken thread
• a new thread's draft is a row in the thread list: src/workbench/draft-threads.ts lists the draft on screen from the moment it opens, and every draft left with text or images in it, newest first; threadStore.getDrafts() reads them and DraftRow draws one (the project line marked with a quiet "draft", the first line typed as its title, else "New thread"). Leaving an empty draft drops it; one with something in it stays until it is opened again (openDraft), discarded (discardDraft) or sent, and a new thread beside it starts a fresh draft. The first message turns it into the thread's own row in the same update. Kept drafts live in this client's storage (tau.kept-drafts.v1, text only; images stay in memory), so they are this device's and do not travel to another. The desktop rail, a tablet's list and a phone's list show them above the active threads; a phone's Back from an empty draft closes it
• deleting a thread is reversible for a while: sessions.remove moves it into the host's trash (src/main/thread-trash.ts, <userData>/thread-trash/) — a Pi session file moves there, a thread of another backend leaves the shell record its provider hands over (removeThread), never the CLI's own history — and the index drops it. sessions.restore puts it back; the host purges an entry after 30 days (TAU_THREAD_TRASH_RETENTION_MS for a test instance) or on sessions.purge, touches nothing outside the trash, and runs threadDeleted only then. What a thread is called, where it sits in the rail and whether it is archived are a kit's (Thread Rail)
• the current project (working directory) as Pi sees it
• which threads were mid-turn when the host stopped: the host writes one marker per thread to <userData>/turns-in-flight.json when it accepts a prompt ({ sessionId, cwd, turnId, backend, startedAt, prompt }, atomically, never into the session file, which is the runtime's) and drops it when the turn ends or is cancelled. At the next start each marker is dropped before its thread is touched, so nothing is ever continued twice, and then: with Continue threads after restarts on (Settings → General, threads.continueAfterRestart, off by default) the thread is reopened off screen, its dangling tool calls are closed and it is sent "Continue the interrupted work…"; with the setting off it is repaired, told so in its own transcript, and marked interrupted in the index until its next prompt. What "continue" means is the runtime's answer: the resume capability says whether the continuation can be delivered without reading as the user's own message, and a runtime without that capability is only marked. An external shell a kit owns is always interrupted; the kit says so through its own closed hook

Workbench

• the window's frame, after the workbench design (K75): no window-wide title bar and no panel rail. The left sidebar (256 px, dragged or keyed between 208 px and the window less 640 px, kept per client) runs to the window's top edge, where macOS draws its traffic lights over a 40 px strip that is the window's handle; Windows and Linux frame the window themselves. Right of it the conversation carries its own header (components/ThreadHeader.tsx, the drag region there): the thread's title menu, a line with branch · model mark and name · turn · cost, the title-bar region's kit actions (Workspace Kit's project actions, "N files changed ›", the Git action) and the stage's toggle; right of that the stage, whose tab strip starts at the top edge too. A drawer below the conversation (280 px, kept per client) holds a panel that asks for it. Shared modals. A panel moves between the drawer and a stage tab without remounting (src/renderer/use-panel-layout.ts, components/PanelHosts.tsx). A phone keeps a bar of its own over its chat (components/TitleBar.tsx): back, the title over machine (the host's name from its hello) · branch · model, whole, with turn and cost only where the bar is wider than 600 px, the kits' region and the panels it opens as sheets
• the order of runtimes: Pi, then backends by the provider's order; the host's runtimeBackends list is the one every picker, Providers and onboarding follow
• which token set the window paints with: system, dark or light, applied as data-theme on <html>; a theme package may replace the values, never the mechanism
• the client profile the window draws for (desktop, web, compact): a contribution declares which clients render it, and the workbench leaves out what this one cannot draw (ADR 0016)
• the type scale per device class (ADR 0029, src/renderer/type-scale.ts, tokens.css): a desktop draws the design's sizes; a touch client marks <html> data-device="tablet" or "phone" by its screen before the first render, which sets each text role larger, and keeps --text-scale at the system's text size (Dynamic Type through WebKit's -apple-system-body; Android's font scale from the app's plugin, whose web view's own text zoom is off), clamped to 1–1.5
• the stage: the document area right of the conversation, what the chat's 380 px leave until its divider is dragged (the chat keeps at least 360 px), whose tabs hold files, threads, panels and the surfaces kits register kinds for. Every panel opens as a tab and comes to the front (toolPlace, src/workbench/center-layout.ts); a panel that asks for the drawer is the one exception. The strip's right end holds a button for each panel with stageButton (Files, Terminal), the stage-bar region (Workspace Kit's "Open in"), "More tools" for the others, and the maximize. Chat and stage are side by side whenever both are open (a window short of room narrows the chat to 360 px first); only the user's own choices show one alone: the header's toggle hides the stage and shows it again as it was, and on an empty stage opens the tool last picked in the project, else Files; the maximize (the strip's button, mod+alt+shift+b, or dragging the divider well past the chat's minimum) gives the stage the whole centre, with no strip for the chat, until the strip's toggle, the keyboard or a click on a thread in the sidebar brings the chat back beside it. While the stage is hidden its tools sit in the thread header. A link opens or focuses a tab, never a second one: a file chip in a reply, an @file mention, a read or write tool row, "N files changed" (Files on its Changed view); a relative and an absolute path inside the project are one tab (stageFilePath). Each thread and each draft has a stage of its own (K72, "The stage" below): picking a thread (the rail, the palette, a thread shortcut, a phone's thread list) shows the stage it was left with beside its chat (the chat in front where only one of the two fits), and picking the one on screen brings the chat back beside a maximized stage and leaves the tabs as they are; a compact client closes its panel sheet instead. A new thread (⌘N, the rail's button, the palette, the start card, a phone's list) starts with an empty stage and puts the caret in its composer once the chat is in view
• the UI primitives everything else draws with (src/renderer/components/ui/, on tau since API 1.11.0): Menu with arrows, Home/End, typeahead, submenus and focus back to its trigger; one TooltipLayer for every data-tooltip element (600 ms rest, instant within a 400 ms group, keyboard focus); the toast stack (ToastStore in src/workbench/toast-store.ts: top right, three visible, five seconds of being seen, held while the pointer or focus is on it or the window is hidden, type icons, actions, copy; F6 moves focus into it), which every notice and the update restart use; Dialog, ConfirmDialog and Popover with focus trap and return; Skeleton, Empty and Spinner sizes; MiddleTruncate for branches and paths; and useContextMenu, the OS's menu where the platform has one. They are Tau's own code rather than @base-ui/react for size (PERFORMANCE.md); the palette, the model picker and the project picker give focus back when they close, the palette to the composer when nothing had it
• the window's title: what a Pi extension sets with ctx.ui.setTitle is a window-title push to every client, the host keeps the last one for a client that attaches later, and each client puts it on its page — Electron shows the page's title as the window's, a browser as the tab's. The host may run in another process than the window (ADR 0021), so nothing sets a native title directly
• the app around the workbench, owned by the window's process and spoken to its page over window-shell pushes and the client-side window-action method (src/shared/window-shell.ts, src/main/app-shell.ts, src/renderer/use-window-shell.tsx): the app menu (src/main/app-menu.ts: About, Check for Updates, Settings, Paste as Text, and zoom that always zooms the workbench's own page); ⌘Q held or pressed twice (src/main/quit-shortcut.ts, confirm.quit) and a question before a quit stops working threads (confirm.quitWhileRunning, not asked when the host keeps running); the updater's hourly check; on Linux, an AppImage without Chromium's sandbox offering the .deb of its release and restarting from /opt/Tau (src/main/appimage-install.ts, see docs/RELEASE.md); and the release notes of the version that just started, shown once (src/main/release-notes.ts). Settings → About shows the version and the licences of every package Tau ships, from the third-party-licenses.json the build writes beside the page (vite/third-party-licenses.ts)
• command palette and keybinding dispatch, with when clauses read from focus contexts the page marks (src/renderer/keybinding-when.ts, keybinding-context.ts) and editableFocus, which holds while any text field has the keyboard; the chords themselves are contributions — Runtime Controls binds core's own, each kit its own, kits/keybindings/ replaces them from ~/.pi/agent/keybindings.json and adds one command per Pi extension shortcut. Settings → Keybindings records chords and hands them to the user keymap a kit registers (registerUserKeymap; Keybindings Kit writes the file), showing beforehand which live bindings would share the keys (findKeybindingCollisions, the same platform and when rules as the dispatcher). The defaults are in docs/keybindings.md
• what the palette finds besides commands: sources extensions register (registerPaletteSource), asked per keystroke with the thread index and a signal that aborts when the query moves on, and core's own Settings rows. The merge is src/renderer/palette-results.ts: label matches among the commands, then the sources in order, then the Settings rows, then commands that matched only by their group
• levels in the palette, a drill-down: a command or a row with a submenu opens a level with its own search (PaletteMenu.items, asked per keystroke like a source), a breadcrumb over the field, a back button, and Backspace in an empty field to go back, each level getting its query back; rows may carry an icon, search words they do not show and a "Current" mark (menuRows in palette-results.ts). openCommandPalette({ menu }) opens on a command's level. Core's own levels are Set model… (every runtime's models from the host's catalog cache, the thread's runtime first; another runtime's model starts a thread there), Change theme… and New thread on…, where runtimes and providers are their icons, named in the icon's label (src/renderer/settings/palette-menus.tsx)
• Settings as a page of its own (src/renderer/settings/SettingsScreen.tsx): it covers the whole window — the section column with the search and Back on the left, a bar with Settings / <page> / <scope>, the page at a readable width built from sections of rows (settings-layout.tsx: SettingsSection, SettingRow, useSetting, on tau). Escape, Back and mod+, return; the workbench stays mounted underneath, inert. openSettings(page) opens a page by id
• Settings search: a field at the top of the Settings column over core's rows (a row it finds is scrolled to and marked), the pages extensions added (by label and keywords), each extension's page and every live keybinding; arrows walk the results, / focuses it. The index and its ranking are src/renderer/settings/settings-search.ts, and the palette reads the same one
• the levels a setting is read from: the built-in default, the host (~/.tau/config.json) and the project (<project>/.tau/config.json), first set wins from the project down. HostConfigManager.readLayers and clear (host methods get-config-layers, clear-config) keep the two files apart, src/shared/config-layers.ts resolves a key's value and origin, and src/workbench/config-layers-store.ts is the client's copy that writes to the level being edited. A row shows where its value comes from and resets or overrides it; a page with scope "project" or "both" offers the project in its head. Pi's own keys stay Pi's: they have Pi's global and project files A host half reads its own keys resolved for a project with services.settings(cwd).
• extension lifecycle on both sides: desktop extensions in the renderer, host extensions in the host
• one versioned request/push protocol between client and host, with reconnect, heartbeats, replay and per-client subscriptions (a client is sent the streams of the threads and topics it shows); Electron IPC is one transport of it, and the one generic method host extensions use travels on it
• who may connect to the host (ADR 0023, ADR 0024, src/main/host-access.ts): the host token is the owner's; any other device asks to pair over the socket — with a single-use link's code or, for discovery, without one — and gets a token of its own only once the owner allows it on the host after comparing six digits both screens show (bound to the pinned key when the device pins; ADR 0026). Tokens are kept as hashes in <userData>/paired-clients.json and end after 30/90/365 days unused or never; each device is Full or Read only, and src/main/host-method-access.ts classifies every host method so a Read-only device is refused every change on every call (kit commands declare access: "read"). Every owner window asks about a waiting device at once (src/renderer/pairing/); Settings → Connections (src/renderer/settings/ConnectionsPage.tsx) lists the host's addresses, waiting requests, the paired devices with their preset, last change and expiry, and the host-token connections, makes links (every address, the key pin and the fingerprint in the fragment, each address a CA vouches for marked, a QR code for a network address), renames a device, changes its preset or timeout, revokes one or all others — open connections close at once — and rotates the host token. Only a connection with the host token may do any of it. Network access on the same page opens listeners beside the host's own loopback one, in the running host (src/main/host-network.ts, <userData>/network.json): Local network (every interface) and Tailscale (its addresses, plus a loopback listener a proxy such as tailscale serve forwards to), on fixed ports, TLS only beyond loopback, with the self-signed certificate or the user's own, re-read when it changes. Each listener carries a trust — loopback, network or proxy — and only the loopback one grants local files and the local window; endpoints are labelled by kind (LAN, .local, Tailscale, MagicDNS, IPv6) so a device picks the one it reaches (src/main/host-endpoints.ts, host-protocol.md). A package takes part through services.network (src/main/host-network-contributions.ts): it holds the proxy listener open, for this run or across restarts (<userData>/network-kept.json), and publishes endpoints only it knows, which join the list, the pairing links and the accepted page origins; behind the proxy listener the tailnet user Tailscale Serve names is shown beside the client. The page draws packages' sections below Network access (registerSettingsSection), and a host command that changes who can reach the host is registered with access: "owner", which holds it to the host token on this machine like the connections-* methods. While Local network listens, the host announces _tau._tcp with its id and fingerprint through the system's own responder (dns-sd, Avahi, Windows' DNS-SD API; src/main/host-discovery.ts, the record's contract in src/shared/discovery.ts), and connections-discover looks for other hosts only when the owner asks (host-protocol.md)
• the host as a system service of its machine (src/main/host-service.ts, units in host-service-units.ts): a LaunchAgent, a systemd user unit or a Task Scheduler task per userData that runs the same headless.js a window starts. Such a host writes host.json itself (service), takes over from the host it names on that host's port, and is the one a window adopts, never stops and follows to a restart; a host of another version is restarted, then repaired, once each. Settings → Connections (host methods service-status for any client, service-install, service-uninstall and service-allow-sandbox the owner's, classified in host-method-access.ts) and tau service manage it. On Linux, install --display (service-install with [{ display }]) adds an invisible display: an Xvfb unit the host unit wants, with a cookie, DISPLAY/XAUTHORITY in the host's environment for every shell it starts and a desktop session's Wayland variables out of it (UnsetEnvironment= in the host and window units, leaveDesktopSession in the host for a unit an older Tau wrote; the window also runs with --ozone-platform=x11), and a window unit bound to Xvfb and the host that ClientCalls starts through DisplayWindow (src/main/display-window.ts) when a window-half call finds no window, and stops after 10 minutes without a call; UiHostService.display reports it. Where the kernel restricts user namespaces, the window needs an AppArmor profile for Tau's binary (src/main/linux-sandbox.ts: detected from the process's own AppArmor label or the profile file, written and loaded by one pkexec call in a host and one sudo call in tau service, never --no-sandbox). Beside it, hostKeepAwake holds the machine awake while any thread runs a turn (src/main/keep-awake.ts)
• the machines a window knows (ADR 0025, src/main/window-environments.ts): beside its own host, a window keeps the machines the user paired it with in <userData>/environments.json (0600, each token encrypted with safeStorage; nothing is saved where that cannot encrypt). Adding one pairs through ADR 0024 from the window's process (environment-pairing.ts: a link's key pin, or a bare address's key pinned for the attempt, digits bound to it; an address the host flagged for a CA is checked by chain and name instead, ADR 0026). One small connection per machine and one to its own host (environment-monitor.ts: auxiliary, subscribed to nothing but the threads a stage tab looks in on, pinging) report status and recent threads, and move a saved certificate pin to the key after a hello that pin let in. The page shows one machine at a time: opening a thread or starting one on another machine attaches a WindowHost to it and loads the page again with its address, token and environment=<id>, with the thread or the draft's text waiting. Chromium accepts the saved machines' pinned keys for their names, and the page's own sockets to them carry no Origin (environment-session.ts). A Bonjour search from the window's own host adds a machine without a link, pinned to its record; a saved machine follows the addresses its hello or its record names, each with its CA flag; the window can show the machine it showed last again at start; and core's "Back to this computer" returns from any machine, whatever kits it serves. The page reads it all through the client-side environments-* methods and the environments window event (Platform.environments, context.environments); the host keys of client storage get a copy per machine
• the machines a host reaches for its agents (ADR 0027, src/main/host-machines.ts): a pairing may ask for a second device, the machine's agents (companion in the pair frame); the other owner allows both in one step and revokes each alone. The window hands the agents' token to its own host (machines-add, owner only), which keeps it in <userData>/host-machines.json (0600, in the clear like host-token) and holds its own connection per machine (EnvironmentMonitor, no index). Kits act there through services.machines (machines permission): list, subscribe, call for a kit command, request for the core methods in MACHINE_REQUEST_METHODS only, and watch for a kit's topic events. Absent on a host in the window's process and in a worker
• how busy a machine is and what it could run (src/main/host-resources.ts, src/shared/host-resources.ts): host-resources (cores, CPU use over a few seconds, available memory, running turns, battery) and readiness (each runtime's state from the runtime catalogs, Git and whether it has merge-tree, free space where worktrees go, the display), both read, both in MACHINE_REQUEST_METHODS, answered only when asked. services.machines.request with the host's own id answers them here
• files between hosts (src/main/host-blobs.ts): services.machines.upload sends a file to another machine in 8 MB pieces (blob-put, blob-commit with size and sha256, blob-abort; Full access only), and a kit there takes it once with services.blobs.take (machines permission), after which it is deleted. The receiver keeps blobs in <userData>/blobs/ for at most an hour: 2 GB each, 4 GB per device, never below 512 MB free disk. Absent on a host in the window's process and in a worker
• which clients are attached: every transport reports its clients to one registry, so the host knows how many there are and what each claims to be; the count is published, and services.clients on the host seam is where a kit reads it
• sessions.start on the host seam: an extension has core create a thread for a project, index it and deliver its first prompt, without ever taking the screen; sessions.import (API 1.15.0, src/main/session-import.ts) takes over a Pi session another machine sent: a new id, this machine's cwd in the header, and a tau.remote-work/origin entry after it that the index reads as UiSession.origin, the rest of the history byte for byte
• Tau's tools for every runtime (ADR 0022): a local MCP endpoint in the host process (src/main/mcp-endpoint.ts, Streamable HTTP on 127.0.0.1, stateless) where kits offer the same Pi tool definitions they give Pi (services.mcp.registerTools) and gate every call (services.mcp.gate). A runtime backend asks services.mcp.connect for a thread's server entry — one bearer credential per thread, revoked when that thread's runtime closes — and puts it into its own MCP configuration; the credential decides which thread a call belongs to, so no tool reaches across threads
• media on a turn (src/main/turn-attachments.ts): which extension provides pictures or recordings of a thread's turns, and a list and read by thread for any other; core keeps no bytes and knows only the media type, and draws nothing
• what a project's commands may reach (src/main/host-execution-policy.ts, new in API 1.14.0): extensions provide a rule per folder (any, or loopback with the hosts still allowed and a reason), core merges them to the strictest — a provider that fails counts as loopback — and hands the result to extensions (services.executionPolicy.for) and to each runtime backend with its thread (HostBackendOpenContext.executionPolicy()). Core enforces nothing and knows no reason for a limit: the runtime kits apply it to their own sandboxes or refuse, and the kit that provides a limit holds Pi's bash to it
• the login shell's environment for everything the host spawns (on Windows the registry's PATH instead, docs/windows.md), and findCommand on the seam for extensions that need a tool from the machine
• watching the files the host itself reads — the package folders, the theme folders, keybindings.json, config.json — and reloading only what changed: the one package that was edited, the themes, the config. Core re-reads nothing on anyone else's behalf: observeConfigChanges on the seam and a config-changed push say what moved, and whoever owns those files decides. Tau's own update-config and clear-config writes reach observeConfigChanges even while watching is off, so a kit that reads its settings on the host follows them. Watching is off under extensions.watch: false (Settings → General → Reload files when they change, which applies at once), TAU_NO_WATCH=1 and safe mode (src/main/config-watcher.ts, src/main/workspace-watch.ts)
• enough persisted state to restore the workbench: the window puts each thread's and each draft's stage back the way it was left — its tabs, the active one, their order, the maximize, whether the stage was hidden, which panel it showed and the drawer (tau.stage.v2:thread:<id> and tau.stage.v2:draft:<draftId>, kept by src/workbench/thread-stages.ts) — and each project's tool last picked (tau.dock.v1:<workspace>, src/workbench/workbench-layout-state.ts); the chat's width stays per client. Tabs are stored as they are held, so a tab kind a kit adds round-trips and one that cannot be read is dropped; a file of another project and a thread the index has forgotten are dropped silently. The stage of a deleted thread goes with it, a settled thread's once it has not been opened for 30 days, a draft's once the draft is gone, and beyond 200 stages the ones opened longest ago; a page showing another machine keeps that machine's stages apart
• applying a rebuild: reloadExtensions() loads kits and packages again and the client reloads its page, without touching a single runtime and without waiting for anything, while reloadRuntime() is the heavier path that rediscovers Pi's resources and is the only one that asks about running threads. The build result chooses: a kit's runtime half (pi.cjs) takes the runtime path, the main process or preload takes a restart, everything else takes the light one. A package refresh never replaces the runtime extensions of a runtime that is already built — registerRuntimeExtension applies to every runtime from then on — so a turn in flight keeps the code it started with while host commands and panels change at once

The workbench and its client#

The workbench is always a client of a host in another process. The window starts that host, watches it and connects the renderer to its socket; the threads belong to the host, so the window may close, crash or reload without stopping one (ADR 0021). Thirteen methods stay on this side — clipboard, image preview, a workspace file shared with the page by URL (tau-ext://files/…, src/main/shared-files.ts: PDFs, images, audio and video inside the open workspace, with byte ranges), the kit bundles the renderer imports, the workbench rebuild, relaunch and update, a system notification, the app icon's badge, a right-click menu the OS draws and the app around the workbench (window-action: menu, quit, release notes) — and a kit that needs the window's process for a native view ships a window half the host calls with callClient.

src/workbench/ is Tau's client without a window: the thread index, the thread on screen, transcript pages, composer scopes and drafts, notices and the host connection, plus WorkbenchStore — the one place a host update becomes client state — and ThreadCommands, everything the workbench does to a thread that is one host call and a notice. It imports no React, no Electron and no browser global, and src/workbench/workbench-boundary.test.ts fails on any of them. Where it needs the view side it names a port, never a class.

src/renderer/ is the React binding of that client, and Platform (src/workbench/platform.ts) is what the client needs of the machine it runs on: clipboard, openExternal, files (only where the host's paths are this machine's), storage, importModule, attention — a notification the OS draws and a count on the app's icon, absent where the client has neither — and contextMenu, a right-click menu the OS draws at a point of the page (src/main/window-context-menu.ts: Menu.popup in the window's process); without it, or when it refuses, the page draws its own. Electron answers it in src/renderer/platform-electron.ts and a browser tab in src/web/platform-web.ts. The sandboxed Electron renderer holds no permission to notify, so its attention asks the window's own process (src/main/window-attention.ts: Notification, app.setBadgeCount); a tab uses the page's Notification API and draws the count into its icon. App.tsx is bootstrap, store wiring and layout; the three facts it cannot work out for itself — which client this is, whether kits were left out, and how to build the platform — arrive as a ClientEnvironment from the entry point.

There are two such entry points in src/. src/renderer/main.tsx is the Electron window; src/web/ is the browser client a listening host serves, which reuses every component and adds only its entry, its platform and the token handling. Below 720 px either of them lays itself out compactly — the composer at the bottom edge, and on a phone the thread list as its home page, with a project filter as an icon in its header and a floating New thread button that starts a draft in the filtered project, else in the one the host last worked in (lastUsedProject, never /), else asks; a tablet's list beside a thread starts it in that thread's project when no filter is set, as ⌘N does everywhere (newThreadProject in src/workbench/new-thread-project.ts). A chat is a screen over the list with Back in its bar. The list, the app pages that claim compact (registerPage, three at most, in their order) and Settings are the phone's main pages, with a bottom navigation (PhoneNav) as their last row (it remembers its pages, so they are there at the next start before the packages that register them have loaded); a chat, a page's view and a Settings section are sub-pages without it. usePhoneNavigation derives the route (src/workbench/phone-route.ts) from the workbench's state, and TouchLayer keeps the browser's history as the path from the list to it (phone-history.ts), so the system's back (Android back, the iOS edge swipe of the native shell) steps out one level and stops at the list; the address names the route (?thread=, ?page=, ?settings=) for a reload or a link — through body[data-profile] and src/renderer/profile-compact.css, not a second component tree. A browser on a touch screen claims compact at any width. A compact client on a tablet's screen (shorter side at least 600 px) and at least 720 px wide gets the desktop's arrangement instead (compactFormFor, with a 40 px hysteresis, never from height or content, and not while the page is hidden): the thread list as a sidebar, the chat, the panels that claim compact as stage tabs beside the chat (one of the two, with "Show chat" in the strip, where there is no room for both), no bottom navigation. The touch pieces live in src/renderer/touch/, a chunk only a compact layout loads: the thread list with a swipe to settle and a long press for every action (TouchThreadList, SwipeRow, ActionSheet), the list's header with search and More as popovers and a floating New thread button (TouchThreadBrowser), on a phone panels that claim compact as sheets over the thread (PanelSheet, opened from the phone's bar — the first two by their glyphs, from three on the rest from its More menu — and by actions.openPanel/closePanel, which reach the sheet there), sheets that close on a pull down (sheet-drag.ts), and TouchLayer — the height the on-screen keyboard leaves (visualViewport), a tap that shows a message's actions, and the open thread in the address (?thread=<id>, which a push notification opens; on a tablet back moves between the threads it held). A touch keyboard's return key writes a newline; the send button sends. A hardware keyboard on a touch screen (no on-screen keyboard over the page, body[data-keyboard] unset) sends on Return and writes a newline on Shift+Return, as the desktop does. Settings on a phone is stacked: the section list, then a page. The hello tells a device paired Read only (ADR 0024) so, and useHostCapabilities().readOnly carries it to kits, which disable a write with that reason instead of offering one the host refuses. Core's own writes follow it: the composer is a note, setting rows are inert with the reason, the palette, the title menu, the compact list and a file tab disable what changes the host (a command or palette row stays enabled with access: "read"; the palette leaves out a group or a source with no such row), a chord for such a command says why instead of running it, thread commands refuse with the reason, and preferences stay on the device.

mobile/ is a third entry point, the native app (Capacitor), which puts the compact client in a shell of its own: saved hosts, pairing by QR code or Bonjour, and a choice of address each time it connects (mobile/src/endpoints.ts). It asks two things of the workbench and nothing of the host: SocketTransportOptions.createSocket, so every socket is a native one that pins the host's key (or checks an address the host flagged for a CA), and ClientEnvironment.shell, the host's name above the thread list and the shell's own actions (Hosts) in its More menu. Each host gets its own view of the page's store (mobile/src/storage.ts), so drafts and the bootstrap cache of one never show up for another.

The model picker (src/renderer/components/ModelPicker.tsx) opens as a popover at the control that opened it (the composer's model chip, a settings field), without a scrim; on a phone or an iPad it is a bottom sheet with the same logic. Escape gives focus back to that control, and a choice made from the composer hands it to the prompt. It keys everything on what the catalog says, in three columns under one search field:

• Runtimes, as marks only (ProviderIconStack; a second instance wears its initials): Favourites, then every runtime the host offers, each instance of one included, with a dot for a state other than ready (model-picker-rail.ts). A tooltip names each and says its state and model count. A runtime that cannot run a thread (not installed, sign-in needed, unavailable) is dimmed, not hidden; choosing it says why and offers "Install…" or "Sign in…", which opens its card under Settings → Providers. For a new thread's draft one click on a runtime that can run it is the choice: the draft moves there with what it last chose there.
• Models of that runtime, one line each (model-offerings.ts): pinned first (the favourites, the model in use and the one last chosen on that runtime, which the cursor starts on), the rest behind "Show all N" once something is pinned or the runtime lists more than eight; each runtime keeps one fold for legacy generations. A runtime with several providers (Pi) shows their marks as filters above the list. A row across runtimes (search, Favourites, Recent) wears its route's mark, a runtime's own list only the access mark, and only where it mixes providers. Context, how a model is paid and its price per million tokens (a plan's shows what the same model costs over its API; a price the user set in modelPrices replaces the catalog's) are no columns: a quiet detail line under the list says them for the row under the cursor.
• Thinking: the levels of the model in use (or the one just chosen, from the catalog, until the thread reports it), Pi's default marked. Choosing a model keeps the picker open only while a level is still to choose; choosing a level closes it. A runtime that sets thinking itself says so here.

"Recent" (the client's own list) sits at the bottom, one click each, beside a link to pin models in Settings. The search runs across every runtime and groups a model's offerings under it. One menu in the search field holds the sorts (relevance; price, every plan before every API offering, each group by its API price; context; newest, by models.dev's releasedAt), the filters (billing, what a model can do), "Show hidden models" and adding a provider. Keys: ↑↓ move in a column, ← and → move between the columns (from the search field at its start and end), ↵ chooses, ⌥↵ pins, ⌘1–9 reach the first nine favourites of any runtime, ⌘⇧↑↓ step through the runtimes, and typing anywhere goes to the search. A row hides its model (with a pointer; a phone shows only the star). What a runtime hides and the order it lists its models in is modelPreferences.<runtime> in Tau's config, a record of the config levels that Settings → Providers → Models edits per runtime and project; favourites stay one list across runtimes (offeringKey: provider/id for Pi, <runtime>:provider/id otherwise). The host keeps every runtime's catalog, Pi's too, whether or not a thread of it ran (src/main/runtime-catalogs.ts, stale-while-revalidate, on disk across restarts, with price, context, inputs and billing filled from Pi's model data), and the picker lists another runtime's models from it (src/workbench/runtime-catalog-store.ts); a runtime that cannot run says why (not installed, not signed in) instead of listing nothing. A runtime whose program changed since its answer (programKey, the executable's fingerprint) is asked again at once, and the picker's Refresh asks every runtime; Tau's signed model catalog adds models Pi does not know yet (src/main/model-catalog.ts), and src/main/runtime-tool-updates.ts keeps the agent CLIs current from Settings → Runtimes (runtimes.md). Picking another runtime's model binds a new thread's draft to that runtime, and the draft keeps model, level and mode per runtime (runtimeSelections), so switching back and forth loses nothing; for a thread that exists it starts a new thread in the same project on that model, because a thread keeps its runtime, and offers the runtime-switch commands kits register beside it (Handoff Kit's "Continue in"). A draft bound for a runtime other than the thread on screen chooses from that runtime's own catalog (runtime-catalog, which a backend answers through newThreadCatalog without opening a thread): the composer's model and thinking pickers work as they do for Pi, the draft keeps the choice with the runtime it was made for (src/workbench/runtime-catalog-store.ts), and newSession hands model and level to the new thread through catalogWrite before its first prompt. A runtime that can only name its models inside a session (Antigravity before its first one) says so, and the thread starts on its default. One rule picks the marks everywhere (providerMarks in src/renderer/runtime-marks.ts), at most two, and never the model's maker: a runtime with a provider it owns shows its own mark alone (Codex with OpenAI, the Agent SDK runtime with Anthropic, Grok with xAI, Antigravity with Google). The runtime says which providers those are (homeProviders on its backend, published on runtimeBackends); core knows only that a runtime owns the provider of its own name (Cursor's cursor). Any other pair, Pi included, shows the access mark and the runtime's side by side, the runtime's a shade quieter (ProviderIconStack); a subscription plan wears its product's mark (Pi's openai-codex is Codex's; an Anthropic plan login the Agent SDK runtime's), unless the runtime says its plans are its own (ownPlan: Cursor, Antigravity), where Claude on the Cursor plan stays "Cursor via Anthropic". The tooltip names both. A list that is one runtime's (Pi's settings, the Pi-providers list, a runtime's own list in the picker) leaves the runtime's mark out. What the catalog does not say — which generations are legacy, which model wears a "new" badge for a while — lives in src/renderer/model-manifest.ts, hand maintained and dated; an unmatched model is current. A model behind a subscription login the runtime performs (UiModel.login, billing: "subscription") reads "incl." in the price column (the row's accessible name says Plan); whether that is worth a warning is a policy, and policies reach the picker and the composer through registerModelBadge and registerComposerGate. In a new thread's picker, Shift-click hands the model to the set an extension keeps (registerModelSelection) instead of choosing it; without one it chooses.

The stage#

The stage is the column right of the conversation, starting at the window's top edge with its tab strip (the design's 40 px on the side surface, the tab in front joined to its content, an "M" on a changed file, a dot on unsaved work, a panel's count, "All tabs" once some scroll out of view, then the tools, the stage-bar region and the maximize). Core owns the tab strip, the placement, the preview and pin rules and the strip's own gestures — double-click pins a preview, the middle button and Escape close, mod+w closes the active tab, ctrl+tab and ctrl+shift+tab move through them, and the right-click menu offers close, close others, close to the right and pin/unpin. Two kinds of tab are core's own, and a third belongs to whoever registered it.

A file tab shows source or the working-tree diff; core owns the tab strip and the placement, and whoever registered the document source loads the content. openFile(path, { line }) opens the source scrolled to a line and marks it; the tab keeps the line with a request count, so asking for it again scrolls there again. The header draws the commands extensions offer on the file-tab surface (Files Kit's "Edit file"); they read the tab from actions.activeStageTab(). A thread tab shows another thread's transcript, read-only, drawn with the same VirtualTranscript the conversation uses and headed by the title, status and cost the thread index carries. It exists so a sub-agent's chat can be read without becoming the thread the composer talks to; "Take over" is the one button that does switch — and even then the child stays out of the rail, which never lists a thread with a parent. It reloads when the index republishes that thread's entry — which is what the host does when a background turn settles — and polls every two seconds only while the index says the thread is streaming. A tab whose session the index no longer knows shows an empty state rather than an error. WorkbenchActions.openThread(sessionId) is how an extension opens one; the Agents Kit panel is the caller that motivated it. With { machine } (API 1.15.0) the tab reads a thread of another machine the window knows, over the window's own connection there (RemoteThreadDocument, environment-thread-watch.ts): subscribed only while the tab is open, read again at each change, and "Open on <machine>" in place of "Take over". It reads whether or not a runtime holds the thread: a released Pi thread is projected from its session file, a thread of another backend from the shell that backend keeps for the index, and neither opens a runtime.

An extension tab is a kind a desktop extension registered with registerStageTab: the kind supplies the title, the glyph and the content, core everything else. The tab is { id, kind: "extension", tabKind, params, title } with params plain JSON, so it is the same tab whatever draws it and it survives being written to storage; the content talks back through a handle (setTitle, setDirty, onClose), and StageTabController (src/renderer/stage-tab-controller.ts) is the one door that closes a tab of any kind — it asks about unsaved work, runs that tab's listeners and forgets its handle. A kit that goes away takes its tabs with it. Terminal Kit's "open as tab" is the shipped caller; docs/EXTENSIONS.md is the guide.

The stage belongs to the thread (K72). Switching threads writes the stage being left at once and shows the next one's (useWorkbenchLayoutState over ThreadStages); a draft has its own, which becomes its thread's when the first message makes the thread (the draft's composer scope moving to the thread's is the signal), and a draft moved to another project starts empty. A new thread starts with an empty stage; its header's toggle opens the tool last picked in the project. Hiding a thread's stage unmounts its tabs' content but closes nothing: no onClose runs, handles stay, and what a tab shows lives on — a terminal's shells keep running in the host (they end with their thread), the Preview page is the window's one browser and is neither closed nor reloaded, and a Files Kit buffer with unsaved work stays with its document. Each tab still reads and writes in its own project: the project is the one its thread or draft belongs to (stageWorkspace), as in K68 and K71. The first thread shown after the update to per-thread stages, and otherwise a project's most recent thread, takes the stage its project kept before (tau.stage.v1:<workspace>), with the dock's open state and drawer; no other thread does.

Not in core#

These were extension work still inside core files when Phase 1b in PLAN.md started the move; Phase 6 finished it, and each row below names the kit under kits/ that owns it now.

Runtime Controls is core, not a kit. The Settings screen with its General, Models, Pi, Keybindings, Connections, Extensions and Inspector pages, its search field and the controls every page is built from, and the contributions that reach core's own actions — the command palette, mod+, for Settings, escape to abort, mod+n, /reload, /tree, /fork, /clone, "Set model…", "Set thinking level…" — are the workbench itself. A window that cannot pick a model is not a usable window, and safe mode has to be one. They live in src/renderer/settings/ (runtimeControls, activated through registry.activateCore, so it is on in safe mode too and carries no switch). The host entry that reads and writes Pi's keybindings.json and its extension shortcuts is the Keybindings kit's kits/keybindings/host.ts, not core; Runtime Controls only keeps the id tau.runtime-settings, the name Pi's keybindings arrive under.

The Pi page draws the settings Pi owns. HostConfigManager splits an update-config patch: the keys Tau applies itself go to ~/.tau/config.json, and the keys Pi reads and applies go to Pi's own ~/.pi/agent/settings.json (or the project's .pi/settings.json), merging into what is already there. A value in Tau's file that Pi owns is therefore never accepted, persisted and then ignored — Pi's file is the one authority for those, and read lets it win. The names differ on one point: Tau calls a model provider/modelId in models.default, Pi wants defaultProvider and defaultModel apart.

The one thing safe mode loses with the kits is /install and the Packages page — the package manager is a kit like any other now. Recovering from a window that cannot install is still npm run start or an edit to ~/.tau/packages.json.

Out of sight on this machine#

Agents that work in the background should neither take the machine nor pop up in front of the user. What Tau does about it on the machine the user sits at:

• Lower priority. A sub-agent's commands (Agents Kit) yield to the user's work; everything a command starts inherits it. priority in ~/.tau/agents.json picks the level:

  • "low" (default): renice -n 10, on Linux plus ionice -c 2 -n 7. The commands still use every core when the machine is idle. macOS has no softer clamp for a running shell (taskpolicy -c utility -p does nothing), so there it is the nice value alone.
  • "background": on macOS taskpolicy -b plus renice -n 10 (lowest CPU band, throttled disk and network; on Apple silicon the efficiency cores only), on Linux renice -n 10 plus ionice -c 3. Under load a command can wait minutes, long enough to run into a bash timeout.
  • "normal": unchanged. "lowPriority": false, the older switch, means the same.

  Threads the user runs are untouched, and so are sub-agents on a runtime other than Pi, whose commands Tau does not start.

• No window of Tau's in front. The preview page keeps painting for the agent whatever the window shows, in a view that is never shown when it is out of sight (Preview Kit, above). TAU_NO_FOCUS=1 (src/main/background-mode.ts) runs Tau itself without a Dock icon and without ever taking the focus; test instances use it.

What macOS cannot keep out of sight, because it has no virtual display a program may use (no Xvfb; CGVirtualDisplay is private API):

• Computer Use. It works on the real screen in the user's session and moves the real pointer (kits/computer-use/ runs on darwin only anyway).
• Apps an agent starts with open (or any GUI program it launches). They appear on screen and take the focus; a lower priority does not change that.
• Windows placed off screen. macOS moves them back onto a display.

For work that must be invisible, move it to another machine: a Linux host runs without a window, and a display there is Xvfb's.

The stylesheet#

src/renderer/tokens.css is the palette, and it is a contract: every colour, font, radius, elevation and motion value Tau draws with is named there and nowhere else, in two sets — light-dark(light, dark), chosen by the color-scheme that data-theme on <html> sets. The theme preference (system, dark, light; system is the default and follows prefers-color-scheme) is core's, in Settings → Appearance (General without that page) and in the palette, and the client writes it onto <html>: no component in the workbench knows a colour. index.html links the file rather than importing it, so the first paint is already themed.

The palette is the workbench design's (K69), with a warm grey in the light scheme and a near-black with a faint blue cast in the dark (K77), on two grounds — the document area and the side surface, the latter the lighter one in the dark scheme — one blue accent for Tau's own actions and selection, green and red for diffs and checks, amber for a question, short light shadows, and Figtree as the interface face. Figtree ships with Tau as local woff2 files (src/renderer/assets/fonts/figtree/, SIL OFL 1.1, listed in the third-party licences) that tokens.css declares, so no font is fetched from a server and the first paint stays offline. The Tau mark is a warm-white τ on that blue (--brand, artwork in assets/icon/): the app icon, the reload curtain and the onboarding mark.

Spacing is a token scale too: --space-1 to --space-8 (2 to 32 px), each multiplied by --density, which is 1 unless a client sets it on <html>. The structural spacing — the thread rail, the thread row, the transcript, the headers, the composer, the Settings screen — reads the scale; detail rules keep their pixels until a visual pass moves them. Core applies no density of its own: Appearance Kit sets it.

The table of those names is in EXTENSIONS.md §8, because it is what a theme package — a manifest with styles and no code — may set. A theme's stylesheet is linked after core's tokens and after every kit, so its names win on order alone. Nothing about a layout class is API.

A kit that draws a surface of its own carries the rules for it: a styles entry in its manifest, kits/<name>/styles.css, linked while the kit is active and gone with it (see EXTENSIONS.md). Workspace, Agents, Preview, Signals, Packages, Questionnaires, Pi UI and Review have one. They name tokens like everything else and define no colour of their own.

src/renderer/styles.css keeps the classes core itself draws, which is the whole of the test: a rule stays if a core component renders the element, even when only a kit ever mounts that component.

The rules for classes nothing renders any more are gone (.approval-mark, .image-placeholder, .palette-group, .reasoning-toggle, .reasoning-body, .typing-mark, .thread-virtual-spacer, .tool-group-header, .turn-activity-stack, .title-auto-toggle, .review-file-read, .review-files-virtual, .tier-mark, .title-generator-actions, .review-file-select, .review-comment-composer, .review-notes).

How to check#

• Every colour is a token: src/renderer/tokens.test.ts fails on one written outside tokens.css, on a var() naming a token nothing defines, and on a text token that misses WCAG AA in either scheme. A package that brings only a stylesheet is a theme — no grant, loaded last, marked "Theme" in Settings → Packages.
• Settings → Packages lists the two sets apart: the kits Tau ships (scope: "bundled" from inspectBundledKits, granted by construction), headed by the distribution they came in (@tau/kits and its version, from dist-kits/manifest.json), above the packages a source installed. A rescan after an install never touches the first set — the activator only ever loads what it scanned from the package folders, and refuses a package claiming a kit's id.
• The kits Tau ships live under kits/<name>/ with a tau-extension.json and load through the package loaders, from dist-kits/ when the app was built and from the sources otherwise. There is no other door in either direction: a kit reaches core through tau (src/renderer/extension-api.ts), tau/host-extension (src/main/host-extension-api.ts) and tau/host (src/main/host-extension-worker-protocol.ts), plus the two test harnesses its own tests may use; core reaches a kit through the contributions the kit registers, never by path. src/shared/kits-boundary.test.ts fails on any other reach, and src/shared/core-boundary.test.ts fails if an extensions/ directory reappears under src/. A kit that also runs inside a Pi runtime Tau does not own ships a pi entry, prebuilt to dist-kits/<id>/pi.cjs, which .pi/extensions/tau-session-bridge.ts loads through PiKitBridge — the bridge itself names no kit.
• start:safe shows the core list and nothing more. That includes no access gate: safe mode runs tools the way Pi does.
• Removing a bundled kit removes its behavior on both sides without editing core.
• src/shared/contracts.ts and src/main/index.ts name no feature. Feature commands travel through invokeHostExtension. Core operations are the method table in src/main/host-methods.ts; src/main/ipc-contract.test.ts fails when the client and the table stop naming the same methods.
• Thread lineage is an extension's claim, not a core field: a desktop extension publishes setThreadLineage, and the navigator hides spawned threads and counts a parent's working children from it. UiSession has no parent.
• PiHost orchestrates and owns almost nothing itself. Attached-Pi ownership, transcript projection, client-message correlation, extension questions and session-event translation delegate to focused modules, and so do the project facts a provider answers with (project-facts-cache.ts), the thread index and its shells (thread-index.ts), extension binding (thread-binding.ts), a runtime from build to teardown (thread-runtime-lifecycle.ts), the spare runtime and thread prewarming (runtime-prewarm.ts), a prompt's runtime spelling and its guards (prompt-preparation.ts), steering, follow-up and adapter turns (turn-delivery.ts) and what the host looks like right now — the snapshot, the model catalogs behind it, and every update and result that publishes them (host-publication.ts). What is left in pi-host.ts is the sequencing: activation epochs, the lifecycle queue and what each operation publishes. A thread's runtime answers through ThreadRuntimeBackend (src/main/runtime-types.ts): twenty required members in Tau's own vocabulary plus capability groups, with requireCapability as the one place that refuses what a runtime cannot do. The Pi terminal Tau attaches to is one of those backends (attached-thread-backend.ts), its collaborators receive named ports (host-ports.ts), and thread lifecycle work is serialised by a reentrant LifecycleQueue (lifecycle-queue.ts). The renderer delegates layout to Workbench, its client state to src/workbench/, and keeps per-thread composer data in ComposerScopeStore.
• Tests keep this true: src/shared/core-boundary.test.ts fails on a feature name in those two files outside a listed debt and caps pi-host.ts at 2,080 lines and App.tsx at 700; src/workbench/workbench-boundary.test.ts fails on React, Electron or a browser global inside the client. src/main/pi-host-safe-mode.test.ts proves safe mode loads no host or Pi extension, and kits/kit-lifecycle.test.tsx activates and removes every kit against the core slots.
• The client reaches the desktop host only through HostClient (see "Renderer host client" in host-protocol.md) and the machine only through Platform; src/renderer/host-client-boundary.test.ts fails on any module outside main.tsx touching the preload bridge, and client-storage-boundary.test.ts on any outside platform-electron.ts reading the browser's own store.
• An extension package is not core and is not trusted: it declares permissions, waits for the user's grant in ~/.tau/extension-grants.json before either half starts, and reaches host services through the proxy in guardedServices. src/main/extension-packages.test.ts proves an unapproved package is never even imported, in the global folder as much as in a project's. docs/EXTENSIONS.md is the guide for writing one.
• The renderer's own boundary is checked, not assumed: the window runs sandboxed with webSecurity, no webview tag and no permission of any kind (src/main/index.ts), and desktop bundles arrive over the tau-ext scheme instead of a blob URL, so the page's CSP is script-src 'self' tau-ext:. src/main/extension-bundle-server.test.ts fails if the scheme serves anything it was not given or if blob: returns to the CSP.

This page is docs/CORE.md in Tau's repository.