https://github.com/indrasvat/shux
A modern take on tmux
https://github.com/indrasvat/shux
agents asciinema automation claude-code codex gemini iterm2 tmux
Last synced: about 1 month ago
JSON representation
A modern take on tmux
- Host: GitHub
- URL: https://github.com/indrasvat/shux
- Owner: indrasvat
- Created: 2026-02-19T03:00:05.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-16T07:20:15.000Z (about 1 month ago)
- Last Synced: 2026-05-16T09:40:41.190Z (about 1 month ago)
- Topics: agents, asciinema, automation, claude-code, codex, gemini, iterm2, tmux
- Language: Rust
- Homepage: https://shux.pages.dev
- Size: 8.03 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Roadmap: docs/roadmap.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
The terminal multiplexer built for AI coding agents
Typed API. Deterministic state. Zero wrappers needed.
---
## Why shux
Every AI agent orchestration tool today wraps tmux. They do it because no
multiplexer offers a typed API for programmatic control. shux is what tmux
would be if designed today: humans and agents are equal citizens, every
operation is available through both keyboard and JSON-RPC, state is always
queryable, deterministic, and streamable.
```bash
# As a human
shux # attach to last session, or create "default"
# As an agent — every CLI verb mirrors an RPC method 1:1.
# RPC dots become CLI spaces. No top-level shortcuts to memorize.
shux session create work # → session.create RPC
shux session list # → session.list
shux pane send-keys -s work --text 'j' # → pane.send_keys
shux rpc call --params @file # raw fallthrough for any method
```
## Install
The fastest path — pre-built binary for macOS and Linux (x86_64 / aarch64),
verified by SHA-256 and dropped into `~/.local/bin`:
```bash
curl -sSfL https://raw.githubusercontent.com/indrasvat/shux/main/install.sh | bash
```
Pin a version or change the install dir:
```bash
curl -sSfL https://raw.githubusercontent.com/indrasvat/shux/main/install.sh \
| bash -s -- --version v0.1.0 --dir ~/.bin
```
Or build from source:
```bash
git clone https://github.com/indrasvat/shux.git
cd shux
make install # → ~/.local/bin/shux
```
Requires Rust 1.93+ and a Unix-like OS (macOS, Linux). For dev setup, see
[`docs/development.md`](docs/development.md).
## Quickstart
```bash
shux # attach last session (TTY-only)
shux session create work # create + attach a named session
shux pane split -s work # split the active pane
shux pane snapshot -s work # PNG of the current frame
shux config init # scaffold ~/.config/shux/config.toml
```
Every command mirrors an RPC method: `shux session create` is the same
RPC as `session.create`. Drop to the raw form with
`shux rpc call session.create --params @spec.json` when you'd rather
write the payload in a file.
Inside the TUI, the prefix key is `Ctrl+Space` by default:
| Key | Action |
|---|---|
| `Ctrl+Space \|`/`-` | split vertical / horizontal |
| `Ctrl+Space h`/`j`/`k`/`l` | focus left / down / up / right |
| `Ctrl+Space z` | toggle zoom |
| `Ctrl+Space d` | detach |
| click any pane | focus it |
| drag a border | resize |
## Extend shux with a process plugin
A plugin is any executable that speaks shux's line-delimited
JSON-RPC dialect on stdin/stdout. It subscribes to bus events and can
call the same RPC methods you use from outside (`window.rename`,
`pane.send_keys`, `state.apply`, …). Any language — bash, python,
node — same trust model as a shell function.
```bash
shux plugin install ./my-plugin.sh # spawn, handshake, register
shux plugin list # what's running
shux plugin kill # graceful shutdown (2s) → SIGKILL
```
The smallest correct shape is
[`examples/plugins/hello/plugin.sh`](examples/plugins/hello/plugin.sh)
(~30 lines of bash). Full protocol is documented in
[`skills/shux/references/plugins.md`](skills/shux/references/plugins.md)
and the task design doc
[`docs/tasks/044a-process-plugins-v0.md`](docs/tasks/044a-process-plugins-v0.md).
## Documentation
Read in this order:
1. [**Quickstart for humans**](docs/users.md) — keybindings, status bar,
customization, dotfile integration
2. [**Quickstart for agents**](docs/agents.md) — typed JSON-RPC surface,
`ensure` semantics, event streaming, scripting patterns
3. [**Configuration**](docs/configuration.md) — `~/.config/shux/config.toml`
schema, hot reload, status-bar segments, starship integration
4. [**Architecture**](docs/architecture.md) — daemon model, the seven crates,
why each one exists, the patterns that hold it all together
5. [**Development**](docs/development.md) — dev setup, make targets, the L1–L4
testing strategy
6. [**Roadmap**](docs/roadmap.md) — what's done, what's next, milestone plan
7. [**Full PRD**](docs/PRD.md) — design philosophy, competitive analysis,
plugin WIT interfaces, performance budgets
## License
MIT