pohunek: headless multihost backbone for coding agents. I herd. They code. Engraving of a farmhand boy with a whip steering a plow pulled by three server cabinets labelled codex, claude and hermes.

pohunek.dev · Docs · Install · Surfaces

CI Latest release MIT license MSRV 1.96

**pohunek** is a headless, multihost backbone for coding agents. One small Rust daemon per machine. One durable terminal per Codex, Claude Code, or Hermes Agent session. One versioned JSON contract for everything you build on top. > A *pohunek* is the farmhand boy who drives the draft animals. He does not > plow himself — he keeps the team moving. The agents do the plowing. pohunek keeps them running on the right machine, in the right worktree, and tells you or your tooling when one of them needs attention. > **Status: pre-1.0, experimental.** Wire shapes, config files, and on-disk > metadata may change freely between releases. Runs on Linux x86_64 and on > macOS on Apple Silicon. ## Two machines, one minute ```bash # Which of your overlay peers already run a daemon? No tokens, no server. pohunek host discover # Start Codex on the build box, in a fresh worktree, with its first prompt. # Codex (like Claude Code and Hermes) is served only by its official package: # install it on buildbox first, then its hooks with `pohunek integration install # --agent codex` (docs/install.md, "Install official runtime packages from the # release archive"). # The project name resolves on buildbox; no filesystem path crosses the wire. pohunek session new --host buildbox --project myapp --agent codex \ --branch feat/parser --input "Fix the parser fuzz failures." --yes # Find sessions linked to one work item; repeated metadata predicates are ANDed. pohunek session list --meta-eq link.provider=github \ --meta-eq link.id=owner/repo#123 --meta-has link.url # Go do something else. When the agent waits for an approval or is blocked, # the record lands here, from every host at once. pohunek notifications watch --all-hosts # Take over the terminal across the mesh; Ctrl-] leaves the agent running. pohunek attach buildbox/s-01J00000000000000000000000 # What did it change? Diff of the remote worktree, untracked files included. pohunek session diff buildbox/s-01J00000000000000000000000 ``` Close the terminal, restart or upgrade the daemon: the session keeps the same PTY and child PID. Logout, a host reboot, or a worker failure ends that runtime generation; the session then shows `runtime.state=lost`, is never restarted behind your back, and `pohunek session resume` recovers it on purpose when the agent's native session id was captured. ## Why not a multiplexer and ssh A multiplexer keeps a shell alive. It does not know that the process inside is an agent, so every agent-aware need lands on whoever writes the tool. pohunek handles it once, for every agent CLI: | You need to | pohunek gives you | |---|---| | Know whether the agent is working, blocked on an approval, or idle | Live `working` / `blocked` / `idle` detection from OSC titles, screen patterns, and PTY activity. Detection rules are TOML manifests, so a new agent needs no recompile. | | Submit a multi-line prompt into an Ink TUI without it being half-swallowed | `session input` with per-agent framing (bracketed paste, delayed submit). Prompts can come from stdin so they never appear in argv or logs. | | Hear about it when something needs you, on any machine | Durable notification records (`unread → read → acknowledged → archived`), fed by agent hooks and daemon-side detection, deduped and debounced, fanned out with `--all-hosts`. | | Keep two agents out of one working tree | `--branch` creates a worktree per session off the base branch; ownership is recorded and checked before any reuse or cleanup. | | Get a conversation back | Hooks capture the agent's own session id for explicit `session resume`, which reopens the conversation in the same session. | | Watch without stealing the terminal | `session screen`, paged `session output` with exact runtime cursors, and `session wait` for bounded change polling. | | Drive it from a script or another agent | One versioned `--json` envelope, typed errors with recovery hints, `subscribe` event streams, Rust and TypeScript SDKs. | ## What pohunek is built for - **Headless by design.** This repository ships no user interface. The daemon, its protocol, the CLI with `--json`, and the SDKs are the product. Every GUI, launcher, or dashboard is a client of the same public contract: the Rust crate `pohunek-client` and the TypeScript packages `@pohunek/protocol`, `@pohunek/sdk` (with a node-free browser entry), and `@pohunek/testkit` speak one newline-delimited JSON protocol, with the TypeScript types generated from the Rust source of truth. A shell script around `--json` is a legitimate client too. [docs/sdk.md](docs/sdk.md) has the examples. - **A stable base for tooling you build yourself.** Each agent CLI has its own TUI quirks, prompt framing, hooks, session ids, and resume rules. pohunek absorbs those differences once, so your scripts, launchers, review bots, and manager agents talk to one contract instead of every harness. - **Multihost from the start.** Every host is authoritative for its own sessions. The CLI and SDKs talk directly to each host's daemon: an owner-only Unix socket locally, a NetBird (default) or Tailscale (Linux hosts) overlay remotely, bound only to the overlay address ([Tailscale guide](docs/knowledge/guides/tailscale.md)). No central server, no SaaS, no state sync. `--host buildbox` or a `buildbox/` target is all it takes, and a machine's own overlay name selects its local daemon, so one host name works everywhere ([resolution order](docs/cli.md#commands)). - **Driven by agents, not only by people.** Every automation command returns one versioned JSON envelope with typed errors. `pohunek agent-skill` prints the complete operating skill an agent needs, and `pohunek assistant` starts an agent session that already knows pohunek and your hosts. ```bash # An agent, or your script, working a session on another host: printf '%s' 'Run the focused tests.' \ | pohunek session input buildbox/s-01J00000000000000000000000 --stdin --json pohunek session wait buildbox/s-01J00000000000000000000000 \ --activity idle --timeout-ms 8000 --json # wakes on idle, or reports a timeout pohunek agent-skill --json # the full skill text plus its sha256 pohunek assistant "why does attach fail on my laptop?" ``` ```text your tooling: agents, scripts, launchers, GUIs, dashboards | pohunek CLI --json · protocol · SDKs +-----------+---------------+---------------------+ | Unix socket | overlay (WireGuard) | overlay (WireGuard) v v v laptop: pohunekd workstation: pohunekd buildbox: pohunekd | | | durable PTY workers durable PTY workers durable PTY workers claude · codex codex · hermes claude · shell ``` Each daemon hands every session to its own `pohunek-sessiond` worker (a systemd transient unit on Linux, a launchd job on macOS), which owns the PTY. pohunek is built for one operator on machines they own: owner-only permissions locally, your overlay's policies remotely, no multi-user auth, no hosted control plane. [Features and architecture](docs/features.md) has the full list and the trust boundary. ## Install with an agent The easiest way to install pohunek is to let the coding agent you already use do it. Open Claude Code, Codex, or another agent with shell access on the machine that should become a pohunek host, and paste: ```text Install pohunek (https://github.com/zajca/pohunek) on this machine and set it up so you can drive it. Read these first and follow them, they are the source of truth: - https://raw.githubusercontent.com/zajca/pohunek/main/docs/install.md - https://raw.githubusercontent.com/zajca/pohunek/main/docs/knowledge/guides/setup.md - on macOS also https://raw.githubusercontent.com/zajca/pohunek/main/docs/knowledge/runbooks/install-on-macos.md Rules: 1. Detect the OS and CPU. Linux x86_64 uses the latest release's pohunek-daemon--x86_64-unknown-linux-gnu.tar.gz (or -musl). macOS 14 or newer on Apple Silicon (tested on macOS 15) uses `brew install zajca/pohunek/pohunek`. For anything else, stop and tell me. 2. Verify every download with its .sha256 file and, when `gh` is available, `gh attestation verify --repo zajca/pohunek`. Stop on any mismatch. 3. Before changing anything, run `pohunek service check --json` (from the extracted archive on Linux), show me what will be installed where, and wait for my approval. Then install the login service (`./packaging/install-daemon.sh` on Linux, `pohunek service install` on macOS). Never pass --accept-runtime-loss, --stop-sessions, or --purge. When an upgrade refuses with `service_upgrade_sessions_at_risk`, show me the listed sessions and reason codes instead of overriding it. 4. Verify with `pohunek doctor --json`, `pohunek service status --json`, `pohunek health --json`, and `pohunek host inspect local --json`. Report every warning; fix only what I approve. 5. Ask me before running `pohunek integration install --agent `: it has no dry run and installs a SessionStart hook into that runtime's config home (for Claude Code `~/.claude`, for Codex `~/.codex`). Claude Code and Codex are served only by their official packages, so their hooks install only after the package does. Tell me which runtimes and configuration files it will touch and wait for my approval. 6. Run `pohunek agent-skill` and save its output as a skill or instruction file in your own harness, so later sessions know how to drive pohunek. Tell me where you saved it. 7. If this machine is in a NetBird or Tailscale network, run `pohunek host discover --refresh --json` and list the hosts that already run pohunek. 8. Never put secrets into commands, logs, or your summary. End with the installed version, paths, open warnings, and next steps. ``` Repeat it on every machine that should host sessions. Each host needs its own daemon, and remote hosts must be members of the same NetBird (default) or Tailscale network; [Tailscale setup](docs/knowledge/guides/tailscale.md) is opt-in. Once the daemon runs, `pohunek assistant setup` starts an agent session with the knowledge bundle of the assistant package (see [install](docs/install.md#install-the-assistant-package)) and the launch context. Use it to finish projects, agent profiles, and remote hosts. ## Install manually - **Linux x86_64:** each [release](https://github.com/zajca/pohunek/releases) publishes glibc and MUSL CLI and daemon archives. Unpack the daemon archive and run `./packaging/install-daemon.sh`. - **macOS (Apple Silicon, macOS 14 or newer, tested on macOS 15):** `brew install zajca/pohunek/pohunek`, then `pohunek service install`. - **From source (Rust 1.96+):** `cargo build --release --locked --bin pohunek --bin pohunekd --bin pohunek-sessiond`. ```bash pohunek doctor # environment check pohunek service status && pohunek health # daemon installed and answering # Claude Code is served only by its official package: install it from the # extracted daemon archive (Linux or Apple Silicon), then its hooks (session ids # + notifications). pohunek plugin install runtime/packages/claude.tar.zst --catalog runtime/runtime-catalog.json --yes pohunek integration install --agent claude pohunek session new --agent claude --name "fix-login-bug" pohunek attach # Ctrl-] detaches, the agent keeps running ``` [docs/install.md](docs/install.md) covers archive verification, what the login service installs, upgrades, the first worktree-isolated session, and runtime packages: the official Pi, Codex, Claude Code, and Hermes packages that each Linux daemon archive carries under `runtime/packages/` with the signed `runtime/runtime-catalog.json`, and third-party packages trusted by an explicit digest. ## Experiments built on pohunek [`zajca/pohunek-work`](https://github.com/zajca/pohunek-work) holds the author's own tooling on top of the core, and is the test that the core works as a backbone: every surface there uses only the CLI with `--json` and the public protocol through the SDKs, pinned to one core release. They show one way to build on pohunek, not the way. - **Native GUI** (`pohunek-gui`, Iced) for Linux (Wayland) and macOS; opening a session launches your own terminal. - **Web control center**: Bun backend, Svelte SPA with an in-browser terminal, usable from a phone over the mesh. - **Launchers**: rofi and sway scripts plus Linear and GitHub issue pickers. The core never learns about Linear, GitHub, or work items. It knows sessions, worktrees, projects, events, notifications, and opaque metadata, and leaves everything domain-specific to clients like these. ## Use, extend, contribute - **Use Pohunek** to keep agent terminals durable across daemon restarts, operate sessions directly across your NetBird or Tailscale hosts, or drive the public `--json` interface from scripts. Start with the [manual installation](docs/install.md) and [CLI guide](docs/cli.md). - **Extend Pohunek** with a Rust or TypeScript client, scripts over the CLI, or runtime packages. The [SDK guide](docs/sdk.md), [versioned public API](docs/public-api.md), and [runtime package guide](docs/knowledge/guides/runtime-packages.md) describe those shipped extension points. UI and workflow products are separate clients, not core components. - **Contribute** through [public issues](https://github.com/zajca/pohunek/issues), including the [maintainer-managed ready queue](https://github.com/zajca/pohunek/issues?q=is%3Aissue%20is%3Aopen%20label%3Areadiness%3Aready). Read the [contribution workflow](.agents/skills/contribute/SKILL.md) before choosing work. `readiness:ready` marks eligibility, not a reservation or merge promise; contributors do not need private Project access. ## Roadmap A sketch of the main tracks. The linked epics and the [repository milestones](https://github.com/zajca/pohunek/milestones) are the public source of truth for scope, order, and status. | Track | Where it is heading | Status | |---|---|---| | **Runtime plugin packages** — [#139](https://github.com/zajca/pohunek/issues/139) | Pi, Codex, Claude Code, and Hermes become signed, content-addressed runtime packages installed per host, with their own CI and compatibility matrix. Only `shell` stays built in. | In progress (37/46): the registry, package format, signed catalog, CLI lifecycle, the Pi, Codex, Claude Code, and Hermes packages (#145, #146, #147), the package CI and compatibility matrix (#149), and the package documentation (#151) have landed, with the compiled-in Codex, Claude Code, and Hermes removed; the open children are follow-ups (#868, #870, #899, #911, #1003, #1011, #1013). | | **More agents** — [#50](https://github.com/zajca/pohunek/issues/50), [#227](https://github.com/zajca/pohunek/issues/227) | Pi and OpenCode 2.x as further first-class runtimes. | Pi ships as an official runtime package; its end-to-end acceptance and OpenCode are open. | | **Delegated task runs** — [#182](https://github.com/zajca/pohunek/issues/182), [WS1–WS8](https://github.com/zajca/pohunek/issues/219) | Tasks and turns over ordinary sessions: causal turn settlement, a blocking `task.wait`, typed results with repository evidence and checks, and an optional MCP adapter. Agents can then delegate work to other agents reliably. | RFC accepted; implementation started with the WS1 protocol | | **Durability and detection** — [#420–#426](https://github.com/zajca/pohunek/issues/426), [#59–#67](https://github.com/zajca/pohunek/issues/67) | Recovery from crashes and host-wide session loss in one action, and explainable, arbitrated `working` / `blocked` / `idle` detection. | In progress: `lost` classification and recovery binding landed; one-action recovery and detection work are open. | | **macOS** — [#94](https://github.com/zajca/pohunek/issues/94) | Native Apple Silicon hosts with launchd-owned durable workers. | Supported: archives and a Homebrew tap ship; the remaining items of the [#105](https://github.com/zajca/pohunek/issues/105) acceptance gate are follow-ups. | | **Optional team relay** — [#56](https://github.com/zajca/pohunek/issues/56) | A public, multi-team control plane: hosts open the WireGuard link to the relay themselves, and the relay adds team ACLs, routing, and audit. The direct owner path stays first-class, and the relay lives in its own private repository ([`pohunekd/pohunek-relay`](https://github.com/pohunekd/pohunek-relay)). | Foundation (authentication, credentials) implemented there; transport and team surfaces pending | | **Dark factory** — [#185](https://github.com/zajca/pohunek/issues/185), [FS0–FS8](https://github.com/zajca/pohunek/issues/233) | Unattended manager/auditor delegation over the team relay, built as a client of the relay. | Design | The longer narrative and the shipped foundations are in [docs/ROADMAP.md](docs/ROADMAP.md). ## Documentation | Document | Content | |---|---| | [Features and architecture](docs/features.md) | Everything the core does, the daemon/worker split, and the trust boundary | | [Manual installation](docs/install.md) | Release archives, login service, upgrades, building from source, and a first session | | [CLI guide](docs/cli.md) | Every command, multihost targeting, automation and observation, notifications, the assistant, and Hermes | | [SDKs and your own client](docs/sdk.md) | Rust and TypeScript SDKs, connection, and event subscription examples | | [Development](docs/development.md) | Workspace layout, gates, fast test loops, and release | | [Knowledge guides](docs/knowledge/index.md) | Setup, remote hosts, project setup, agent skill, Hermes operator, and runbooks | | [Public API](docs/public-api.md) | The versioned wire protocol | | [Architecture](docs/architecture.md) | The authoritative design | Repository implementation rules start at [AGENTS.md](AGENTS.md). ## License [MIT](LICENSE). The Pohunek Hermes operator plugin and generated skill, shipped in the official Hermes runtime package (`runtime-packages/hermes`), and the core hook reporter compiled into the CLI are repository-owned MIT assets. Their Python modules use only the Python standard library plus the pinned Hermes host API; Pohunek does not bundle Hermes code, marks, model/provider SDKs, or third-party Python dependencies in that package or the CLI archive.