Agent Session Manager
Native GTK4/libadwaita terminal workspace for AI coding agents. Run Claude Code and Cursor side by side in spaces, tabs, and split panes; see at a glance which agent is working, blocked, or done; and resume any past session.
Unofficial community tool. An independent community project, not affiliated with or endorsed by any agent vendor (including Anthropic) or by herdr. It never modifies your agents' own session data — all app state lives in its own config file.
The workspace model and look are inspired by herdr, a terminal workspace manager for coding agents.
Features
- Spaces: every project folder with open tabs is a space, listed in the sidebar with its git branch. Tabs belong to their space; the tab strip's + starts another agent in the same folder.
- Agents & states: every running agent with a status dot — working, blocked (waiting on an approval or a question), done (finished while you weren't looking), or idle — rolled up to its space. Detected from Claude Code's terminal title and screen and from Cursor's prompts (a simplified port of herdr's detection rules). Desktop notifications fire when an agent you aren't watching finishes or needs you.
- Split panes: shell panes next to the agent, split right or down, with focus moves, zoom, and close.
Ctrl+Bprefix with herdr's default keys for panes, tabs, spaces, the sidebar, and preferences;Ctrl+B ?lists them. Go to agent (Ctrl+B g) jumps to any running agent, filterable by state.- History: every past session on disk (for Claude Code, under
~/.claude/projects/), grouped by project with a Favorites group, a search box, waiting / interrupted badges, live updates, and a quick switcher (Ctrl+Shift+K). Click a session to resume it in a tab. - Names, favorites, emoji: rename sessions, star them, and put one emoji on a tab (
Ctrl+.or click the tab's emoji). All of it lives in~/.config/agent-session-manager/state.json. - Terminals: each tab is an embedded VTE terminal running your
$SHELLwith the agent's command, in the project folder. Closing a tab asks the agent to exit cleanly (Claude Code's/exit) first. In-terminal search (Ctrl+Shift+G);Shift+Enterinserts a newline in the agent's prompt. - Right-click a session for the full action set: open, open in Ghostty, fork, continue in chat, rename, favorite, details (messages/models/tokens, a peek at recent messages, MCP servers and usage), replay, copy session ID, export as Markdown, reveal the transcript, hide, trash, or delete permanently. Select mode handles many sessions at once.
- Look: a terminal-workspace style in Catppuccin by default (matching herdr), with Tokyo Night, Gruvbox, Nord, Dracula, and more as variants coloring the whole window — or the Classic (Adwaita) style.
- Sidebar sections (spaces, agents, history) fold with a click on their title and can be switched off in Preferences.
- Also: multiple windows, Claude Code and Cursor side by side, advanced new-session options (model, permission mode, extra directories, continue), an MCP servers browser, native streaming chat with permission cards, and session replay.
Keyboard shortcuts
| Shortcut | Action |
|---|---|
Ctrl+B, then a key |
Prefix commands (v/- split, hjkl move, z zoom, x close pane, c new agent, n/p tabs, g go to agent, ? help…) |
Ctrl+Shift+T |
New session |
Ctrl+Shift+N |
New window |
Ctrl+Shift+W |
Close current tab |
Ctrl+Tab / Ctrl+PgDn |
Next tab in this space (with Shift / PgUp: previous) |
Ctrl+Shift+K |
Quick switcher (jump to any session) |
Ctrl+Shift+F |
Focus the history search |
Ctrl+. |
Pick an emoji for the current tab |
Ctrl+Shift+E |
Toggle 😊 on the current tab |
Ctrl+Shift+C / Ctrl+Shift+V |
Copy / paste in terminal |
Ctrl+Shift+G |
Find in terminal |
F9 |
Toggle sidebar |
Ctrl+, |
Preferences |
Requirements
Python ≥ 3.10, GTK 4, libadwaita ≥ 1.5, VTE (GTK 4 build), PyGObject — from your distro's packages:
# Ubuntu / Debian
sudo apt install python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 gir1.2-vte-3.91
# Fedora
sudo dnf install python3-gobject gtk4 libadwaita vte291-gtk4
# Arch
sudo pacman -S python-gobject gtk4 libadwaita vte4
Plus a supported agent's CLI on your PATH — the claude CLI and/or cursor-agent.
Installing with
pipx? PyGObject comes from the system, so usepipx install --system-site-packages agent-session-manager-gtk.
Install
Ubuntu — PPA:
sudo add-apt-repository ppa:matemiller992/agent-session-manager
sudo apt update && sudo apt install agent-session-manager
Arch — AUR: yay -S agent-session-manager
Any distro — pipx: pipx install --system-site-packages agent-session-manager-gtk
Debian/Ubuntu — .deb package (from the latest release):
sudo apt install ./agent-session-manager_*_all.deb
Dependencies are pulled in automatically; the app appears in your app grid as "Agent Session Manager".
From source:
git clone https://github.com/r4nd3l/agent-session-manager.git
cd agent-session-manager
python3 -m claude_session_manager
Or install the desktop launcher + icon (shows up in the app grid as "Agent Session Manager"):
./data/install.sh
Terminal shortcuts: Ctrl+Shift+C copy, Ctrl+Shift+V paste.
Layout
claude_session_manager/
├── app.py # Adw.Application entry point + base CSS
├── window.py # main window: spaces, tabs, Ctrl+B prefix, actions
├── spaces.py # spaces / agents sidebar panel and per-space tab strip
├── panes.py # split panes inside a tab
├── agentstate.py # working / blocked / idle detection
├── sidebar.py # the history list
├── store.py # session discovery off the main thread, file monitors
├── sessions.py # transcript discovery + statistics
├── providers.py # per-agent adapters (Claude Code, Cursor)
├── state.py # persistent app state (names, favorites, hidden, settings)
├── themes.py # color themes + the terminal-workspace stylesheet
├── prefs.py # preferences dialog
└── terminal.py # VTE terminal tab spawning the agent CLI
data/
├── io.github.r4nd3l.AgentSessionManager.desktop # launcher template
├── icons/io.github.r4nd3l.AgentSessionManager.svg # app icon
└── install.sh # install launcher + icon for current user
scripts/
├── build_deb.sh # build the .deb package into dist/
└── make_demo_data.py # fake sessions for screenshots/demos
Publishing (maintainers)
Releases are one step: push a v* tag. .github/workflows/release.yml then
builds the wheel/sdist and the .deb, creates the GitHub Release (with the
.deb attached and auto-generated notes), and publishes to
PyPI via trusted
publishing (OIDC — no API tokens).
# bump version in pyproject.toml / __init__.py / debian/changelog, commit, then:
git tag -a v1.1.0 -m v1.1.0 && git push origin v1.1.0
PyPI trusted-publisher setup expects workflow release.yml (owner r4nd3l,
repo agent-session-manager). The AUR and PPA are updated separately
(see packaging/).
Roadmap
- Agents (not just shells) in split panes, with their own state
- Persistent spaces and layouts across restarts
- More provider adapters beyond Claude Code and Cursor
- Flathub
Metadata
Release files for agent-session-manager-gtk 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_session_manager_gtk-1.1.0.tar.gz | 112.6 kB | With provenance | Details for agent_session_manager_gtk-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_session_manager_gtk-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for agent_session_manager_gtk-1.1.0-py3-none-any.whl |
Total release size: 240.5 kB
Release files / agent_session_manager_gtk-1.1.0.tar.gz
| Download URL | agent_session_manager_gtk-1.1.0.tar.gz |
|---|---|
| Size | 112.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
909ff9ec572123222e1cdc9cbe45ef6277b8b40d591062dad9e037d489766ad7
|
|
BLAKE2b-256 checksum How to use checksums |
98026b3caef1ef66d3ac30f380311cafc4fd0e2ddb91cb93cfd11574dfbf17c5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logRelease files / agent_session_manager_gtk-1.1.0-py3-none-any.whl
| Download URL | agent_session_manager_gtk-1.1.0-py3-none-any.whl |
|---|---|
| Size | 127.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2f21258ac42079dfee7df408c92f7b37df303e426c54ff839c6b15a642749f63
|
|
BLAKE2b-256 checksum How to use checksums |
6028da9aee2aaaea1a58580fa5debb5f11e15cf1476899103d7639582d1df89c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logSecurity for agent-session-manager-gtk 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_session_manager_gtk-1.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.