agent-session-manager

Agent Session Manager (ASMGR)

A powerful terminal UI (TUI) application for managing multiple AI coding assistant CLI sessions using tmux. Inspired by Claude Squad.

Supported AI Agents

• Claude Code - Anthropic's CLI coding assistant
• Gemini CLI - Google's AI assistant
• Aider - AI pair programming in your terminal
• OpenAI Codex - OpenAI's coding assistant
• Amazon Q - AWS AI coding companion
• OpenCode - Open-source AI coding assistant
• Custom - Any CLI command you want to manage

Features

• Projects/Workspaces - Organize sessions into separate projects with isolated session lists
• Single Instance Lock - Only one instance of ASMGR can run per project at a time
• Multi-Agent Support - Run Claude, Gemini, Aider, Codex, Amazon Q, OpenCode, or custom commands
• Multi-Session Management - Run and manage multiple AI sessions simultaneously
• Live Preview - Real-time preview of agent output with ANSI color support
• Session Resume - Resume previous Claude conversations from any project (Claude-specific)
• Activity Indicators - Visual indicators showing active vs idle sessions
• Custom Colors - Personalize sessions with foreground colors, background colors, and gradients
• Prompt Sending - Send messages to running sessions without attaching
• Session Reordering - Organize sessions with keyboard shortcuts
• Compact Mode - Toggle spacing between sessions for denser view
• Smart Resize - Terminal resize follows when attached, preview size preserved when detached
• Overlay Dialogs - Modal dialogs rendered over the main view with proper Unicode character width handling
• Fancy Status Bar - Styled bottom bar with highlighted keys, toggle indicators, and separators
• Rich Help View - Comprehensive help page with keyboard shortcuts and detailed descriptions (F1 or ?)
• Session Groups - Organize sessions into collapsible groups for better organization

Installation

Prerequisites

• Go 1.24 or later
• tmux
• At least one AI CLI tool installed:
  • Claude Code
  • Gemini CLI
  • Aider
  • OpenAI Codex
  • Amazon Q
  • OpenCode

Build from Source

git clone https://github.com/izll/agent-session-manager.git
cd agent-session-manager
go build -o asmgr .

Install to PATH

# Linux/macOS
cp asmgr ~/.local/bin/
# or
sudo cp asmgr /usr/local/bin/

Usage

Simply run:

asmgr

Keyboard Shortcuts

Navigation

Session Actions

Groups

Customization

Projects

Other

Inside Attached Session

Note: Ctrl+q is set as a universal quick-detach for all tmux sessions. ASM sessions get automatic resize before detach to maintain proper preview dimensions.

Color Customization

Press c to open the color picker for the selected session:

• Foreground Colors - 22 solid colors + 15 gradients
• Background Colors - 22 solid colors
• Auto Mode - Automatically picks contrasting text color
• Full Row Mode - Extend background color to full row width (press f to toggle)
• Gradients - Rainbow, Sunset, Ocean, Forest, Fire, Ice, Neon, Galaxy, Pastel, and more!

Use Tab to switch between foreground and background color selection.

Session Resume

ASM can resume previous Claude Code conversations:

1. Press r on any session
2. Browse through previous conversations (shows last message and timestamp)
3. Select a conversation to resume or start fresh

Session Groups

Organize your sessions into collapsible groups:

📁 Backend ▼ [3]
   ● api-server
   ● database-worker
   ○ cache-service
📁 Frontend ▶ [2]  (collapsed)
   ● misc-session

• Press g to create a new group
• Press G to assign the selected session to a group
• Press → to expand a group, ← to collapse it
• Press Tab to toggle collapse/expand
• Press e on a group to rename it
• Press c on a group to change its color
• Press d on a group to delete it (sessions become ungrouped)

Sessions without a group appear at the bottom of the list.

Projects

Projects allow you to organize your sessions into separate workspaces. Each project has its own isolated session list and groups.

Project Selector

When you start ASMGR, you'll see the project selector:

┌─────────────────────────────────────┐
│  Agent Session Manager              │
│             v0.3.0                  │
├─────────────────────────────────────┤
│  > Backend API         [5 sessions] │
│    Frontend App        [3 sessions] │
│    DevOps Scripts      [2 sessions] │
│  ───────────────────────────────────│
│    [ ] Continue without project     │
│    [+] New Project                  │
└─────────────────────────────────────┘

• Select an existing project to work with its sessions
• Choose "Continue without project" for backward-compatible default sessions
• Create a new project to start fresh

Single Instance Lock

Only one instance of ASMGR can run per project at a time. If you try to open a project that's already open in another terminal, you'll see an error with the PID of the running instance.

Session Import

Press i in the project selector to import sessions from the default (no project) session list into the selected project. This is useful when migrating from the old single-session-list mode to the new project-based organization.

Activity Indicators

Sessions show different status indicators:

• ● Orange - Active (agent is working)
• ● Gray - Idle (waiting for input)
• ○ Red outline - Stopped

Configuration

Configuration files are stored in ~/.config/agent-session-manager/:

~/.config/agent-session-manager/
├── projects.json              # Project list & metadata
├── sessions.json              # Default (no project) sessions
└── projects/
    ├── backend-api/
    │   └── sessions.json      # Project-specific sessions
    └── frontend-app/
        └── sessions.json

projects.json

Stores the list of projects with their names and creation dates.

sessions.json

Stores sessions and groups:

• Session: name, path, color settings, resume ID, auto-yes, group, agent type
• Group: name, collapsed state, color settings

filters.json (optional)

Customize status line filtering for each agent. Default filters are built-in, but you can override them:

{
  "claude": {
    "skip_contains": ["? for", "Context left"],
    "skip_prefixes": ["╭", "╰"],
    "min_separators": 20
  },
  "opencode": {
    "skip_contains": ["ctrl+?", "Context:"],
    "content_prefix": "┃",
    "show_contains": ["Generating"],
    "show_as": ["Generating..."]
  }
}

Architecture

agent-session-manager/
├── main.go              # Entry point
├── session/             # Session management & tmux integration
│   ├── instance.go      # Instance lifecycle & PTY handling
│   ├── storage.go       # Persistence & project management
│   ├── project.go       # Project data structures
│   └── claude_sessions.go  # Claude session discovery
└── ui/                  # Bubbletea TUI
    ├── model.go         # Core model, constants, Init, Update
    ├── handlers.go      # Keyboard input handlers
    ├── views.go         # View rendering functions
    ├── colors.go        # Color definitions & gradients
    ├── styles.go        # Lipgloss style definitions
    └── helpers.go       # ANSI utilities & overlay dialog rendering

Dependencies

• Bubble Tea - TUI framework
• Lip Gloss - Style definitions
• Bubbles - TUI components
• go-runewidth - Unicode character width calculation for overlay dialogs

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Acknowledgments

• Inspired by Claude Squad
• Built with Charm libraries
• Powered by Claude Code