{"id":45739243,"url":"https://github.com/accessd/tmux-agent-indicator","last_synced_at":"2026-02-27T12:01:43.733Z","repository":{"id":338494683,"uuid":"1158010253","full_name":"accessd/tmux-agent-indicator","owner":"accessd","description":"Tmux plugin that gives visual feedback for AI agent states (running/needs-input/done). Supports   Claude Code, Codex, and custom agents. Pane borders, window title colors, status bar icons.","archived":false,"fork":false,"pushed_at":"2026-02-22T13:41:33.000Z","size":3762,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-22T18:52:44.883Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","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/accessd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-02-14T16:51:33.000Z","updated_at":"2026-02-22T13:41:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/accessd/tmux-agent-indicator","commit_stats":null,"previous_names":["accessd/tmux-agent-indicator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/accessd/tmux-agent-indicator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/accessd%2Ftmux-agent-indicator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/accessd%2Ftmux-agent-indicator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/accessd%2Ftmux-agent-indicator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/accessd%2Ftmux-agent-indicator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/accessd","download_url":"https://codeload.github.com/accessd/tmux-agent-indicator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/accessd%2Ftmux-agent-indicator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29893566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T09:48:51.284Z","status":"ssl_error","status_checked_at":"2026-02-27T09:48:43.992Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-02-25T13:00:19.263Z","updated_at":"2026-02-27T12:01:43.726Z","avatar_url":"https://github.com/accessd.png","language":"Shell","funding_links":[],"categories":["Plugins"],"sub_categories":[],"readme":"# tmux-agent-indicator\n\nAI agents run in tmux panes but give no signal when they finish or need input. You have to keep switching panes to check. This plugin tracks agent state and surfaces it through pane borders, window titles, and status bar icons so you never miss a transition.\n\n## Demo\n\nhttps://github.com/user-attachments/assets/b6b6b466-4b42-4d45-85aa-b9b659e4bafe\n\nWhen the agent finishes, the window title background/foreground changes and the pane border updates to signal completion.\n\n| ![needs-input](docs/images/needs-input.png) | ![done](docs/images/done.png) | ![done-pane-bg](docs/images/done-pane-bg.png) |\n|:---:|:---:|:---:|\n| needs-input: yellow window title | done: red window title | done: pane background change |\n\n## How it works\n\nThe plugin tracks three states per pane: `running`, `needs-input`, and `done`.\n\nState transitions are driven by hooks. Claude Code fires hooks on prompt submit, permission request, and stop. Codex uses its `notify` command. OpenCode uses its plugin system. Any other agent can call `agent-state.sh` directly from a wrapper script or hook.\n\nEach state can change:\n- Pane border color\n- Pane background (supported but disabled by default to avoid visual noise)\n- Window title background and foreground\n- Status bar icon (per-agent, e.g. `claude=🤖`, `codex=🧠`)\n\nStates reset when you focus the pane/window, or on the next transition.\n\n## Features\n\n- Per-agent status icons in the status bar\n- Knight Rider animation during `running` state\n- Deferred pane reset: keep pane colors until focus, not when the hook fires\n- Process detection fallback for agents that don't fire hooks\n- Tmux display-message notifications on state transitions\n\n## Requirements\n\ntmux 3.0+, bash 4+\n\n## Installation\n\n### One-command installer (recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/accessd/tmux-agent-indicator/main/install.sh | bash\n```\n\nThe installer will offer to run the interactive color setup wizard. You can also run it later:\n\n```bash\nbash ~/.tmux/plugins/tmux-agent-indicator/setup.sh\n```\n\nThis installs files to `~/.tmux/plugins/tmux-agent-indicator` and updates:\n- `~/.claude/settings.json` hooks for Claude (`UserPromptSubmit`, `PermissionRequest`, `Stop`)\n- `~/.codex/config.toml` `notify` command for Codex\n- `~/.config/opencode/plugins/` plugin for OpenCode\n\nIntegration uninstall options:\n\n```bash\n./install.sh --uninstall-claude\n./install.sh --uninstall-codex\n./install.sh --uninstall-opencode\n```\n\n### TPM\n\nAdd to ~/.tmux.conf:\n\n```tmux\nset -g @plugin 'accessd/tmux-agent-indicator'\n```\n\nReload tmux:\n\n```bash\ntmux source-file ~/.tmux.conf\n```\n\n## Status Bar Integration\n\nFor native status:\n\n```tmux\nset -g status-right '#{agent_indicator} | %H:%M'\n```\n\nFor [minimal-tmux-status](https://github.com/niksingh710/minimal-tmux-status):\n\n```tmux\nset -g @minimal-tmux-status-right '#{agent_indicator} #(gitmux \"#{pane_current_path}\")'\n```\n\n## Configuration\n\nQuick start with the most useful options:\n\n```tmux\n# Enable/disable visual channels\nset -g @agent-indicator-border-enabled 'on'\nset -g @agent-indicator-indicator-enabled 'on'\n\n# Per-agent icons\nset -g @agent-indicator-icons 'claude=🤖,codex=🧠,opencode=💻,default=🤖'\n\n# Keep pane colors until you focus the pane (instead of clearing immediately)\nset -g @agent-indicator-reset-on-focus 'on'\n\n# Knight Rider animation while running\nset -g @agent-indicator-animation-enabled 'on'\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eFull configuration reference\u003c/summary\u003e\n\n```tmux\n# Global toggles\nset -g @agent-indicator-background-enabled 'on'\nset -g @agent-indicator-border-enabled 'on'\nset -g @agent-indicator-indicator-enabled 'on'\n\n# Running state (default keeps pane/border unchanged)\nset -g @agent-indicator-running-enabled 'on'\nset -g @agent-indicator-running-bg 'default'\nset -g @agent-indicator-running-border 'default'\nset -g @agent-indicator-running-window-title-bg ''\nset -g @agent-indicator-running-window-title-fg ''\n\n# Needs-input state\nset -g @agent-indicator-needs-input-enabled 'on'\nset -g @agent-indicator-needs-input-bg 'default'\nset -g @agent-indicator-needs-input-border 'yellow'\nset -g @agent-indicator-needs-input-window-title-bg 'yellow'\nset -g @agent-indicator-needs-input-window-title-fg 'black'\n\n# Done state\nset -g @agent-indicator-done-enabled 'on'\nset -g @agent-indicator-done-bg 'default'\nset -g @agent-indicator-done-border 'green'\nset -g @agent-indicator-done-window-title-bg 'red'\nset -g @agent-indicator-done-window-title-fg 'black'\n\n# Per-agent icons\nset -g @agent-indicator-icons 'claude=🤖,codex=🧠,opencode=💻,default=🤖'\n\n# Process fallback detection\nset -g @agent-indicator-processes 'claude,codex,aider,cursor,opencode'\n\n# Keep pane colors until pane focus-in after done\nset -g @agent-indicator-reset-on-focus 'on'\n\n# Running animation in status indicator\nset -g @agent-indicator-animation-enabled 'off'\nset -g @agent-indicator-animation-speed '300'\n\n# Notifications (tmux display-message on state transitions)\nset -g @agent-indicator-notification-enabled 'on'\nset -g @agent-indicator-notification-states 'needs-input,done'\nset -g @agent-indicator-notification-format '[#{agent_name}] #{agent_state} (#{session_name}:#{window_name})'\nset -g @agent-indicator-notification-duration '5000'\nset -g @agent-indicator-notification-command ''\n```\n\nPane background coloring is unchanged by default (`*-bg 'default'` for all states).\nTo enable background colors, set per-state values in your `~/.tmux.conf`, for example:\n\n```tmux\nset -g @agent-indicator-needs-input-bg 'colour94'\nset -g @agent-indicator-done-bg 'green'\n```\n\nEmpty option values are treated as \"do not apply this property\" (for toggles, empty behaves as disabled). Example:\n\n```tmux\nset -g @agent-indicator-done-bg ''\n```\n\nThis skips done-state background changes while still allowing done border/title styles.\n\nNote: tmux border coloring is window-scoped (`pane-active-border-style` / `pane-border-style`).\nYou can style the active border differently, but tmux cannot set a fully independent border color for one arbitrary non-active pane.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eColor presets\u003c/summary\u003e\n\nPreset 1 (Balanced):\n\n```tmux\nset -g @agent-indicator-running-bg ''\nset -g @agent-indicator-running-border ''\nset -g @agent-indicator-needs-input-bg 'colour223'\nset -g @agent-indicator-needs-input-border 'colour214'\nset -g @agent-indicator-done-bg ''\nset -g @agent-indicator-done-border 'colour34'\nset -g @agent-indicator-done-window-title-bg 'colour34'\nset -g @agent-indicator-done-window-title-fg 'black'\n```\n\nPreset 2 (High Contrast):\n\n```tmux\nset -g @agent-indicator-running-bg 'colour52'\nset -g @agent-indicator-running-border 'colour196'\nset -g @agent-indicator-needs-input-bg 'colour94'\nset -g @agent-indicator-needs-input-border 'colour226'\nset -g @agent-indicator-done-bg ''\nset -g @agent-indicator-done-border 'colour46'\nset -g @agent-indicator-done-window-title-bg 'colour46'\nset -g @agent-indicator-done-window-title-fg 'black'\n```\n\nPreset 3 (Subtle):\n\n```tmux\nset -g @agent-indicator-running-bg ''\nset -g @agent-indicator-running-border 'colour244'\nset -g @agent-indicator-needs-input-bg ''\nset -g @agent-indicator-needs-input-border 'colour220'\nset -g @agent-indicator-done-bg ''\nset -g @agent-indicator-done-border 'colour70'\nset -g @agent-indicator-done-window-title-bg 'colour238'\nset -g @agent-indicator-done-window-title-fg 'colour194'\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eTmux color reference\u003c/summary\u003e\n\nTmux supports:\n- 8 basic colors: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`\n- Bright variants (`brightred`, `brightblue`, etc.)\n- 256-color palette: `colour0` ... `colour255`\n\n![Tmux color chart](docs/assets/tmux-colors.png)\n\n\u003c/details\u003e\n\n## Notifications\n\nState transitions trigger a `tmux display-message` notification. Enabled by default for `needs-input` and `done` states.\n\n```tmux\n# Disable notifications entirely\nset -g @agent-indicator-notification-enabled 'off'\n\n# Only notify on done\nset -g @agent-indicator-notification-states 'done'\n\n# Custom format\nset -g @agent-indicator-notification-format '#{agent_name} is #{agent_state} in #{session_name}'\n\n# Duration in milliseconds (0 = use tmux default display-time)\nset -g @agent-indicator-notification-duration '3000'\n```\n\nAvailable format placeholders: `#{agent_name}`, `#{agent_state}`, `#{session_name}`, `#{window_name}`, `#{window_index}`.\n\nYou can also run an external command on each notification. The command receives environment variables `AGENT_NAME`, `AGENT_STATE`, `AGENT_SESSION`, and `AGENT_WINDOW`:\n\n```tmux\n# Log notifications to a file\nset -g @agent-indicator-notification-command 'echo \"$AGENT_NAME $AGENT_STATE\" \u003e\u003e /tmp/agent-notify.log'\n\n# macOS system notification\nset -g @agent-indicator-notification-command 'osascript -e \"display notification \\\"$AGENT_NAME is $AGENT_STATE\\\" with title \\\"tmux agent\\\"\"'\n```\n\n## Custom Agent Integration\n\nTo integrate any agent that does not have built-in hook support, call `agent-state.sh` from your agent's hooks or wrapper script.\n\n```bash\n~/.tmux/plugins/tmux-agent-indicator/scripts/agent-state.sh --agent claude --state running\n~/.tmux/plugins/tmux-agent-indicator/scripts/agent-state.sh --agent claude --state needs-input\n~/.tmux/plugins/tmux-agent-indicator/scripts/agent-state.sh --agent claude --state done\n~/.tmux/plugins/tmux-agent-indicator/scripts/agent-state.sh --agent claude --state off\n```\n\n`--state off` always resets pane background and border immediately.\n\n## Claude Hook Template\n\nDefault template file: `hooks/claude-hooks.json`\nIt maps:\n- `UserPromptSubmit` -\u003e `running`\n- `PermissionRequest` -\u003e `needs-input`\n- `Stop` -\u003e `done`\n\n## OpenCode Plugin\n\nThe installer copies `plugins/opencode-tmux-agent-indicator.js` to `~/.config/opencode/plugins/`. The plugin uses OpenCode's event system:\n- `session.status` (busy) -\u003e `running`\n- `permission.updated` -\u003e `needs-input`\n- `session.idle` -\u003e `done`\n\nTo install manually without the installer, copy the plugin file:\n\n```bash\nmkdir -p ~/.config/opencode/plugins\ncp plugins/opencode-tmux-agent-indicator.js ~/.config/opencode/plugins/\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccessd%2Ftmux-agent-indicator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faccessd%2Ftmux-agent-indicator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccessd%2Ftmux-agent-indicator/lists"}