{"id":49104655,"url":"https://github.com/yeelam-gordon/agent-cli-session-tui","last_synced_at":"2026-05-09T04:02:54.238Z","repository":{"id":351973682,"uuid":"1213294343","full_name":"yeelam-gordon/agent-cli-session-TUI","owner":"yeelam-gordon","description":"A TUI for managing multiple AI agent CLI sessions (Copilot, Claude, Codex, Gemini, Qwen, Kimi). Free me from worrying about resumes or losing track  of what I was doing.","archived":false,"fork":false,"pushed_at":"2026-05-08T11:18:40.000Z","size":594,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T12:34:52.529Z","etag":null,"topics":["agent-cli","agent-management","agent-session-manager","agent-sessions","ai-agent-framework","session-manager","terminal-ui","tui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yeelam-gordon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-17T08:26:56.000Z","updated_at":"2026-05-08T11:18:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yeelam-gordon/agent-cli-session-TUI","commit_stats":null,"previous_names":["yeelam-gordon/agent-cli-session-tui"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/yeelam-gordon/agent-cli-session-TUI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeelam-gordon%2Fagent-cli-session-TUI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeelam-gordon%2Fagent-cli-session-TUI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeelam-gordon%2Fagent-cli-session-TUI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeelam-gordon%2Fagent-cli-session-TUI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yeelam-gordon","download_url":"https://codeload.github.com/yeelam-gordon/agent-cli-session-TUI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yeelam-gordon%2Fagent-cli-session-TUI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32806692,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-cli","agent-management","agent-session-manager","agent-sessions","ai-agent-framework","session-manager","terminal-ui","tui"],"created_at":"2026-04-21T01:03:56.314Z","updated_at":"2026-05-09T04:02:54.232Z","avatar_url":"https://github.com/yeelam-gordon.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent CLI Session TUI\n\nA terminal UI for managing agent CLI sessions — **Copilot CLI**, **Claude Code**, **Codex CLI**, **Qwen CLI**, **Gemini CLI**, **Kimi**, and extensible to others.\n\u003cimg width=\"2818\" height=\"1608\" alt=\"image\" src=\"https://github.com/user-attachments/assets/28922190-474b-4019-be01-45d291954fe9\" /\u003e\n\n## Pain Points Solved\n\n- **Where is my running agent?** — press `Enter` on any 🟡 Waiting or 🟢 Running session to instantly focus its terminal tab\n- **Too many tabs** — see all sessions in one view with clear status badges\n- **Which needs my input?** — 🟡 Waiting vs 🟢 Running vs 💤 Resumable at a glance\n- **Finding that one session** — `/` to search with tiered ranking: exact match → fuzzy word match → ✨ semantic similarity (optional). Now indexes head, tail, compaction summaries, and your own messages — names buried inside long conversations show up in results\n- **Hundreds of sessions piling up** — assign sessions to thematic groups with `g`, view by group via `Shift+Tab`. Optional [AI auto-suggest](#ai-auto-grouping) proposes groups for you\n- **Close without worry** — shut down any session anytime; all sessions are discoverable and resumable later\n- **Resume after reboot** — session summaries, last activity, full last response help you decide what to pick up\n- **One place for all agents** — manage Copilot, Claude, Codex, Qwen, Gemini sessions from a single TUI\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ TUI (ratatui + crossterm)                                   │\n│  Session List  │  Session Detail  │  Activity Log           │\n│  Search (exact → fuzzy → semantic)  │  Tab Focus            │\n├─────────────────────────────────────────────────────────────┤\n│ SessionViewModel (incremental merge, phased loading)        │\n│ Supervisor (tokio — parallel provider scans, non-blocking)  │\n│  Discovery · Process matching · Launch/Resume (config-driven)│\n├─────────────────────────────────────────────────────────────┤\n│ Provider plugins (data-only — read from each CLI's state)   │\n│  Copilot │ Claude │ Codex │ Qwen │ Gemini │ Kimi │ (more…) │\n├─────────────────────────────────────────────────────────────┤\n│ Shared infrastructure                                       │\n│  Process detection │ Semantic DLL (optional) │ Archive store │\n└─────────────────────────────────────────────────────────────┘\n```\n\nNo internal database. Providers read directly from each CLI's own state directory (read-only). All providers scan in parallel for fast refresh. The `SessionViewModel` merges results incrementally per-provider for progressive loading.\n\n### Session States\n\nAt a glance, every session shows one of three states:\n\n| Badge | State | Meaning |\n|-------|-------|---------|\n| 🟢 | **Running** | Agent is actively working |\n| 🟡 | **Waiting** | Agent finished — waiting for your input |\n| 💤 | **Resumable** | Session stopped — can be resumed anytime |\n\nPress `Enter` on Running/Waiting to jump to its terminal tab. Press `Enter` on Resumable to relaunch it.\n\n## Keybindings\n\n| Key | Action |\n|-----|--------|\n| `↑`/`↓` or `j`/`k` | Navigate sessions |\n| `Enter` (⏎) | Resume selected session — focuses the WT tab if Running, launches otherwise |\n| `n` | New session (launches default provider) |\n| `a` | Archive session (instantly hidden) |\n| `g` | Assign current session to a group (← → pick from existing, type to add new) |\n| `s` | Run AI grouping on the top ungrouped sessions (Grouped view) — see [AI Auto-Grouping](#ai-auto-grouping) |\n| `y` / `n` / `e` | Accept / dismiss / edit pending AI suggestion (cursor must be on a session with a 🤖 shadow) |\n| `/` | Search (type to filter, `↑`/`↓` to browse, `Enter` to resume, `Esc` to cancel) |\n| `Shift+Tab` | Cycle Active → Grouped → Hidden views |\n| `Tab` | Switch panel focus (works for all 5 providers) |\n| `PgUp`/`PgDn` | Scroll detail panel |\n| `Esc` | Cancel search |\n| `q` / `Ctrl+C` | Quit |\n\nNative mouse text selection works (click-drag to highlight and copy).\n\n## Supported Providers\n\n| Provider | State Dir | Session Format |\n|----------|-----------|----------------|\n| **Copilot CLI** | `~/.copilot/session-state/` | `workspace.yaml` + `events.jsonl` + lock files |\n| **Claude Code** | `~/.claude/projects/` | `\u003cencoded-cwd\u003e/\u003csession-id\u003e.jsonl` |\n| **Codex CLI** | `~/.codex/sessions/` | Session directories with state files |\n| **Qwen CLI** | `~/.qwen/projects/` | `\u003cencoded-cwd\u003e/chats/\u003csession-id\u003e.jsonl` |\n| **Gemini CLI** | `~/.gemini/tmp/` | `\u003cproject\u003e/chats/session-*.jsonl` + subdirs |\n| **Kimi** | `~/.kimi/sessions/` | Session JSONL files |\n\n## Configuration\n\nCopy `config.toml.example` next to the binary and rename to `config.toml`:\n\n```toml\ndata_dir = '~/.local/share/agent-session-tui'\npoll_interval_ms = 2000\nlog_max_lines = 500\n\n[providers.copilot]\nenabled = true\ndefault = true          # 'n' launches this provider\ncommand = \"copilot\"\ndefault_args = []\nstate_dir = '~/.copilot/session-state'\nresume_flag = \"--resume\"\nlaunch_method = \"wt\"    # \"wt\" | \"pwsh\" | \"cmd\"\nlaunch_fallback = \"cmd\" # optional — fallback if primary not found\n\n[providers.claude]\nenabled = true\ncommand = \"claude\"\ndefault_args = []\nstate_dir = '~/.claude/projects'\nresume_flag = \"--resume\"\nlaunch_method = \"wt\"\n```\n\nFor full control over launch commands, use custom launcher fields:\n\n```toml\n# Windows — open in a new Windows Terminal tab\nlaunch_cmd = \"wt\"\nlaunch_args = [\"-w\", \"0\", \"new-tab\", \"--startingDirectory\", \"{cwd}\", \"cmd\", \"/k\", \"{command}\"]\n\n# Linux/macOS — open in a new tmux window\n# launch_cmd = \"tmux\"\n# launch_args = [\"new-window\", \"-c\", \"{cwd}\", \"{command}\"]\n```\n\nPlaceholders: `{cwd}` → working directory, `{command}` → the agent CLI command.\n\nConfig search order: next to exe → `%APPDATA%/agent-session-tui/config.toml` → built-in defaults.\n\n## Semantic Search\n\nSearch uses a three-tier ranking system: **exact substring** → **fuzzy word** → **semantic similarity**. The semantic tier is an optional DLL plugin (`semantic_search.dll` / `.so` / `.dylib`) that adds meaning-aware matching using cached embeddings.\n\n- Results with a semantic boost show a ✨ indicator in the search list\n- Embeddings are pre-computed and cached per session — no embedding during search\n- Status bar shows 🧠 when the semantic plugin is loaded and ready\n- If the DLL is missing, search falls back gracefully to exact + fuzzy only\n\nThe plugin lives in `semantic-plugin/` and is built separately. See [`CONTRIBUTING.md` § Semantic Search Plugin](CONTRIBUTING.md#semantic-search-plugin) for the exact `cargo build` and copy-DLL-next-to-exe steps.\n\n## AI Auto-Grouping\n\nOptional. Asks an AI agent (GitHub Copilot CLI by default) to suggest thematic groups for your ungrouped sessions. **Off by default** — opt in via `config.toml`.\n\n### What it does\n\n- Sends each ungrouped session's **title, summary, and updated_at timestamp** (never file contents) to the AI in batches of 30.\n- The AI proposes a group name + score for each session, or skips it.\n- Suggestions render inline as a dim `· ⟨group⟩` shadow under the session row in the Active view.\n- Press `y` to accept, `n` to dismiss, or `e` to edit the group name before saving.\n\n### Two modes\n\n| Mode | How to trigger | What happens |\n|------|----------------|--------------|\n| **Manual** | `s` in Grouped view | One batch, results open in a popup so you can step through y/n/e |\n| **Auto** | `auto_suggest = true` in config | Runs in the background after the initial session load. Chains batches automatically until every ungrouped session has been analyzed. No popup — suggestions appear inline as shadows. |\n\n### Requirements\n\n- `copilot` CLI installed on PATH and authenticated (`copilot login`)\n- `prompts/group-suggest.md` template next to the binary (shipped in the release zip)\n\n### Configuration\n\n```toml\n[acp]\ncommand = \"copilot\"\nextra_args = [\"--effort\", \"low\"]   # ~30% faster than default; quality unchanged for this task\nauto_suggest = false               # set to true for background auto-suggest\ntimeout_secs = 180                 # bump if your model is slow\n# prompt_template = '~/.config/agent-session-tui/group-suggest.md'\n```\n\n### Cost \u0026 performance\n\n- ~25–45s per 30-session batch with `--effort low`\n- Each batch counts against your Copilot CLI usage quota\n- Auto-suggest chains batches: ~1 minute per 30 sessions until all are processed\n\n### Other group-view keys\n\n- `g` — assign the selected session to an existing group (← → to pick) or type a new one\n\nGroups are sorted by most-recent member activity, frozen on entry to the Grouped view to avoid jitter on the 2-second scan refresh. To refresh the order, leave and re-enter the view via `Shift+Tab`.\n\n## Release Packages\n\n| Package | Size | Contents |\n|---------|------|----------|\n| **Core** | ~1.1 MB | `agent-session-tui` binary only |\n| **Semantic** | ~26 MB | Core + `semantic_search_plugin` DLL |\n\nBuilt for **x64** and **arm64** across all three platforms (Windows, Linux, macOS).\n\n## Adding a Provider\n\nSee [`.github/instructions/plugin.instructions.md`](.github/instructions/plugin.instructions.md) for the full guide.\n\nImplement the `Provider` trait (data-only — no launch/resume logic needed):\n\n```rust\npub trait Provider: Send + Sync {\n    fn name(\u0026self) -\u003e \u0026str;\n    fn key(\u0026self) -\u003e \u0026str;\n    fn capabilities(\u0026self) -\u003e ProviderCapabilities;\n    fn discover_sessions(\u0026self) -\u003e Result\u003cVec\u003cSession\u003e\u003e;\n    fn match_processes(\u0026self, sessions: \u0026mut [Session]) -\u003e Result\u003c()\u003e;\n    // Optional: discover_sessions_paged(), session_detail(), activity_sources(),\n    //           infer_state(), tab_title()\n}\n```\n\nLaunch/resume/kill are handled by the framework from `config.toml`. Register your provider in `main.rs::create_provider()`.\n\n## Building\n\nRequires the **MSVC toolchain** on Windows (for the `windows` crate used by tab focus):\n\n```bash\nrustup override set stable-x86_64-pc-windows-msvc  # Windows only\ncargo build --release\n# Binary: target/release/agent-session-tui(.exe)\n```\n\n## Testing\n\n```bash\n# Unit tests only (runs on CI)\ncargo test --lib\n\n# All tests including provider integration tests (needs real session data)\ncargo test -- --nocapture\n\n# Specific provider\ncargo test --test copilot_lifecycle_test -- --nocapture\ncargo test --test claude_lifecycle_test -- --nocapture\ncargo test --test qwen_lifecycle_test -- --nocapture\ncargo test --test gemini_lifecycle_test -- --nocapture\ncargo test --test codex_lifecycle_test -- --nocapture\n```\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to get started — adding providers, building the semantic plugin, and code standards.\n\nFor project internals, design decisions, and AI agent context, see [`AGENTS.md`](AGENTS.md).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeelam-gordon%2Fagent-cli-session-tui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyeelam-gordon%2Fagent-cli-session-tui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyeelam-gordon%2Fagent-cli-session-tui/lists"}