SumoCode

A retained terminal shell for Pi.
SumoTUI owns the foreground experience; Pi runs behind it over RPC.

---

SumoCode is the terminal UX layer I daily-drive on top of Pi. Pi remains the agent runtime: it owns models, the agent loop, tools, sessions, MCP, skills, authentication, and provider integrations. SumoCode owns the screen around it: rendering, input, transcript presentation, overlays, themes, activity, orchestration surfaces, and terminal lifecycle.

The installed interactive path is native and RPC-first. The release's sumocode executable in its bin directory is a Bun-compiled foreground host; it launches the bundled sumocode-pi child with --mode rpc, and the two processes communicate over Pi's JSONL RPC protocol. Contributors keep bin/sumocode.sh as the source/Jiti development path. SumoCode no longer depends on a private Pi constructor patch.

Note

This is a personal, opinionated project rather than a polished general-purpose distribution. The code is public and MIT licensed; the maintainer's persona, memory, settings, MCP configuration, and skills live in a separate private repository.

What ships

• Retained SumoTUI shell — Yoga layout, cell compositor, incremental frame diff, in-app scrollback, mouse routing, selection, modal layers, and signal-safe terminal cleanup.
• Structured transcript — Markdown, code, diffs, Mermaid, inline images, tool calls, skills, questions, background terminals, and delegated agents render as typed blocks instead of flattened strings.
• Agent orchestration — durable terminal_* jobs, headless and visible subagent_* delegation, role presets, bounded activity cards, cancellation, and isolated git worktrees.
• Cathedral workflows — command palette, Divine Query, Memory Scriptorium, model/session selectors, /sumo:review, /sumo:worktree, /sumo:roles, /reload, and /fast.
• Five themes — Cathedral, Amber CRT, Obsidian Temple, Herdr Terminal, and Ultraviolet Core. Each theme owns its palette, chrome, state colours, and working indicator.
• Deterministic visual verification — component, fixture, and real-runtime lanes converge on styled-cell diffs, geometry audits, and review screenshots.

RPC-first architecture

┌──────────────────────────── terminal ────────────────────────────┐
│                                                                  │
│  bin/sumocode · native executable                               │
│          │                                                       │
│          ▼                                                       │
│  in-process foreground SumoCode host                            │
│  SumoTUI · editor · transcript · chrome · overlays · input      │
│          │                                                       │
│          │ Pi JSONL RPC over stdio                              │
│          ▼                                                       │
│  Pi child: sumocode-pi --mode rpc -e extension/*.bundle.mjs     │
│  agent loop · providers · tools · sessions · MCP · skills       │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

The process boundary is intentional:

1. SumoCode is the foreground client. It owns the alternate screen, keyboard and mouse input, editor, retained state, and every painted cell.
2. Pi is the execution engine. It streams events and answers host requests through its supported RPC protocol.
3. The extension uses an RPC-child profile. It installs tools and compatibility commands needed by the host without starting a second terminal UI inside Pi.
4. Direct Pi remains available. Print mode, explicit --mode, non-TTY stdout, and --no-sumo-tui bypass the foreground host.

Launch shape	Runtime path
sumocode / sumocode . in an interactive TTY	Foreground SumoCode host → Pi RPC child
sumocode --print "..."	Direct Pi
sumocode --mode <mode>	Direct Pi
stdout is not a TTY	Direct Pi
sumocode --no-sumo-tui	Direct Pi diagnostic bypass

The current launcher workflow lives in DEV_LOOP.md. The patch strategy preserves historical migration evidence.

Install

Native release (recommended)

macOS arm64 releases contain the compiled SumoCode host, compiled Pi child, extension bundle, and required sidecar assets. Node, pnpm, and a separate Pi install are not required.

VERSION="$(curl -fsSL https://api.github.com/repos/dhruvkelawala/sumocode/releases/latest | sed -n 's/.*"tag_name": "v\([^"]*\)".*/\1/p')"
test -n "$VERSION"
curl -LO "https://github.com/dhruvkelawala/sumocode/releases/download/v${VERSION}/sumocode-${VERSION}-macos-arm64.tar.gz"
curl -LO "https://github.com/dhruvkelawala/sumocode/releases/download/v${VERSION}/SHA256SUMS"
shasum -a 256 -c SHA256SUMS
tar -xzf "sumocode-${VERSION}-macos-arm64.tar.gz"
./sumocode-${VERSION}-macos-arm64/install.sh
~/.local/bin/sumocode

install.sh copies the immutable release under ~/.local/lib/sumocode/ and symlinks both ~/.local/bin/sumocode and ~/.local/bin/sc to the native executable. Set SUMOCODE_INSTALL_PREFIX to choose another prefix. If macOS Gatekeeper blocks an unsigned download, remove its quarantine attribute explicitly:

xattr -dr com.apple.quarantine ~/.local/lib/sumocode/sumocode-${VERSION}-macos-arm64

Using SumoCode's Pi from other apps

Apps that launch the pi CLI themselves, such as T3 Code's Pi provider, can use SumoCode's bundled Pi through ~/.local/bin/sumocode-pi-cli, which install.sh also links. In T3 Code, set the Pi provider's binary path to ~/.local/bin/sumocode-pi-cli (expanded to an absolute path). The link moves to each new release when you install it, so the setting survives upgrades.

sumocode-pi-cli runs the bundled Pi with the bundled SumoCode extension, like sumocode --no-sumo-tui, with three differences:

• --version prints the bundled Pi version, which is the version those apps check.
• --no-extensions runs bare Pi. Apps pass it for helper runs such as commit messages and titles.
• The extension loads its app-host profile. The app owns the screen, so SumoCode draws no chrome and keeps only what works through Pi's dialogs: the question, terminal_*, and Slate tools, memory, and the /slate, /sumo:ship, /sumo:memory, /sumo:sync, /sumo:bootstrap, /fast, and /answer commands.

Inside T3 Code, T3's delegate_task replaces the subagent_* tools so child work appears in the app. The system prompt maps each SumoCode role to a delegate_task call on the Pi provider with the role's model and instructions. Herdr panes, themes, and the other commands stay in the sumocode shell.

From source (contributors)

The development loop requires Node.js 23.11.0 or newer, pnpm, and the Pi peer dependencies installed by pnpm:

git clone https://github.com/dhruvkelawala/sumocode.git
cd sumocode
pnpm install
pnpm dev /path/to/project

pnpm dev is an alias for bin/sumocode.sh; it intentionally keeps the source/Jiti launcher for checkout development. pi -e . remains the classic extension-only loop. Pi can also install the repository as an extension package for source testing:

pi install git:github.com/dhruvkelawala/sumocode

The full installed RPC-first experience uses the native sumocode executable; plain pi remains Pi's own entry point.

Useful launcher commands

sumocode [path]                 # start the RPC-first interactive shell
sumocode -d [path]              # run with JSONL diagnostics enabled
sumocode doctor                 # check Pi, host, module, and diagnostics health
sumocode diag [file]            # summarize a diagnostics trace
sumocode -w feature-name        # create a worktree and open SumoCode there
sumocode task "prompt" [path]   # start directly in an agent turn
sumocode --no-sumo-tui          # bypass the RPC host for diagnosis

Run sumocode --help for the complete launcher contract and forwarded Pi options.

Retained work and review

Physical Node source launches on macOS/Linux can retain headless and visible subagents across verified session replacement. Native/Bun artifacts and unsupported executable layouts use disposable backends and report retention as unsupported. Recovery refuses unknown identity or cleanup evidence. The predecessor recovery proof passed 35 of 38 real matrix cells; ambiguous-identity, PID-reuse-unknown and cleanup-unknown remain explicit OS-oracle capability gaps.

Settled retained worktree cards show recorded commit/file/cleanliness evidence. Use /sumo:worktree result <id> to inspect fresh Git evidence, confirm an apply that stages ordered commits without moving parent HEAD, dismiss the result, or separately confirm removal of a clean worktree. Apply checks every path touched by the commits, including changes absent from the final diff. Prune preserves the branch and retained completion evidence. Advisory budgets expose warnings; they do not automatically cancel work.

Active approval installation was retired by Plan 076. Dormant modules/tests remain, and Pi/operator trust policy owns approval. The approval visual state remains available to UI surfaces.

Everyday controls

Control	Action
Ctrl+/	Open the command palette
Ctrl+Shift+T	Cycle themes
/sumo:memory	Open persistent memory
/sumo:roles	Inspect and choose subagent roles
/sumo:review	Launch a tracked code-review agent
/sumo:worktree	Create or manage isolated worktrees
/reload	Restart the host and continue the current session
/fast	Toggle OpenAI/Codex priority service for this session

Themes and state

SumoCode exposes five preattentive agent states — idle, thinking, tool, approval, and learning. The active theme maps those states to its own colour and motion language while preserving the same semantic contract.

Theme order:

Cathedral → Amber CRT → Obsidian Temple → Herdr Terminal → Ultraviolet Core

Ultraviolet Core can optionally use Fredy Sandoval's 0BSD RunCat glyphs. The safe orbital indicator remains the default.

pnpm runcat:install
pnpm runcat:check

Then map U+E900–U+E904 to the installed icomoon font in the terminal and set SUMOCODE_RUNCAT_FONT=1. See the theme implementation and visual fixtures under src/themes/ and docs/ui/.

Repository map

Path	Responsibility
src/native/main.ts	Compiled installed launcher, argv roles, direct-Pi bypass, and in-process RPC host
bin/sumocode.sh	Source-mode contributor launcher, routing, diagnostics, task mode, and reload loop
sumo-rpc-host.js	Source-mode host entry with bundle validation and Jiti fallback
src/sumo-tui/rpc/	Pi RPC client, host state, hydration, editor, controls, selectors, and overlays
src/sumo-tui/	Retained renderer, layout, input, transcript, runtime, and test backend
src/activity/	Shared live/durable activity contract and producer adapters
src/subagents/	Delegated-agent lifecycle, roles, tools, worktrees, and delivery
src/background-tasks/	Durable managed terminal processes and terminal tools
src/extension-entry.ts	Stable Pi entry, bundle validation and profile-specific source fallback
src/extension-core.ts	Shared feature installation and compatibility bridges
docs/visual/parity/	Visual contract, scenarios, evidence, and approved runtime goldens

Development

Pi executes TypeScript through jiti in the contributor loop; there is no emitted application build required for pnpm dev or pi -e .. Generated dist/** outputs are build/release artifacts and are never committed: pnpm build:host, pnpm build:extension, pnpm build:bundles, and pnpm build:native exist for CI, the integration harness, local diagnostics, and tagged releases, and their outputs stay ignored. A generated source-mode extension bundle is self-verifying: dist/extension/.inputs.json binds the input-graph hash to the outputsHash of the published bytes, pnpm build:extension reproduces both deterministically, and the source runtime rejects stale inputs or a mismatched artifact and falls back to source.

Distribution policy: tagged releases build the precompiled native archive in CI. Pi git-package installs remain a contributor/source path through the stable entry (src/extension-entry.ts → classic or RPC-child source profile via jiti) and need no committed bundle. Never add dist/** files or binaries to a feature PR.

pnpm install
pnpm typecheck
pnpm test
pnpm test:integration
pnpm visual:ci
pnpm build

For local runtime work:

./bin/sumocode.sh -d .
sumocode diag

Before changing rendering primitives, read docs/SUMO_TUI_RENDER_PRIMITIVES.md. Before changing tools or interception, read docs/PI_TOOL_ARCHITECTURE.md. The complete edit, test, and release workflow is in DEV_LOOP.md.

Documentation authority

• AGENTS.md: repository and agent rules.
• README.md: current product and supported runtime paths.
• DEV_LOOP.md: contributor verification and release workflow.
• SETUP.md: portable setup and durable state.
• Plan ledger: execution status; dated plan bodies preserve historical evidence.
• V2 parity contract: visual verification and golden approval.

Historical documents carry a dated top banner linking to current authority.

Design and architecture docs

• ADR 0001 — SumoTUI framework
• RPC migration and patch strategy
• Transcript view-model contract
• Headless test backend
• Visual parity contract
• Cathedral UX specification

Acknowledgements

Mario Zechner and the @earendil-works team built Pi. SumoCode deliberately keeps Pi as the agent runtime and builds a different terminal experience around its public extension and RPC contracts.

OpenCode is an important influence on SumoCode's terminal interaction language.

The renderer and orchestration system were built with substantial assistance from frontier coding agents.

License

MIT — see LICENSE.