Splinterm

A persistent, security-conscious terminal substrate for humans and bounded automation.

Website · Documentation · Beta 1 release notes · Quickstart · Product roadmap · Current status

Splinterm combines a native Wayland terminal with a headless daemon that keeps shells, layouts, and terminal state alive when graphical clients disconnect. Close a window, come back later, and the work is still running.

Humans use that persistent topology through native windows, tabs, and panes. Authorized tools can reach the same sessions through bounded JSON/NDJSON, SSH relay, and MCP interfaces. Splinterm is built in Rust from Foot's terminal behavior and designed first for Omarchy and Arch Linux.

splinterd owns the terminal processes, layouts, and session metadata. A Wayland window is a disposable view into that state—not the owner of it. Detaching a client does not end the work beneath it.

Native windows, the human CLI, structured clients, the SSH relay, and the MCP adapter all operate on the same persistent sessions. Automation does not live in a separate, less capable terminal world.

Automation is constrained by exact executable identity, explicit scopes, bounded resources and messages, controller ownership, consent, revocation, and body-free audit metadata. Terminal output remains untrusted data; it cannot grant authority or become an automatic instruction.

Foot is Splinterm's behavioral foundation, not just visual inspiration. The terminal kernel is a Rust translation grounded in a pinned Foot implementation, with provenance retained in THIRD_PARTY.md.

For limitations and release gates, read Current status. Exact image support is documented in docs/images.md.

The validated installation target is x86_64 Omarchy/Arch Linux with native Wayland. The recommended AUR packages download verified prebuilt binaries and do not compile locally:

yay -S splinterm-bin
# Optional policy-scoped MCP adapter:
yay -S splinterm-mcp-bin

The source-built alternatives are splinterm and splinterm-mcp. paru may be used instead of yay. All packages remain beta software with no stable compatibility or support-duration guarantee.

For the newest published versioned release package, clone the public repository and run:

git clone https://github.com/OldJobobo/splinterm.git
cd splinterm
./install.sh

The release installer selects the newest published SemVer v… release, verifies its GitHub-recorded manifest digest and package checksums, preserves an emergency binary snapshot, installs through Pacman, and verifies the packaged client identity. The snapshot supports diagnosis and manual recovery; it is not a package-consistent rollback. GitHub CLI authentication is optional, and anonymous public downloads are supported.

To build and package the current committed checkout locally, run the installer from Foot or another terminal not owned by splinterd:

./install.sh --source

Add --check to run the complete package test suite. The installer deliberately packages a clean committed HEAD; it does not include uncommitted worktree changes.

Installation does not change your default terminal, edit Omarchy or Hyprland configuration, enable systemd user lingering, or install the optional MCP package on a fresh system. After installation, splinterm integration omarchy enable explicitly configures the complete reversible user-level default-terminal, terminal-tag, and screensaver integration. Trusted graphical authority requires the client to be the exact device/inode sibling adjacent to the running /usr/bin/splinterd. After an upgrade replaces /usr/bin/splinterm, close and reopen every existing Splinterm window: an already-running client retains the old inode and is no longer the trusted sibling.

Read the complete installation guide.

Open a fresh terminal from the installed desktop entry or the XDG terminal launcher:

splinterm-xdg-terminal-exec

A commandless desktop/XDG launch creates a persistent Lair with one Dojo and one Splint. Closing its window detaches the graphical client while splinterd keeps the session running. When another application asks the XDG terminal to host a command, Splinterm instead creates a transient client-bound Lair: command exit or owner-window disconnect terminates its processes and removes it from topology. Native splinterm launch -- COMMAND... remains persistent.

Return through the native Dojo picker:

splinterm dojos   # choose a running Dojo or start a new terminal
splinterm reopen  # reopen the last locally remembered running Dojo

splinterm sessions remains a compatibility alias for splinterm dojos.

Inside a managed Splinterm window, these controls cover the essential workflow:

The optional omarchy-tmux profile adds familiar Ctrl+Space / Ctrl+B prefixes, searchable Prefix+? resolved-key help, Prefix+[ vi copy mode, and Prefix Shift+S/F/V/O for Save, pin toggle, Preview, and Restore of the current Lair. In copy mode, navigate with vi keys or arrows, press v to select, y to publish to the Wayland clipboard, or Escape to cancel. Outside copy mode, Ctrl+Shift+C/V provide compositor-safe terminal copy/paste; Super+C/V and Omarchy's Ctrl+Insert/Shift+Insert translation remain aliases. Splinterm-owned fields additionally provide bounded local selection, cut, and undo without claiming universal terminal Super+X/Z. Packaged atomic Dojo presets and optional collision-safe Bash helpers cover the standard Omarchy t, tdl, tds, tdlm, and tsl workflows under Splinterm's separate s* shell namespace.

Reopening attaches to processes that are still running. Starting an exited process again from saved launch metadata is an explicit restore operation.

Continue with the quickstart, repository human usage guide, or website Dojos and persistence.

                         native windows
                    ┌──────────┴──────────┐
                    │ disposable views    │
                    └──────────┬──────────┘
                               │ attach / detach
                         ┌─────▼─────┐
                         │ splinterd │
                         └─────┬─────┘
                               │ owns
Topology
└── Lair: project or persistent session
    ├── Dojo: terminal layout
    │   ├── Splint: shell or process
    │   └── Splint: shell or process
    └── Dojo: another layout
        └── Splint: shell or process

• Topology — the daemon's complete persistent session catalog.
• Lair — a named project or persistent session.
• Dojo — one persistent terminal layout inside a Lair.
• Splint — an individual terminal pane and process lifecycle.
• Window — a native Wayland view that may display multiple Dojos as local tabs.

Window and tab lifetimes are separate from Dojo and Splint lifetimes. Closing a view detaches it; terminating a process is an explicit, guarded action.

Read Core concepts for the user model or docs/architecture.md for system ownership and boundaries.

Splinterm exposes a deliberately bounded automation surface rather than making its private daemon protocol public:

• JSON/NDJSON CLI for versioned one-shot operations and subscriptions.
• SSH stdio relay for remote automation without a network listener in splinterd.
• Native remote client for a profile-bound graphical workflow over an authenticated relay.
• MCP adapter as an optional, separately packaged and policy-identified integration.

Machine access does not inherit human graphical authority and remains governed by automation policy. Native remote Windows are different: OpenSSH authenticates the human account, and the installed graphical relay receives normal terminal-multiplexer authority without automation policy.

Authoritative references:

• docs/automation.md — public JSON/NDJSON contracts, policy, and exit behavior
• docs/remote.md — SSH relay, remote profiles, and authority boundaries
• docs/mcp.md — MCP installation, policy, and host setup
• docs/integrations.md — integration-author checklist and safe client workflows
• dist/schemas/v2/ — checked-in public machine schemas

Splinterm uses ${XDG_CONFIG_HOME:-~/.config}/splinterm/config.ini for its focused configuration surface. It supports fonts and sizing, shell behavior, scrollback, cursor settings, pane chrome, keymap overlays, and explicit theme overrides.

On Omarchy, Splinterm reads the active theme's effective foot.ini and colors.toml and safely reloads valid palette changes without restarting the daemon or shell. When main.font is unset, graphical clients also follow fontconfig's effective monospace family live; explicit font patterns remain user-owned, and invalid live generations retain the last valid font without restarting the Window or its processes.

See the configuration guide for supported keys, keymap inspection, Omarchy integration, and Foot migration.

Specialist contracts and design records remain in docs/. Plans, spikes, benchmarks, and retained artifacts are development history and evidence—not the primary user guide.

Splinterm is a Rust workspace. The normal non-graphical validation is:

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

For an isolated development daemon and client:

./splinterm-test          # build, start or reuse the test daemon, and open Splinterm
./splinterm-test restart  # rebuild and restart after daemon or protocol changes
./splinterm-test ping     # build and verify the isolated daemon
./splinterm-test stop     # stop the isolated daemon

Read CONTRIBUTING.md and the development guide before changing domain, protocol, renderer, or Foot-derived behavior.

Splinterm's emulator half is derived from Foot's architecture and behavior. Translated or adapted code records its source provenance and retains the relevant MIT attribution. See docs/adr/0001-foot-rust-port.md and THIRD_PARTY.md.

If Splinterm is useful to you, you can support its continued development on Ko-fi.

Splinterm is available under the MIT License.