# opensessions: a tmux sidebar that tracks your coding agents

> opensessions is a Rust and ratatui sidebar for tmux that watches Amp, Claude Code, Codex and OpenCode transcripts, marks unseen thread states, and exposes a local HTTP API on port 7391 for agents to push status. It is for people already living in tmux with several agents running.

**Ataraxy-Labs/opensessions** — tmux sidebar for coding agents — Amp, Claude Code, Codex, OpenCode. Per-thread markers, local HTTP API, live session state.

- Repository: https://github.com/Ataraxy-Labs/opensessions
- Website: https://ataraxy-labs.com/#opensessions
- Stars: 1,230 · Forks: 75
- Language: Rust
- License: not declared
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/ataraxy-labs-opensessions

## The problem opensessions targets: too many agent sessions, no shared view

Running several coding agents at once turns tmux into a maze. Each agent lives in its own window or pane, each has its own transcript format, and the only signal that a thread finished, failed or was interrupted is whatever the agent prints before you look away. opensessions puts one narrow pane next to your work that answers three questions: which sessions exist, what state each agent thread is in, and where each session is rooted in the filesystem. The README frames it as a sidebar for when "your sessions, agents, and localhost tabs start multiplying", and it deliberately lives inside the existing tmux workflow rather than replacing it. The audience is narrow and specific: developers who already use tmux as their primary mux and who run Amp, Claude Code, Codex or OpenCode. If you run one agent in one terminal, the sidebar has nothing to summarize.

## How the sidebar learns agent state: four file watchers and a Rust server

There is no plugin protocol between opensessions and the agents. The sidebar reads what the agents already write to disk. According to the README, the Amp watcher reads `~/.local/share/amp/threads/*.json` and clears unseen state from Amp's `session.json` when a thread becomes seen there. The Claude Code watcher reads JSONL transcripts under `~/.claude/projects/`. The Codex watcher reads transcript JSONL files in `~/.codex/sessions/` or `$CODEX_HOME/sessions/` and resolves sessions from `turn_context.cwd`. The OpenCode watcher polls the SQLite database at `~/.local/share/opencode/opencode.db`. That design has a clear consequence: opensessions can only show what those tools persist, and a change to any of those on-disk formats breaks the corresponding watcher until the project follows it. The UI itself is a native Rust sidebar built with ratatui 0.30 and crossterm 0.29, and it talks to a local Rust WebSocket/HTTP server. Session ordering is persisted in `~/.config/opensessions/session-order.json`. Hidden sidebars are stashed in a tmux session named `_os_stash` so they can return without restarting the sidebar process. The workspace in Cargo.toml has four members: `apps/tui-rs`, `apps/server-rs`, `packages/runtime-rs` and `packages/sidebar-core-rs`, which matches the split between the pane, the server and the shared logic.

## Installing opensessions with TPM and opening the sidebar

The documented install path is TPM, the tmux plugin manager. The requirements listed in the README are tmux, TPM itself, and curl or wget for downloading prebuilt binaries on first load. Add the plugin line to your tmux configuration:

```tmux
set -g @plugin 'Ataraxy-Labs/opensessions'
```

Then reload tmux and let TPM install it. The README gives these two commands:

```bash
tmux source-file ~/.tmux.conf
~/.tmux/plugins/tpm/bin/install_plugins
```

TPM clones the repository into `~/.tmux/plugins/opensessions`. On first load, opensessions downloads the matching prebuilt release bundle into `bin/`; that bundle contains `opensessions-sidebar`, `opensessions-server` and `lazydiff`. Open the sidebar with `prefix o` followed by `s`. If your platform has no prebuilt bundle, or you are working from a local clone, the README says you can build from source with `cargo build --release` inside `~/.tmux/plugins/opensessions`. For local development the README also lists `cargo test`, `cargo run -p opensessions-sidebar` to start the sidebar outside tmux, and `cargo run -p opensessions-server` to start the server. The README also provides a one-line shell command that appends the plugin line to `~/.tmux.conf` if it is not already there, reloads tmux and runs the TPM installer, for people who want the same setup without editing the file by hand.

## Pushing your own status into the sidebar over HTTP

The part that is not just a viewer is the programmatic API. Scripts and agents can post metadata to the sidebar over HTTP on `127.0.0.1:7391`, and the README notes no binary is needed for this. The documented endpoints are `/set-status`, `/set-progress`, `/log`, `/clear-log` and `/notify`. A status pill is one POST:

```sh
curl -X POST http://127.0.0.1:7391/set-status \
  -H 'content-type: application/json' \
  -d '{"session":"my-app","text":"Deploying","tone":"warn"}'
```

Progress takes `current`, `total` and a `label`, and log entries take `message`, `source` and `tone`. The tones are `neutral`, `info`, `success`, `warn` and `error`, each with its own icon and color. This is the piece worth evaluating before anything else, because it is the difference between a status display and an integration point: a CI job or a wrapper script can tell the sidebar what it is doing without opensessions knowing anything about that tool. The full reference lives at `docs/reference/programmatic-api.md` in the repository. Note that the API is bound to localhost, so anything outside the machine needs its own path in.

## Where opensessions stops being the right tool

The README is direct about the biggest limitation: tmux is the only supported mux today. There is older zellij integration code in the repository, but the README states it is not stable enough to document as supported, and the project is looking for maintainers to bring it back to that bar. If your workflow is zellij, treat opensessions as unavailable rather than partially working. The second limitation is the watcher model. Everything the sidebar knows about agent state comes from files those agents write, so the sidebar is only as current and as correct as those files. The OpenCode watcher polls a SQLite database rather than watching a file, which the README does not describe in terms of interval or cost; if that matters to you, read `docs/explanation/architecture.md` before committing. Third, the project is still on an alpha line: the most recent release listed is v0.2.0-alpha.12 from 2026-06-07, and the last push to the repository was on 2026-06-23. That is three months before today, so this is not a project you should describe to colleagues as actively developed; check the repository for newer commits yourself. Fourth, the README does not document any rollback procedure for a bad update beyond reinstalling through TPM, and it does not describe what happens to the HTTP API when the server is restarted mid-request.

## opensessions compared with a plain tmux status line

The obvious alternative is not another sidebar product; it is the tmux status line plus a few shell scripts. A status line can show the current session name, the window list and whatever text you interpolate into it, and you can wire `run-shell` commands to print agent state. The difference in approach is where the state lives. A status line is a single line of text recomputed on an interval, with no per-thread history and no notion of unseen. opensessions keeps per-thread unseen markers for `done`, `error` and `interrupted` states, shows the branch in the session list and the working directory in the detail panel, and detects localhost ports, which a status line does not do without custom scripting. The trade is a pane of screen space and a long-running server process against a few lines of shell. If you only need to know which window is active, the status line wins. If you need to know which of nine agent threads finished while you were reading code, the sidebar is doing work a status line cannot express.

## Updating, uninstalling and the licence question

Updates go through TPM: `prefix + U`, or `~/.tmux/plugins/tpm/bin/update_plugins opensessions`. The README states no local rebuild is needed for normal installs, and that the plugin automatically restarts the server on update so it picks up the new binary. If the sidebar was open, toggle it back with `prefix o` followed by `s`. Uninstalling has an ordering constraint that is easy to get wrong. The README says to run the uninstall script before removing the plugin files, because it cleans up tmux hooks, keybindings, sidebar panes and environment variables that would otherwise persist and cause glitching:

```bash
sh ~/.tmux/plugins/opensessions/integrations/tmux-plugin/scripts/uninstall.sh
```

After that, remove the plugin line from `~/.tmux.conf` and run TPM's uninstall. On licensing, the README carries an MIT badge and links to the MIT text, and the repository has no separate LICENSE file listed among its top-level entries. That badge is the only licence statement in the repository's readme, so if you need certainty for a corporate policy check, confirm it against the repository directly rather than the badge image. Nothing here is legal advice.

## Conclusion

Adopt opensessions if you already run tmux and keep two or more coding agents alive in it, because the value comes entirely from the watchers reading Amp, Claude Code, Codex and OpenCode files you already have on disk. Do not adopt it if you use zellij as your mux: the README states the zellij integration code in the repo is not stable enough to document as supported. If you use another mux or a single agent in a single window, the sidebar adds a pane without adding information. Before installing, verify that your platform has a prebuilt release bundle, since the TPM path downloads one on first load and only falls back to cargo build --release when it does not.

## FAQ

### Does opensessions work with zellij or only with tmux?

Only tmux is supported today. The README says there is older zellij integration code in the repository, but it is not stable enough to document as supported, and the project is looking for maintainers to bring it back to that bar.

### Which coding agents does opensessions detect?

The README lists Amp, Claude Code, Codex and OpenCode. Each has its own watcher reading that tool's transcripts or database: Amp threads under ~/.local/share/amp/threads/, Claude Code JSONL under ~/.claude/projects/, Codex JSONL under ~/.codex/sessions/ or $CODEX_HOME/sessions/, and the OpenCode SQLite database.

### What is the opensessions local HTTP API for?

Scripts and agents use it to push custom metadata to the sidebar without needing a binary. The documented endpoints are /set-status, /set-progress, /log, /clear-log and /notify, served on 127.0.0.1:7391, and the reference is docs/reference/programmatic-api.md.

### What is an open session?

In this project, a session is an entry the sidebar lists, and opensessions tracks the state of each one across tmux. The README describes the sidebar as a place for session switching, agent state, repo breadcrumbs and quick jumps back into the right terminal.

### How do I install opensessions in tmux?

Add set -g @plugin 'Ataraxy-Labs/opensessions' to ~/.tmux.conf, then run tmux source-file ~/.tmux.conf and ~/.tmux/plugins/tpm/bin/install_plugins. TPM clones the repo and opensessions downloads a prebuilt release bundle into bin/ on first load.

## Sources

- [Ataraxy-Labs/opensessions on GitHub](https://github.com/Ataraxy-Labs/opensessions)
- [Issues](https://github.com/Ataraxy-Labs/opensessions/issues)
- [Project website](https://ataraxy-labs.com/#opensessions)
- [README](https://github.com/Ataraxy-Labs/opensessions/blob/main/README.md)
- [Releases](https://github.com/Ataraxy-Labs/opensessions/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ataraxy-labs-opensessions