Heddlework

Heddlework is an agent development environment built around a simple idea: the workspace should outlive any one agent harness. Conversations, diffs, tasks, artifacts, review state, and workspace safety belong to the product; Pi, Codex, Claude, and future runtimes connect through adapters.

Today, Heddlework is a fast native desktop preview for Pi, rendered with GPUIX. The longer-term direction adds durable dependency-aware work, safe checkout lanes, scheduling, triage, and Fabric-powered orchestration without introducing another hidden agent loop.

A heddle guides one thread inside a loom harness. Heddlework applies that model to agentic development: harness adapters carry execution, while one workspace keeps the human-visible pattern coherent.

Heddlework currently launches Pi as an RPC sidecar. The transport boundary in src/pi/transport.ts is intentionally small; future harness adapters can implement the same application-facing contract while preserving their own execution semantics.

The app can also attach to an existing Pi TUI process and show its streaming response and tool activity. Start Heddlework once to install the user extension, then start Pi normally—or use /reload in an already-running TUI before opening its thread in the app. Prompts and supported controls from either frontend go to the same authoritative process. Closing an attached frontend does not terminate that process.

To access an app-owned session from a terminal, run the Heddlework terminal attach client from this checkout:

bun run pi:attach -- --list
bun run pi:attach -- --session /absolute/path/to/session.jsonl

This is a terminal frontend, not a second stock Pi TUI. Do not start another pi --session writer for the same live session. See Pi live synchronization for setup, ownership, reconnect behavior, and limits.

Requirements:

• Bun 1.3+
• a working pi executable on PATH
• a platform supported by GPUIX: macOS, Linux, or Windows

git clone https://github.com/monotykamary/heddlework.git
cd heddlework
bun install --frozen-lockfile
bun run start -- /path/to/repository

For UI development without credentials or a Pi process:

bun run demo -- /path/to/repository

For native UI development with reload-on-save (the process restarts so GPUIX rebuilds its input state):

bun run dev -- /path/to/repository

Build the current unsigned executable:

bun run gpuix:fetch
bun install --frozen-lockfile
bun run build
./dist/heddlework /path/to/repository

gpuix:fetch downloads the patched GPUix packages this fork depends on (see Patched GPUix). On macOS bun run build produces dist/Heddlework.app with Chromium bundled; dist/heddlework is a symlink to its executable.

Linux users can install the current unsigned build into their user application menu:

bun run build
HEDDLEWORK_PI="$(command -v pi)" ./packaging/linux/install-user.sh

The installer uses the standalone executable, a square scalable icon, and an absolute-path launcher so app-grid launches do not depend on the GUI session inheriting Bun or Pi from shell startup files. See Linux desktop integration for installed paths, GNOME cache guidance, removal, and diagnostic-log precautions.

Pushing a v* tag runs .github/workflows/release.yml: it checks, builds, and packages Heddlework.app (macOS arm64 and x64), a Linux tarball, and a Windows zip, writes checksums.txt, and publishes a GitHub Release. macOS signing and notarisation run when MACOS_CERT_P12, MACOS_CERT_PASSWORD, APPLE_ID, APPLE_TEAM_ID, and APPLE_APP_PASSWORD secrets exist; Windows signing runs with WINDOWS_CERT_PFX and WINDOWS_CERT_PASSWORD. Without secrets the assets carry an -unsigned suffix. macOS and Linux release jobs run the full bun run check; hosted macOS runners boot a 1024x768 virtual display, so scripts/ci-display.sh switches it to 1920x1080 first, otherwise GPUIX test windows are clamped to tablet width. Windows runs the typecheck and the suites that do not depend on POSIX paths. Cut a release with bun run release:tag patch then git push origin main --follow-tags.

The desktop process can serve the same workspace to browser and phone companions. Open Settings and pick a Remote access mode. This Mac binds loopback for a browser on the same machine, and Tailscale & LAN binds every interface and lists a link per address, with the Tailscale one first when Tailscale is running. The choice persists across launches. HEDDLEWORK_HOST=1 still forces it on for a single run, and the headless host serves a machine without a display:

bun run host -- /path/to/repository
HEDDLEWORK_DEMO=1 bun run dev:web -- /path/to/repository

bun run build:web writes the browser client to dist/web. The host serves those files when HEDDLEWORK_WEB_ROOT or dist/web is present, and the desktop binary looks next to itself for a web/ folder. Open the printed connect link to use the same controller from a browser. The host also prints a QR code of the connect URL. Bind with HEDDLEWORK_HOST_BIND=0.0.0.0 to reach it from a phone. The host prints one link per reachable address, Tailscale first when the Mac is on a tailnet, then LAN, and the QR code carries the first one. HEDDLEWORK_HOST_ADVERTISE overrides that choice.

The host prints a connect link carrying a bearer token. The token is stored with owner-only permissions under the Heddlework state directory (host-token) and the Settings surface has a Copy connect link action. The host binds to 127.0.0.1 unless HEDDLEWORK_HOST_BIND says otherwise. Every remote command goes through the same controller as the desktop UI, so Pi stays the single execution authority. The wire contract is documented in Harness adapter protocol.

Settings can also start Tailscale Serve so phones use a private HTTPS MagicDNS URL instead of a CGNAT IP. Setup never replaces another Serve endpoint and never turns on Funnel. See Tailnet HTTPS.

Settings → Power can keep the host computer from idle-sleeping while work is running, or while Heddlework stays open. macOS uses caffeinate, Windows uses SetThreadExecutionState, and Linux uses systemd-inhibit when a logind session exists. Display stay-awake is optional on macOS and Windows and is not claimed on Linux. Lid close, an explicit Sleep, and low battery still win. Web and iOS settings change the connected host, not the phone. See Host sleep prevention.

A sequential flow is a task graph. Each step can name the step it waits on, so independent steps run as soon as their prerequisites succeed and a failed prerequisite blocks its dependents instead of running them against a broken tree. Steps can set a retry count; a failed attempt is re-queued as a fresh session until retries run out. A step can also run in a worktree lane: Heddlework creates a git worktree on a heddlework/<task-id> branch under the state directory and instructs Pi to work only there. The primary tree is never reset or cleaned. When the task succeeds, the task page offers Merge lane (git merge --no-ff) and Discard lane; a conflict leaves the lane in place with git's message. Graph state is durable in flows.json and survives restarts.

After every turn that changes files, Heddlework records a mutation receipt: the files touched with added, modified, or deleted status, line counts, the patch (up to 200 KiB per file), and the tool names Pi called. Receipts are Heddlework-owned annotations stored in receipts.json under the state directory, capped at 200 per session; Pi's transcript is never altered. Open the Receipts surface in the right panel on desktop, or the Diff tab on web and mobile, to review or clear them.

The bottom dock and right workbench surface share in-process PTY sessions, an incremental VT grid, and one fixed-cell native GPUI host. A versioned 16-byte cell buffer replaces thousands of React nodes and large style graphs; GPUI paints backgrounds and framebuffer block masks through one nearest-sampled 2×2-per-cell texture, caches shaping without ANSI colors, and paints remaining glyph-atlas masks directly. Fractional cell advances keep the first and right TUI columns attached without xterm.js. Bun's small PTY fragments are coalesced at synchronized-frame boundaries, complete CSI controls take an allocation-light parser path, ordinary presentation is paced at 125 Hz, and completed DEC frames plus causal input responses bypass that deadline without exposing partial frames. Native Tab capture forwards Tab and Shift+Tab to the PTY while keeping focus in the terminal. Runtime settings cover installed fonts, ligatures, Nerd Font fallback, muted emoji, and contrast-safe light/dark palettes. bun run benchmark:terminal measures the complete 160×50 VT → React → NAPI → GPUI frame. See Terminal architecture and rendering.

Settings → Browser offers Aside and host-installed custom adapters alongside the built-in browser. Each external task needs explicit account selection and one-use approval. Web and SwiftUI clients run these tasks on the connected host. See Browser integrations for setup, the adapter contract, and access limits.

The right workbench panel now hosts an in-process CEF/Chromium child view rather than WKWebView or the user's system-browser profile. Tabs, lossless acknowledged navigation commands, fullscreen geometry, app-owned profiles, private sessions, and agent-access policy remain in Heddlework; GPUix owns the native child view, sandboxed Chromium helpers, input focus, and browser lifecycle. Native CEF fails closed outside a valid macOS app bundle. Build the linked GPUix runtime with bun run build:browser first; Heddlework then requires and hash-verifies its CEF manifest while building dist/Heddlework.app. Run bun run smoke:browser after packaging for a hidden local-page smoke covering native loads, profiles, command acknowledgements, sandboxed helpers, and clean shutdown. Set HEDDLEWORK_WITHOUT_CEF=1 only for an explicit browser-free macOS build. The same browser service can later target a remote/mobile host without loading CEF into the WASM client. See Browser architecture, security, and packaging.

Submitting while an agent run is active stages the input in Heddlework's editable queue instead of immediately surrendering it to Pi's immutable RPC queue. Enter creates a steering row for the next healthy turn boundary; the visible Queue action and Option/Alt+Enter create a follow-up for agent_settled. While idle, ordinary Enter still starts immediately, Queue parks work in a paused plan, and Enter on an empty composer—or the primary action—resumes its oldest row. The collapsed strip is inset like an upside-down checkout bar and tucks behind the composer; expanding it springs upward into a single bounded scroll surface where rows can be edited, held, removed, moved between lanes, explicitly steered, or reordered from their left drag handles.

Steering drains one row at a healthy turn_end; follow-ups drain one row after agent_settled, and lane-local FIFO order is preserved. A row hold blocks only its own lane. Delivery holds during compaction. Abort pauses the remaining tail until Resume is selected, while the controller's graceful pause waits for in-flight tools before stopping Pi. A terminal error also holds the tail, but a healthy retry or overflow-compaction recovery releases it automatically; otherwise it remains available for manual resume. Skills, prompt templates, and extension commands remain raw until Pi accepts them. Every built-in slash command is a queue barrier and is intercepted by Heddlework whether submitted idle or queued, so /name, /compact, /new, and similar controls are never collapsed into model prompts. A queued /new waits for its parent run to settle and starts a child-linked Pi session before the lane continues. Image-bearing slash text remains a normal message so attachments are never discarded. The Fabric gate in the queue strip selects live peers and inserts a cancellable /fabric await barrier through an input-only bridge; it does not inject model context. The owned queue is persisted per workspace. Stable rows, Flow correlation, lane identity, row holds, pause state, and images survive restart; if the process stopped during an uncertain dispatch, restoration pauses with a recovery hold instead of risking a duplicate control or prompt. Pi-native steering and follow-up entries are still mirrored as locked rows because RPC does not expose mutation operations for them.

Flows is a full-page read-only projection opened from the button above Search. Work merges every Heddlework-owned queue row with ordinary, scheduled, and historical Flow-named Pi sessions. Steer and follow-up lanes become sequential rail groups immediately: messages are tasks, /new is a pending session handoff, and /fabric await branches onto a connected peer-gate lane before rejoining the queue. After a handoff runs, Pi's own parentSession metadata keeps the resulting sessions on the same causal rail. Queue in chat returns to the fresh/current thread composer instead of opening a separate task form, so manual work has no Flow definition or lifecycle record. A task page shows the projected prompt or control, remaining queue primitives, current Fabric workers, and Pi result. Sessions older than seven days collapse into Settled until they run again or the user restores them. Triage derives successful and failed entries from terminal assistant stop reasons and tracks local read receipts. Pi remains authoritative for status and output; Heddlework stores only presentation annotations—settle/unsettle receipts, optional priority overrides, and user labels. Automatic priority rises with session duration.

Parallel work is also observational: any Pi session fans into agent rails only when fabric_exec reports participant previews or completed agent audits. It does not require a Flow name, managed child sessions, extra tools, or context markers. A user can queue an ordinary orchestration prompt from chat; scheduled parallel jobs still compile one prompt that asks Pi Fabric to spawn and join concurrent workers, while Fabric remains the execution authority.

Scheduled stores one-time, interval, and daily job definitions in the Heddlework runtime. Each due occurrence becomes the same queue primitives and a fresh Pi session, so schedules own intent while Pi sessions remain run history. The desktop runtime must be running; an occurrence for a different active workspace remains durably pending until that workspace runtime is available.

Pi RPC's get_commands response intentionally excludes built-in TUI commands, so Heddlework adds Pi's complete built-in command catalog to native completion and gives built-ins precedence over conflicting extension names. RPC-backed commands cover model and thinking changes, HTML export, session naming and stats, forking and cloning, new sessions, compaction with custom instructions, and resource reload. Host-backed commands open Heddlework's settings, model, thinking, resume, and session-tree surfaces, copy the last response, or quit cleanly. Prompt templates, skills, /llama, and other extension commands continue through Pi's prompt RPC so Pi performs their normal expansion or command handler.

Pi RPC exposes the full session tree through get_tree, but not the mutating half of /tree. Heddlework reads that tree natively and delegates selections through a control-only extension to Pi core's ExtensionCommandContext.navigateTree(), the same in-place navigation path used by the TUI. Active transcript paging starts from Pi's leafId, so switching branches keeps the session file and ID while restoring the selected branch. See Pi session tree integration.

Pi does not currently expose RPC operations for /scoped-models, /import, /share, /trust, /login, /logout, /hotkeys, or /changelog. Heddlework recognizes these commands and reports the protocol limitation instead of sending their text to the model. Authentication and trust changes can still be made from interactive Pi before reconnecting Heddlework.

Extension interactions are hosted in the main conversation area rather than embedded in the composer. Heddlework queues concurrent requests, shows searchable described choices and timeout countdowns, renders extension statuses, discovers slash commands, and retains visible custom-message media. Q&A-shaped tools and ctx.ui dialogs render as native forms, including math in stems and option labels; tabbed questionnaires and /fabric settings keep using their existing contracts. Arbitrary custom TUI factories stay in the terminal with a visible fallback. See Pi extension UI.

Every published GitHub release also feeds the package channels below. Prereleases (tags with a - suffix) stay on GitHub Releases only.

The macOS app is signed with a Developer ID certificate and notarised. The Homebrew cask also links heddlework onto PATH. The Linux packages install the binary under /usr/lib/heddlework, a heddlework launcher in /usr/bin, and a desktop entry.

Packaged desktop builds check GitHub Releases ten seconds after launch and every four minutes after that, download the matching asset in the background, verify it against checksums.txt (and codesign on macOS), and show a Restart to update button in Settings. Settings also has a Stable / Prerelease channel switch; builds with a prerelease version default to the prerelease channel. Installs owned by Homebrew, Scoop, winget, apt, or dnf are not replaced in place; the app shows the matching upgrade command instead. Set HEDDLEWORK_UPDATE_CHECK=0 to turn the updater off.

These channels describe what is still ahead.

The browser client in src/web/ is a second renderer over the same host protocol. After bun run build:web or bun run dev:web, open the host connect link to use sessions, the transcript, queue, flows, diffs, and settings without GPUIX. It is a preview, not a signed product channel.

The web app follows the desktop workbench layout. Narrow screens use drawers for navigation and panels, without a separate companion tab bar. On iOS Safari use Share → Add to Home Screen; on Android Chrome use Install app. Local notifications fire when the tab is hidden and a turn finishes or an approval appears.

packaging/ios/ renders the workspace in native SwiftUI and connects directly to the host over WebSockets. It keeps QR pairing, heddlework://connect?url=… links, and saved host connections. GPUix, web, and SwiftUI share the design contract in src/workbench/ui-contract.json; each uses its own renderer. Host-only operations show an explanation rather than a nonfunctional control. See packaging/ios/README.md for builds and Xcode Cloud.

The desktop application remains the primary environment for local repositories, terminals, worktrees, and native agent processes. Web and mobile stay additional surfaces over the same workspace model, not separate products.

1. Open a repository — pass a path or use the native directory picker.
2. Choose or resume work — Heddlework discovers persisted Pi sessions across projects without eagerly loading full transcripts.
3. Collaborate — prompt, steer, abort, switch models, adjust thinking, paste images, and answer extension dialogs.
4. Inspect execution — expand reasoning, ordinary tools, and nested Fabric activity without leaving the timeline.
5. Review changes — open the working-tree diff, filter files, wrap long lines, and keep large patches virtualized.
6. Organize the result — snooze or settle threads and review persistent notification history.

If Pi is not discoverable from the desktop application environment:

HEDDLEWORK_PI=/absolute/path/to/pi bun run start -- /path/to/repository

Heddlework follows a small supervised component model inspired by Cordis:

• src/core/kernel.ts owns deferred service injection, typed events, keyed contributions, dependent lifetimes, and reverse-order cleanup.
• src/workbench/plugins.ts composes transport, session discovery, workspace diff, and controller capabilities without giving the controller concrete providers to construct.
• src/pi/transport.ts defines the application-facing harness transport seam; Pi RPC is its first provider.
• src/protocol/ freezes the versioned surface contract: HarnessAdapter identity and capabilities, the WorkbenchCommand union, and JSON snapshot patches shared by desktop, web, and mobile; see Harness adapter protocol.
• src/host/ serves that protocol over WebSocket from the desktop process or bun run host, and src/web/ is the browser and PWA renderer over it.
• src/plugins/ discovers external workbench plugins by manifest with compatibility and trust checks; see UI extensions.
• src/receipts/ records per-turn mutation receipts; src/flows/graph.ts and src/workspace/checkout-lanes.ts gate flow tasks on dependencies and isolate them in git worktrees.
• src/updates/ performs the startup release check; .github/workflows/release.yml builds and publishes tagged releases.
• src/workbench/controller.ts projects harness events into UI state, owns the durable delivery queue, and rehydrates from authoritative transcripts.
• src/flows/runtime.ts persists schedule intent and compiles due occurrences into the same queue primitives authored directly in chat.
• src/flows/projection.ts derives Work and Triage from queue rows and Pi session summaries without a task lifecycle database; src/flows/fabric-projection.ts derives parallel branches from Fabric participant audits; src/workbench/thread-metadata-store.ts persists only local disposition, read, priority, and label annotations.
• src/plugin-api.ts is the narrow source-level facade for feature authors.
• src/ui/extensions.ts hosts observable, reversible feature manifests; one plugin can contribute several native workbench surfaces.
• src/ui/core-extension.tsx registers the shipped surfaces through the same contract available to future user plugins.
• src/ui/tool-presenters.ts remains a keyed presentation contribution slot.
• src/ui/transcript-projection.ts turns loaded transcript semantics into stable, progressively disclosed native rows; see Transcript projection.
• src/ui/ contains the shared GPUIX shell and never owns harness execution truth.

The UI boundary is intentionally not a microfrontend platform: extensions share one React/GPUIX runtime and register coarse feature surfaces rather than independent applications or a plugin per visual element. See UI extensions.

Heddlework applies the two dimensions from A Programming Paradigm for Spatiotemporal Composability at capability boundaries:

• Temporal composability: every registration, listener, timer, process, and other owned effect has an inverse attached to the same plugin, controller, or React lifecycle. Unloading the owner withdraws those effects in reverse order; operations outside the process boundary use their protocol's cancellation or compensation semantics.
• Spatial composability: replaceable capabilities are typed services, consumers declare them through requires, and providers are constructed only by provider plugins or the composition root. Internal collaborators receive narrow interfaces or props rather than locating providers globally.
• Component granularity: a Cordis component is an independently loadable capability or integration, not every source file or React component. Cohesive UI implementation may be split into static modules while remaining under one feature lifecycle; new plugins and contribution seats require an independently replaceable behavior and a demonstrated consumer.

Pi remains authoritative for Pi messages and sessions. Streaming state is temporary and replaced by get_messages after completion. Future adapters must preserve the same authority rule for their harnesses.

• Native GPU-rendered desktop shell
• Pi RPC adapter and persisted-session browser
• Streaming conversation, tools, images, extension UI, and notifications
• Virtualized transcript and large-diff paths
• Diff, settings, notification, and surface shells
• Cordis-style service/event lifetimes and in-process UI surface manifests
• External plugin discovery and compatibility metadata
• Stable harness adapter protocol
• Codex and Claude adapters
• Projection-first Flows with chat-authored sequential queues, participant-truth Fabric graphs, task pages, and Triage
• Durable one-time, interval, and daily scheduled Flow runtime
• Durable dependency graphs and safe checkout lanes
• Mutation receipts and artifact review
• Signed desktop installers and automatic updates (signing activates when certificate secrets are configured; updates are announced, not auto-installed)
• Web workspace client
• Mobile companion clients

bun run gpuix:fetch
bun install --frozen-lockfile
bun run typecheck
bun run test
bun run build

bun run install:dev builds the Chromium-bundled app and installs it as ~/Applications/Heddlework Dev.app, with its own bundle identifier so it sits beside a release install. Add --watch to rebuild and relaunch it whenever src/, scripts/, or packaging/ change (a rebuild takes about ten seconds). --dir <folder> or HEDDLEWORK_DEV_DIR picks another folder, and --no-launch skips opening it. The updater recognises these bundles and stays out of the way.

To update another arm64 Mac with each install, put its SSH alias in ~/.config/heddlework/dev-hosts.json, for example ["mbp2"]. The remote Mac needs key-based SSH and Bun at ~/.bun/bin/bun. Each install (including watch rebuilds) transfers the same app bundle, verifies its signature, and starts or upgrades its background runtime without opening a GUI. Busy runtimes keep their current version until idle. The previous app stays beside the new one as Heddlework Dev.app.previous.

Remote deployment failures fail the install command; rerun it to retry. --local-only skips remote deployment. Remote apps install under ~/Applications regardless of the local --dir setting. Open the remote app yourself when needed, and approve any macOS folder-access prompt for heddlework-runtime; a healthy network connection does not mean Pi has permission to load its files.

Every platform icon derives from media/heddlework-icon.svg. bun run icons regenerates the macOS .icns, the Windows .ico, the Linux hicolor PNG set, the PWA PNGs, and the iOS marketing icon; it needs macOS for sips and iconutil. Commit the outputs, since CI on the other platforms only consumes them.

The native terminal, the Chromium panel, shimmer text, and a few motion and event fixes need changes to GPUix that are not in the published @gpuix/* packages yet. patches/gpuix-0.7.0-heddlework.patch carries them. package.json pins @gpuix/react and @gpuix/native to tarballs under vendor/gpuix/, which are gitignored and come from one of two places.

bun run gpuix:fetch downloads the prebuilt tarballs from the fork's gpuix-0.7.0-heddlework.4 release and checks them against vendor/gpuix/SHA256SUMS. This is what CI does.

bun run gpuix:build clones GPUix at the @gpuix/native@0.7.0 tag beside this checkout, applies the patch to it and its zed submodule, builds the native addon with the CEF feature, and packs both packages. It needs Rust, cmake, ninja, and the Xcode Metal toolchain (xcodebuild -downloadComponent MetalToolchain). Bump GPUIX_BUILD_VERSION, the tarball names in package.json, and the release tag together when the patch changes.

The prebuilt native package carries a darwin-arm64 addon only. Other platforms fall through to the published 0.7.0 platform packages, so they get the React terminal renderer and no browser panel.

The native test suite exercises the real GPUIX reconciler and covers shell interactions, session paging, transcript following, clipboard media, extension dialogs, notifications, native diff virtualization, deep-scroll performance, and spring panel geometry.

• The desktop layout and interaction language adapt the MIT-licensed T3 Code interface.
• Icons include paths adapted from Lucide.
• Pi integration targets Pi.
• Native rendering is provided by GPUIX.

See THIRD_PARTY_NOTICES.md for complete attribution.

MIT