~~ marlin ~~

fast, durable terminal agents that SWIM between clients 🐟 built in Zig

current release: v0.1.5

⚡ recommended installer (macOS + Linux):

curl -fsSL https://marlin.wtf/install.sh | sh

prefer Homebrew? brew install jespern/tap/marlin

★★★ WELCOME to marlin.wtf ★★★ native agent ★ Claude Code + Codex guests ★ daemon-owned sessions ★ scriptable CLI ★ durable plans ★ SSH remote ★ MCP + hooks + skills ★ written in ZIG ★★★

>> what IS marlin??

marlin is a daemon-native terminal AI agent harness and session multiplexer. Its own agent runs native models; installed Claude Code and Codex agents can run beside it as guests using their existing vendor logins. The daemon owns the structured sessions while the TUI, web UI, and headless CLI remain thin clients.

Close a terminal and the turn keeps running. Reattach later, reach it through SSH, mosh, or your tailnet, or compose it with ordinary shell commands. The transcript, plans, status, approvals, diagnostics, and full tool results are still there—and inspectable without opening SQLite.

GARAGE PICK If Marlin were a car, it would be a first-generation Honda NSX: supercar fast, Honda reliable, usable every day, and direct enough that the driver always knows what the machine is doing. No touchscreen maze, no ornamental controls. Just a small, deliberate machine that starts every time and wants to be driven hard.

one native core binary: no Node runtime, no Python environment, no terminal scraping
one room for the fleet: Marlin's native agent, Claude Code, and Codex share durable multiplexed sessions without pretending they share an implementation
UNIX-shaped clients: run headlessly, list, search, inspect as JSON, archive, kill, and pipe results from ordinary shell scripts
append-only truth: context may compact; durable history and full tool output do not pretend they never happened
process-boundary extensions: managed MCP stdio servers, executable tools, hooks, and Markdown skills
visible execution: durable plans pin the active step and its timing while child work stays inspectable
durable review fan-out: delegate two to eight concurrent read-only jobs, or convene a named multi-model council
real image input: local clipboard paste and remote-safe path upload stay durable and reach vision models
NOT a kitchen sink: marlin is a daily driver. a feature earns its place by surviving daily use, or it gets deleted. the default answer to a new surface is no

DEVELOPMENT PREVIEW Marlin is already self-hosting and useful for real work, but it is not a stable 1.0 product. The native agent, Claude Code and Codex guest sessions, structured multiplexer, scriptable inspection CLI, extension platform, durable plans, child delegation, review councils, SSH remote client, and tailnet web UI are built. Current work is concentrated on hardening edges, diagnostics, and performance. Config and protocol details may still move.

>> what works TODAY

Developer-first TUIVim navigation, multiline editing, Ctrl+N for a new session, command completion, OSC52 copy, structured Markdown, syntax, diffs, reasoning, and foldable tool output.

Durable execution plansThe active step stays pinned in a timed two-column table with live progress and child activity. Completed plans close into scrollback; revisions survive reboot and compaction.

Real multiplexerDurable concurrent sessions, a clickable configurable tab strip, short stable handles, /sessions, per-session view state, and rolled-up child activity.

Actionable stateRunning, approval, error, and child status are typed protocol events, not guesses scraped from a terminal. !c copies the last complete tool result.

Remote without reinventionmarlin --remote host carries the structured protocol over SSH. marlin web is an opt-in loopback UI exposed to your phone through Tailscale Serve.

Context that admits realityInline output caps, full content-addressed blobs, pruning, compaction, usage accounting, and durable reconnect replay.

Self-hosting loopHeadless runs, steering, approvals, interruption, automatic client reconnect, and coordinated /reboot --build while developing Marlin inside Marlin.

MCP as a productIsolated health, daemon-owned add/remove/restart/reload, per-tool policy, durable image results, and one schema + approval path.

Permissions that enforceScrubbed tool environments, protected-path read refusals, capture-time secret redaction, managed network filtering, and canary-verified kernel shell sandboxing on macOS (Seatbelt) and Linux (Landlock) with safe fallback.

Claude Code + Codex guestsRun the official claude binary or stable codex app-server protocol as first-class multiplexed sessions using existing subscription logins. Guest permission prompts share marlin's approval bar.

Scriptable by designmarlin run works headlessly; ls, search, and inspect --json expose daemon-owned state for shell scripts without screen scraping or SQLite queries.

Children + review councilstask and task_batch create up to eight durable, attachable, read-only children. Named councils fan questions across models for parent synthesis.

Image-aware sessionsCtrl+V or /attach uploads signed image data through the client boundary, stores it by content hash, and maps it to native provider vision blocks.

Fast parallel toolsConsecutive tools marked parallel_safe really run concurrently, with at most eight workers. Durable results stay in provider-call order.

Provider choiceOpenRouter-first model catalog, built-in web search/fetch, and OpenAI-compatible and Anthropic paths, with per-session model and reasoning effort.

Local voice dictation/voice setup adds optional push-to-talk or toggle dictation with whisper.cpp or parakeet-mlx. Audio stays at the client edge, and transcripts land in the composer for review before submission.

>> take it for a swim

$ curl -fsSL https://marlin.wtf/install.sh | sh
$ export OPENROUTER_API_KEY=...
$ marlin run "why is my build broken"
# ...the daemon keeps the structured session...
$ marlin             # attach the TUI
$ marlin --remote devbox # same TUI, carried over SSH
$ marlin ls          # short stable handles, including children
$ marlin inspect 63df --json # metadata, state, plan, blocks, diagnostics
$ marlin search "permission denied" # search durable transcripts
$ marlin attach 63df # any unique prefix (minimum four)

# installed vendor agents can join the same multiplexer:
$ marlin run --model codex/default "review this patch"

# inside the TUI:
/council new core   # pick models, then choose Done
/review core audit this design before I ship it

The installer downloads the matching tagged release for macOS or Linux on aarch64 or x86_64, verifies its SHA-256 checksum, and installs it in ~/.local/bin without sudo. Homebrew also works: brew install jespern/tap/marlin. Tracking main instead? Clone the repository and run zig build with Zig 0.16.0.

>> development STATUS

track	where it is	status
M0–M3	agent loop, daemon, TUI, context engine, self-hosting reboot	✅ BUILT
M3.5	permissions + secret boundary (reads refused, secrets redacted, macOS+Linux sandbox)	✅ ENFORCED
M4	structured session multiplexer	✅ VERIFIED
M5	managed MCP, executable tools, hooks, skills	✅ PRODUCTIZED
M6a	durable child sessions + bounded task fan-out	✅ VERIFIED
M6b	named multi-model councils + durable reviewer sessions	✅ SHIPPED
M6c	SSH-carried remote clients + tailnet web UI	✅ SHIPPED
now	cancellation, reconnect, extension diagnostics, dogfood, and performance	🔨 HARDENING
later	workspace snapshots, isolation, leases, land/discard	📋 EVIDENCE FIRST

The source-of-truth details live in the milestones and the active M6 execution plan.

>> edges we're still sharpening (honesty zone)

subprocess cancellation: built-in shell and extension processes still need one consistent deadline, TERM, grace, and KILL primitive
extension burn-in: MCP and hooks work today; real-world dogfood and exact field-level TOML diagnostics are still active work
child hardening: durable batches and cancellation cascade are shipped; disconnect/reconnect and cancellation edges are still being tightened
MCP streamable HTTP: stdio is managed and supported today; remote HTTP transport remains later
hosted or multi-user web: marlin web is an opt-in, tokenless loopback client exposed through Tailscale Serve; your tailnet is the trust boundary, and it is not a public deploy surface
workspace undo/isolation: snapshots, leases, worktrees, /land, and /discard remain one deliberately later track
kitchen sink surfaces: no messaging gateway, realtime voice models, wake words, audio protocol, embedded terminal emulator, or dashboard empire; optional local push-to-talk dictation stays entirely at the client edge

>> sign my guestbook... i mean, links

SOURCE on GH made w/ ZIG RELEASES ARCHITECTURE

one handcrafted HTML file. the fish rejected React.