Agent skill

tmux-status-debug

Debug and test tmux pane status detection for AI agents (opencode, claude, amp). Use when patterns aren't matching, status icons are wrong, or adding new detection patterns.

View SKILL.md on GitHub Repository
Stars 53
Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/edmundmiller/dotfiles/tree/main/.agents/skills/tmux-status-debug

SKILL.md

Debugging tmux-opencode-integrated Status Detection

When to Use

  • Status icons showing wrong state (e.g., showing ERROR when agent is IDLE)
  • Adding new patterns for agent detection
  • Testing pattern matching against real pane content

Quick Commands

List all agent panes

bash
tmux list-panes -a -F "#{session_name}:#{window_name}.#{pane_index} #{pane_current_command}" | grep -E "opencode|claude|amp"

Capture pane content (raw)

bash
tmux capture-pane -t "main:1" -p -S -30 | tail -40

Capture with control chars visible

bash
tmux capture-pane -t "main:1" -p -S -30 | cat -v | tail -40

Check if pattern exists in pane

bash
tmux capture-pane -t "main:1" -p -S -20 | grep -o "pattern"

Debug Script

Create /tmp/debug_status.py and run with the Nix Python that has libtmux:

python
import sys
sys.path.insert(0, "/Users/emiller/.config/dotfiles/packages/tmux-opencode-integrated/scripts")
import smart_name
import re

import libtmux
server = libtmux.Server()
for session in server.sessions:
    for window in session.windows:
        for pane in window.panes:
            program = smart_name.get_pane_program(pane)
            if program in smart_name.AGENT_PROGRAMS:
                print(f"\n=== {program} in {session.name}:{window.name} ===")
                try:
                    cmd_output = pane.cmd("capture-pane", "-p", "-S", "-20").stdout
                    if isinstance(cmd_output, list):
                        content = "\n".join(cmd_output)
                    else:
                        content = str(cmd_output)

                    cleaned = smart_name.strip_ansi_and_control(content)
                    print(f"Last 300 chars (cleaned):\n{cleaned[-300:]}")
                    print(f"\n--- Status: {smart_name.get_opencode_status(pane)} ---")
                except Exception as e:
                    print(f"Error: {e}")

Find the Nix Python with libtmux

bash
# Build the package and get the store path
nix build .#tmux-opencode-integrated --no-link --print-out-paths

# Check wrapper to find Python path
head -10 /nix/store/<hash>-tmux-opencode-integrated-*/share/tmux-plugins/tmux-opencode-integrated/scripts/smart-name.sh

# Run debug script with that Python
/nix/store/<python-hash>-python3-*-env/bin/python3 /tmp/debug_status.py

Pattern Testing

Test patterns against sample content:

python
import re

content = """ctrl+t variants  tab agents  ctrl+p commands    • OpenCode 1.1.30"""

patterns = [
    (r"OpenCode \d+\.\d+\.\d+", "IDLE - version"),
    (r"ctrl\+p commands", "IDLE - status bar"),
    (r"esc interrupt", "BUSY - can interrupt"),
    (r"Esc to cancel", "BUSY - can cancel"),
    (r"■■■", "BUSY - progress bar"),
]

for pattern, desc in patterns:
    if re.search(pattern, content, re.IGNORECASE):
        print(f"✓ {desc}: {pattern}")

Status Priority

Order matters - first match wins:

  1. ERROR - Traceback, panic, FATAL ERROR, API errors
  2. WAITING - Allow once?, Permission required, yes/no/skip prompts
  3. BUSY - Thinking..., spinners, Running tools, esc interrupt
  4. IDLE - Input prompt, context display, OpenCode version, ctrl+p commands
  5. UNKNOWN - No patterns matched (fallback)

Adding New Patterns

  1. Capture real pane content with the debug script above
  2. Identify unique text that indicates the state
  3. Add pattern to appropriate list in smart_name.py
  4. Add test case in tests/test_smart_name.py
  5. Run tests: uvx pytest tests/test_smart_name.py -v
  6. Rebuild: nix build .#tmux-opencode-integrated

Common Issues

"No module named 'libtmux'"

Using wrong Python. Must use the Nix-wrapped Python from the package.

Patterns not matching

Terminal control characters may be interfering. The strip_ansi_and_control() function should handle this, but check with cat -v to see raw content.

Status showing ERROR when it shouldn't

Check if content contains error-like strings from previous output. The detection looks at last 20 lines of pane content.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

edmundmiller/dotfiles

zbench

Benchmark interactive zsh performance with zsh-bench and track regressions. Use when benchmarking shell startup, comparing zsh latency after config changes, investigating slow shell, or running git bisect on performance. Trigger phrases: "benchmark zsh", "shell is slow", "zbench", "zsh-bench", "shell startup time", "profile zsh", "zsh performance".

53 5
Explore
edmundmiller/dotfiles

nix-rebuild

Rebuild nix-darwin/NixOS system after dotfiles changes. Use when config files managed by Nix (lazygit, ghostty, etc.) need to be regenerated, or after editing any .nix file in the dotfiles repo.

53 5
Explore
edmundmiller/dotfiles

hass-config-flow

Interact with Home Assistant via the REST API on a NixOS host. Use when adding integrations, querying entities, managing config flows, creating API tokens, or automating HA setup programmatically. Also covers identifying device protocols (Matter, Zigbee, Thread, HomeKit) from the device registry. Trigger phrases: "add HA integration", "configure home assistant", "query HA entities", "create HA token", "HA REST API", "pair homekit", "set up matter in HA", "add spotify to HA", "is this device zigbee or thread", "what protocol is this device", "move devices to ZHA", "identify matter devices".

53 5
Explore
edmundmiller/dotfiles

hass-declarative

Manage Home Assistant automations, scenes, and scripts declaratively via NixOS modules. Covers adding/editing/removing entities in the domain-based Nix structure, the ensureEnabled wrapper (initial_state enforcement), the sweep service that cleans orphaned entities, entity identity (IDs, slugs, unique_ids), the eval test assertions, and the build-time manifest. Trigger phrases: "add HA automation", "new scene", "new script", "remove automation", "declarative HA", "sweep unmanaged", "entity drift", "ghost entity", "orphaned automation", "HA domain file", "eval-automations test", "hass assertion", "ensureEnabled", "initial_state".

53 5
Explore
edmundmiller/dotfiles

agenix-secrets

Create, edit, and wire up agenix-encrypted secrets in this dotfiles repo. Use when adding API keys, tokens, credentials, passwords, or any sensitive values to NixOS host configs. Trigger phrases: "add a secret", "encrypt with agenix", "new age secret", "hide this value", "agenix secret".

53 5
Explore
edmundmiller/dotfiles

linear

Read-only Linear issue access via the Linear GraphQL API.

53 5
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results