opensessions: a tmux sidebar that tracks coding agent state
tmux sidebar for coding agents — Amp, Claude Code, Codex, OpenCode. Per-thread markers, local HTTP API, live session state.
At a glance
- What is it?
- opensessions adds a ratatui sidebar pane to tmux so you can see which agent thread finished, which errored, and which repo each session points at. It is useful if you already run agents in tmux panes and lose track of them. It is not a general terminal multiplexer replacement, and the README states zellij support exists but is not stable enough to document.
- Who is it for?
- Adopt opensessions if you already run Amp, Claude Code, Codex, or OpenCode inside tmux and want per-thread done, error, and interrupted markers without leaving the terminal. Skip it if you use zellij, since the README says that integration code is present but not stable enough to document as supported, or if you need a licence you can verify: the README badge says MIT but the repository metadata shows no licence.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 84 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: agent threads outlive your attention
Running several coding agents at once in tmux creates a specific failure. The panes keep working while you look elsewhere, and the only signal that a thread finished, errored, or was interrupted is text you have already scrolled past. opensessions targets that gap. It is a sidebar pane inside an existing tmux workflow, not a replacement for it, and the README frames it as one small pane for session switching, agent state, repo breadcrumbs, and quick jumps back into the right terminal. The audience is narrow and stated: people running Amp, Claude Code, Codex, or OpenCode inside tmux who also keep localhost tabs and multiple sessions open. If you run one agent in one window, the sidebar is overhead.
How the watchers read agent state
The mechanism is file watching plus a local server, not agent cooperation. 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 a SQLite database at ~/.local/share/opencode/opencode.db. Those four paths are the whole integration surface, which means the sidebar is only as accurate as the files each tool writes. Per-thread unseen markers cover done, error, and interrupted states. Session context in the UI includes the branch in the list, the working directory in the detail panel, thread names, and detected localhost ports. The sidebar itself is Rust with ratatui 0.30 and crossterm 0.29, backed by a local Rust WebSocket and HTTP server. Hidden sidebars are stashed in a tmux session named _os_stash so they can return without restarting the sidebar process.
Installing through TPM and what lands on disk
The documented path is TPM. Add set -g @plugin 'Ataraxy-Labs/opensessions' to ~/.tmux.conf, then run tmux source-file ~/.tmux.conf and ~/.tmux/plugins/tpm/bin/install_plugins. Open the sidebar with prefix o then s. TPM clones the repo into ~/.tmux/plugins/opensessions, and on first load opensessions downloads the matching prebuilt release bundle into bin/. That bundle contains opensessions-sidebar, opensessions-server, and lazydiff. curl or wget is required for that download. If your platform is unsupported, or you are developing locally, the README gives cd ~/.tmux/plugins/opensessions followed by cargo build --release. A single shell command is also documented that appends the plugin line if it is absent, sources the config, and runs the TPM installer. Updates go through prefix + U or ~/.tmux/plugins/tpm/bin/update_plugins opensessions, and the README states no local rebuild is needed for normal installs because the plugin restarts the server on update to pick up the new binary. Session ordering persists to ~/.config/opensessions/session-order.json.
The HTTP API is the part agents can drive themselves
Scripts and agents push metadata over HTTP on 127.0.0.1:7391 with no binary required. The README shows three calls. POST /set-status with a JSON body of session, text, and tone sets a status pill. POST /set-progress takes session, current, total, and label. POST /log takes session, message, source, and tone. The endpoint list also includes /clear-log and /notify. Tones are neutral, info, success, warn, and error, each with a distinct icon and color. The example uses session my-app, which implies the session string must match a tmux session name for the pill to attach to the right row. The README does not spell out what happens when the name does not match, so that is worth checking before wiring it into a long-running script. The full reference lives in docs/reference/programmatic-api.md.
Where opensessions gets in the way
The README is direct about one limitation: tmux is the only supported mux today, and the older zellij integration code in the repo is not stable enough to document as supported. The project is looking for maintainers to bring it back to that bar. That is a real boundary, not a roadmap item you can plan around. A second issue is layout. The sidebar occupies a pane, so it competes for horizontal space with whatever you are already splitting. The README offers prefix o then e for a sidebar-safe even-horizontal layout in the current window, which is a workaround rather than a fix. A third is versioning: the most recent release listed is v0.2.0-alpha.12 from 2026-06-07, so the prebuilt bundle you download is an alpha. The file-watching model also means state can lag or miss events if an agent tool changes its on-disk format, and nothing in the README describes a fallback when a transcript path is absent.
Uninstall is a script, and that tells you something
The README instructs you to run sh ~/.tmux/plugins/opensessions/integrations/tmux-plugin/scripts/uninstall.sh before removing the plugin files, because it cleans up tmux hooks, keybindings, sidebar panes, and environment variables that would otherwise persist and cause glitching. Then remove the plugin line from ~/.tmux.conf and run prefix + alt + u. A plugin that installs hooks and environment variables into your tmux config has a footprint beyond its own directory. If you keep a versioned tmux.conf, expect diffs from the install, and treat the uninstall script as the supported way back rather than deleting the plugin directory.
The alternative: plain tmux with your own status line
The obvious comparison is doing nothing beyond tmux itself. tmux already gives you session switching, window lists, and a status line you can script with #() commands. What it does not give you is per-thread unseen markers for agent states, because tmux has no concept of an agent thread. That is the gap opensessions fills, and it fills it by reading each agent's own files rather than by asking the agent to report in. The trade is that you inherit four format dependencies. If you only need to know which session is busy, a status-line command that greps the same transcript directories gets you most of the way with no extra pane and no server on port 7391. If you want the pill API, the port detection, and the detail panel, the sidebar is doing work you would otherwise write yourself.
Licence and upgrade cost
The README carries an MIT badge linking to opensource.org, but the repository metadata supplied here lists the licence as unknown. Treat that discrepancy as something to verify in the repository before you depend on it, and note that nothing here is legal advice. Upgrade cost is low by design: TPM update plus a tmux reload, with the server restarting itself and the release bundle re-downloaded if bin/ is missing or incomplete. The cost that is not low is the alpha version number. If you run this across a team, pin the release you have validated rather than tracking prefix + U blindly, and check CONTRACTS.md, which the README lists as the description of supported integration interfaces, before you build scripts against the HTTP endpoints.
Editorial conclusion
Adopt opensessions if you already run Amp, Claude Code, Codex, or OpenCode inside tmux and want per-thread done, error, and interrupted markers without leaving the terminal. Skip it if you use zellij, since the README says that integration code is present but not stable enough to document as supported, or if you need a licence you can verify: the README badge says MIT but the repository metadata shows no licence. Before rolling it out, open a session, run the curl call to http://127.0.0.1:7391/set-status with a tone of warn, and confirm the pill appears in the sidebar, then run sh ~/.tmux/plugins/opensessions/integrations/tmux-plugin/scripts/uninstall.sh and check that no tmux hooks or keybindings survive.
Community notes