Persistent terminals for coding agents. Close the window. The work stays.
Yolo is a terminal workspace for people who run Claude Code, Codex and other coding agents all day. Every managed terminal is owned by a detached Rust Worker, so closing the TUI, restarting the Host, or reconnecting from another client does not kill the PTY or the agent running inside it.
The first-party client is a TUI. A trusted browser client can watch and drive the same terminals over a Hub public protocol. Neither client owns a PTY.
- The agent is not a child of the window. A Worker owns the PTY and its capability-registered process tree. The TUI and Host are replaceable.
- Start the agent normally. Every tab opens your shell. Yolo recognizes Claude Code or Codex after you launch it; creation never asks for an agent type.
- Recover what can be recovered. Client, Host and Worker failures preserve the live PTY when possible. After a reboot, a validated provider binding uses the provider's native resume command instead of pretending a dead PID is live.
- One terminal, many views. Writer leases serialize input. Observers can attach without stealing control; an explicit takeover demotes the previous controller.
- Local or federated. One Hub can expose local and remote machines; shared layouts and peer history remain separate from private focus and drafts.
TUI (first-party) Browser client / trusted plugins
\ /
\-- public Hub protocol -/
|
yolo Hub
|
yolo Host
|
+---------+---------+
| |
session Worker session Worker
| |
PTY PTY
| |
shell / Codex shell / Claude Code
Rust owns terminal identity, writer leases, PTYs, output journals, process supervision, agent detection, resume policy and recovery. The Hub owns shared layout documents. Each client keeps its own focus, zoom and Chat drafts.
There is one Rust yolo executable. yolo internal <role> starts the Host,
Hub, relay, broker and Worker roles from the same binary. Providers are
compiled-in adapters, not plugins.
Requirements: Bazelisk with the repository-pinned Bazel 8.2.1, and a Rust
toolchain selected by Bazel. Linux needs glibc 2.31+ and cgroup v2 for
production termination. macOS platform checks need the macOS SDK.
# from a clone of this repository
bazel build --jobs=1 //core:yolo
bazel run --jobs=1 //core:yoloRunning yolo opens the TUI and starts a persistent shell. Start an agent
inside it just as you would in any terminal:
Ctrl-B c new shell tab
Ctrl-B v split right
Ctrl-B n next tab
Ctrl-B s machine tree sidebar
Ctrl-B m switch an agent pane between Terminal and Chat
Ctrl-B d detach; shells and agents keep running
Reconnect with yolo attach, list terminals with yolo terminal list, or open the
terminal picker with yolo terminals.
curl -fsSL https://raw.githubusercontent.com/AgentsMesh/YoloShell/main/scripts/install.sh | shUpdate an installed binary from GitHub Releases:
yolo update # install and activate the latest release
yolo update --check # show the latest release without changing anything
yolo update --channel nightly # select the nightly channelyolo update installs a newer image, restarts the local Host and Hub when
needed, then probes live service admission. See
operations for the restart boundary.
The trusted web client is a separate plugin repository: AgentsMesh/YoloShellWeb. It is a Bun server plus a browser UI that projects the Hub catalogue, live xterm.js terminals, Chat history, typed interactions and terminal creation over an authenticated same-origin session.
yolo plugin install web.client --trust
yolo plugin startup
yolo plugin log web.clientplugin install resolves the versioned spec, verifies the pinned commit and
manifest, copies it into a private managed directory, and links only after the
explicit --trust preview. For a local checkout, use
yolo plugin link "$PWD/YoloShellWeb/client" --trust instead.
The plugin binds to the LAN and prints its URL. Open it and paste the token from the plugin's private data directory. Plain HTTP plus a bearer token is a trusted-LAN mode, not an internet-facing deployment. Browsers never receive the management socket, raw Hub ID, lease grant, creation capability or Hub token.
See the web client README and ADR 0024.
| Provider | Alpha status |
|---|---|
| Claude Code | Accepted target: detection, lifecycle, typed approvals and native resume |
| Codex | Accepted target: detection, lifecycle, approvals and native resume |
| Gemini CLI | Experimental adapter with hooks and native resume |
| Qwen Code | Experimental adapter with hooks and native resume |
| Grok Build | Experimental adapter with hooks and native resume |
Other terminal TUIs work as ordinary terminal programs. They do not get agent detection, status or native resume unless a provider adapter covers them. Yolo is independent and is not affiliated with these vendors.
Third-party extensions have one type: a trusted user-level plugin. A plugin has
a yolo-plugin.json manifest, is linked with yolo plugin link <dir> --trust,
and manages its own process, port and UI. Plugins are not sandboxed or approved
by the Hub; linking is the trust decision. Providers are not plugins.
Read the trusted plugin protocol and ADR 0023.
Start at the documentation index:
- Alpha contract and operations guide
- Architecture, concept model and single-executable contract
- Public JSON-RPC, client resources and conversation reads
- TUI interactions and terminal/agent lifecycle
- Architecture decision records
Bazel is the production build and test system; Cargo.toml is dependency
metadata only. See CONTRIBUTING.md for build, test,
conformance and live-acceptance commands. Every handwritten source and document
stays under 200 lines; committed build outputs and dependency directories are
forbidden.
Yolo is Alpha. The TUI supports Apple Silicon macOS 14.2+ and Linux aarch64/x86_64. Codex and Claude Code are the accepted agent targets for this Alpha; additional provider adapters are experimental. Linux remote deployment remains preview. Read the Alpha contract before depending on a recovery guarantee.
- Report bugs and propose focused changes through GitHub issues.
- Read SECURITY.md before reporting a vulnerability.
- Participation is governed by CODE_OF_CONDUCT.md.
Yolo is released under the MIT License. The separate web client and its vendored xterm.js assets retain their own notices; see THIRD_PARTY_NOTICES.md.