{
  "markdown": "# WezTerm Agent Cards\n\nA Claude Code plugin that adds a curses-based sidebar to WezTerm showing your\nClaude Code sessions as stacked status cards with real-time state tracking.\n\nStrongly inspired by [CMUX](https://github.com/manaflow-ai/cmux), a native\nmacOS terminal that surfaces AI agent status through vertical tabs and\nnotification rings. WezTerm Agent Cards brings the same idea to Linux (and\nanywhere WezTerm runs) — using Claude Code hooks, a Python TUI, and a thin\nLua module instead of a dedicated terminal app.\n\n![status: working](https://img.shields.io/badge/status-working-brightgreen)\n![platform: linux](https://img.shields.io/badge/platform-linux%20%7C%20macOS-blue)\n![license: MIT](https://img.shields.io/badge/license-MIT-yellow)\n\n## What it does\n\n- Spawns a narrow sidebar pane in every WezTerm tab\n- Shows each tab as a card with project name and last output line\n- Cards change color based on Claude Code status:\n  - **Green** — working (running tools, generating)\n  - **Pink** — waiting (permission dialog, finished, notification)\n  - **Dim** — inactive (no Claude session)\n- Click a card or press Enter to switch tabs\n- Auto-exits when its sibling pane closes\n\n## How it works\n\nThe plugin has three layers:\n\n1. **Hooks** (`hooks/`) — Claude Code lifecycle hooks write per-pane status to\n   `/tmp/wezterm-hook-<pane_id>.json`. Subagent start/stop events maintain a\n   counter to prevent subagent activity from clobbering the main status.\n\n2. **Lua module** (`wezterm/init.lua`) — Registers WezTerm events to spawn the\n   sidebar in new tabs, bridge agent-deck state to a JSON file, and add\n   keybindings for tab/pane navigation.\n\n3. **Python TUI** (`wezterm/sidebar.py`) — Curses app that reads both status\n   sources and renders the card stack with click/keyboard navigation.\n\n### CMUX vs. Agent Cards\n\n| | CMUX | Agent Cards |\n|---|---|---|\n| Platform | macOS only | Linux, macOS, anywhere WezTerm runs |\n| Terminal | Custom (libghostty) | WezTerm split pane |\n| Rendering | Native AppKit | Python curses |\n| Agent detection | Terminal escape sequences + CLI hooks | Claude Code plugin hooks + agent-deck |\n| Extra features | Built-in browser, workspace persistence | Lightweight, no extra dependencies |\n\nBoth solve the same problem: when you run multiple Claude Code sessions in\nparallel, you need to see at a glance which ones need your attention.\n\n## Requirements\n\n- [WezTerm](https://wezfurlong.org/wezterm/)\n- [agent-deck](https://github.com/Eric162/wezterm-agent-deck) WezTerm plugin\n- Python 3 (for the sidebar TUI)\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)\n\n## Installation\n\n### 1. Clone the plugin\n\n```bash\nmkdir -p ~/.claude/plugins\ngit clone https://github.com/YOURUSER/wezterm-agent-cards.git \\\n  ~/.claude/plugins/wezterm-agent-cards\n```\n\n### 2. Enable the plugin\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n  \"enabledPlugins\": {\n    \"wezterm-agent-cards@wezterm-agent-cards\": true\n  }\n}\n```\n\n### 3. Load the Lua module in your wezterm.lua\n\n```lua\nlocal wezterm = require('wezterm')\nlocal config  = wezterm.config_builder()\n\n-- Load agent-deck (required for status bridge)\nlocal agent_deck = wezterm.plugin.require(\n  'https://github.com/Eric162/wezterm-agent-deck'\n)\n\n-- Load agent cards sidebar\nlocal agent_cards = dofile(\n  os.getenv('HOME') .. '/.claude/plugins/wezterm-agent-cards/wezterm/init.lua'\n)\n\n-- Your appearance config ...\n\n-- Apply sidebar\nagent_cards.apply_to_config(config, {\n  agent_deck   = agent_deck,\n  sidebar_cols = 26,\n})\n\n-- Apply agent-deck (detection only, sidebar handles rendering)\nagent_deck.apply_to_config(config, {\n  update_interval = 500,\n  notifications   = { enabled = false },\n  tab_title       = { enabled = false },\n})\n\nreturn config\n```\n\n### 4. Restart Claude Code and WezTerm\n\n- In Claude Code, run `/hooks` to verify the plugin's 8 hooks are registered.\n- Open WezTerm — the sidebar should appear in the initial tab.\n\n## Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `agent_deck` | `nil` | Agent-deck plugin reference. Required for the status bridge. |\n| `sidebar_cols` | `26` | Sidebar width in terminal columns. |\n| `hide_tab_bar` | `true` | Disable WezTerm's native tab bar (the sidebar replaces it). |\n| `webroot_names` | `{docroot, web, public, html}` | Folder names to skip when extracting project name from CWD. |\n\n## Keybindings\n\n| Key | Action |\n|-----|--------|\n| Ctrl+Shift+T | New tab with sidebar |\n| Ctrl+Shift+W | Close tab |\n| Ctrl+Shift+Up/Down | Previous/next tab |\n| Alt+1..9 | Jump to tab by number |\n| Ctrl+Shift+D | Split horizontal |\n| Ctrl+Shift+E | Split vertical |\n| Alt+Shift+Left/Right | Focus left/right pane |\n\n## Plugin structure\n\n```\nwezterm-agent-cards/\n├── .claude-plugin/\n│   └── plugin.json        # Claude Code plugin manifest\n├── hooks/\n│   ├── hooks.json         # 8 lifecycle hooks (auto-registered)\n│   └── status-hook.sh     # Per-pane status writer + subagent counter\n├── wezterm/\n│   ├── init.lua           # Lua module for WezTerm config\n│   └── sidebar.py         # Python curses TUI\n└── README.md\n```\n\n## How status detection works\n\nThe sidebar merges two data sources, with hooks taking priority:\n\n1. **Claude Code hooks** (primary) — fire on actual lifecycle events:\n   - `UserPromptSubmit` → working\n   - `PostToolUse` → working (with sticky guard when subagents active)\n   - `PermissionRequest` / `Notification` / `Stop` → waiting\n   - `SubagentStart` / `SubagentStop` → counter management\n   - `SessionEnd` → cleanup\n\n2. **agent-deck** (fallback) — pattern-matches terminal output to detect agent\n   state. Less reliable but provides status when hooks haven't fired yet.\n\n### Sticky \"waiting\" rule\n\nWhen subagents are active, `PostToolUse`'s \"working\" state cannot overwrite\n\"waiting\". This prevents a subagent's tool use from hiding a permission dialog\non the main agent. Only `UserPromptSubmit` (with force flag) or a new\nwaiting/cleanup event can clear it.\n\n## Acknowledgements\n\n- [CMUX](https://github.com/manaflow-ai/cmux) by Manaflow AI — the original\n  inspiration for surfacing agent status in a terminal sidebar\n- [agent-deck](https://github.com/Eric162/wezterm-agent-deck) — WezTerm plugin\n  for AI agent detection that provides the fallback status data\n\n## License\n\nMIT\n",
  "bytes": 6272,
  "sha": "6e84f69728334ecbf90a8b6b525c198b29da8fa6c860d7a92349ff88332fa3d9",
  "repo_slug": "wrock/wezterm-agent-cards",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_wrock_wezterm_agent_cards_wezterm_agent__f9632e04/readme"
}