Skip to content

Commit c338b27

Browse files
tonytony
committed
ai(claude[plugin]): add tmux-parity plugin for feature parity analysis
why: libtmux wraps ~28 of tmux's ~88 commands (~32% coverage). Need tooling to systematically audit gaps, compare across tmux versions, and guide implementation of new command wrappers. what: - Add .claude-plugin/ with manifest, commands, agent, skill, and scripts - /parity-audit: generate full feature parity report (commands, flags, format variables, options) - /version-diff: compare tmux features across 41 version worktrees - /implement-command: guided workflow for wrapping new tmux commands - parity-analyzer agent: auto-triggers on natural language parity queries - tmux-parity skill: shared domain knowledge with reference files (command mapping, implementation patterns, C source navigation) - Extraction scripts: parse tmux cmd-*.c and libtmux .cmd() invocations
1 parent 191208d commit c338b27

11 files changed

Lines changed: 1063 additions & 0 deletions

File tree

‎.claude-plugin/agents/parity-analyzer.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
name: parity-analyzer
3+
description: |
4+
Use this agent when the user asks about "tmux parity", "what commands are missing", "coverage report", "what does libtmux wrap", "unwrapped commands", "missing tmux features", "does libtmux support X", "tmux feature coverage", or when the user wants to understand what tmux functionality libtmux does not yet expose.
5+
6+
<example>
7+
Context: User wants to know parity status
8+
user: "What tmux commands does libtmux not wrap yet?"
9+
assistant: "I'll use the parity-analyzer agent to scan tmux source and cross-reference with libtmux."
10+
<commentary>User asking about missing commands, trigger parity analysis.</commentary>
11+
</example>
12+
13+
<example>
14+
Context: User considering what to implement next
15+
user: "Which unwrapped tmux commands would be most useful to add?"
16+
assistant: "I'll use the parity-analyzer agent to analyze coverage and prioritize gaps."
17+
<commentary>User wants prioritized gap analysis, trigger parity-analyzer.</commentary>
18+
</example>
19+
20+
<example>
21+
Context: User asks about specific command
22+
user: "Does libtmux support break-pane?"
23+
assistant: "I'll check with the parity-analyzer agent."
24+
<commentary>Specific command inquiry, use parity-analyzer for accurate answer.</commentary>
25+
</example>
26+
27+
<example>
28+
Context: User working on parity branch
29+
user: "What should I work on next for tmux parity?"
30+
assistant: "I'll use the parity-analyzer agent to identify the highest-priority gaps."
31+
<commentary>Planning parity work, trigger analysis for prioritization.</commentary>
32+
</example>
33+
model: sonnet
34+
color: cyan
35+
tools:
36+
- Read
37+
- Grep
38+
- Glob
39+
- Bash
40+
---
41+
42+
You are a tmux/libtmux feature parity analysis specialist. Analyze the gap between tmux C source and libtmux Python wrappers.
43+
44+
## Source Locations
45+
46+
- **tmux C source (HEAD)**: ~/study/c/tmux/
47+
- **tmux version worktrees**: ~/study/c/tmux-{version}/ (41 versions, 0.8 to 3.6a)
48+
- **libtmux Python source**: src/libtmux/ (in the current project)
49+
50+
## Analysis Process
51+
52+
### Step 1: Extract tmux commands
53+
54+
Run the extraction script for current data:
55+
```bash
56+
bash .claude-plugin/scripts/extract-tmux-commands.sh ~/study/c/tmux
57+
```
58+
This outputs `command|alias|getopt|target` for all ~88 tmux commands.
59+
60+
### Step 2: Extract libtmux coverage
61+
62+
Run the libtmux extraction:
63+
```bash
64+
bash .claude-plugin/scripts/extract-libtmux-methods.sh
65+
```
66+
This outputs the unique tmux command strings that libtmux invokes.
67+
68+
Additionally, check mixin files for commands invoked via `tmux_cmd()`:
69+
```bash
70+
grep -rn '"set-environment"\|"show-environment"\|"set-hook"\|"set-option"\|"show-option"\|"capture-pane"\|"move-window"\|"select-layout"\|"kill-pane"' src/libtmux/*.py | grep -oP '"([a-z]+-[a-z-]+)"' | sort -u | tr -d '"'
71+
```
72+
73+
### Step 3: Cross-reference
74+
75+
Classify each tmux command:
76+
- **Wrapped**: Command string appears in libtmux source
77+
- **Not Wrapped**: Command string does not appear
78+
79+
For wrapped commands, optionally compare the getopt string from tmux against the Python method parameters to identify missing flags.
80+
81+
### Step 4: Produce report
82+
83+
Output a structured report:
84+
85+
```markdown
86+
## tmux/libtmux Parity Report
87+
88+
### Summary
89+
- Total tmux commands: X
90+
- Wrapped in libtmux: Y (Z%)
91+
- Not wrapped: N
92+
93+
### Wrapped Commands
94+
| Command | libtmux Location |
95+
96+
### Not Wrapped — High Priority
97+
| Command | Alias | Target | Why Useful |
98+
(Include: join-pane, swap-pane, swap-window, respawn-pane, respawn-window, run-shell, break-pane, move-pane, pipe-pane, display-popup, clear-history)
99+
100+
### Not Wrapped — Medium Priority
101+
| Command | Alias | Target | Notes |
102+
(Include: navigation commands, buffer management, wait-for, if-shell, detach-client)
103+
104+
### Not Wrapped — Low Priority
105+
| Command | Alias | Target | Notes |
106+
(Include: interactive UI commands, key bindings, lock commands, config commands)
107+
```
108+
109+
### Priority Guidelines
110+
111+
**High priority** — Commands useful for programmatic tmux control and automation:
112+
- Pane/window manipulation: join-pane, swap-pane, swap-window, break-pane, move-pane
113+
- Process management: respawn-pane, respawn-window, run-shell
114+
- I/O: pipe-pane, clear-history, display-popup
115+
116+
**Medium priority** — Navigation, buffers, and client management:
117+
- Navigation: last-pane, last-window, next-window, previous-window
118+
- Buffer ops: list-buffers, load-buffer, save-buffer, paste-buffer, set-buffer
119+
- Window linking: link-window, unlink-window
120+
- Synchronization: wait-for
121+
- Conditional: if-shell
122+
123+
**Low priority** — Interactive UI and configuration (rarely needed in API):
124+
- Interactive: choose-tree, choose-buffer, copy-mode, command-prompt
125+
- Key binding: bind-key, unbind-key
126+
- Security: lock-server, lock-session, lock-client
127+
- Meta: list-commands, list-keys, show-messages
128+
- Config: source-file, start-server
129+
130+
## Reference Data
131+
132+
The baseline command mapping is at `.claude-plugin/skills/tmux-parity/references/command-mapping.md`. Use this as a starting point, but always run the extraction scripts for the most current data.

‎.claude-plugin/commands/implement-command.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
description: Guide implementing a new tmux command wrapper in libtmux
3+
argument-hint: "<tmux-command-name> — e.g., 'break-pane', 'join-pane', 'swap-window'"
4+
allowed-tools:
5+
- Read
6+
- Write
7+
- Edit
8+
- Grep
9+
- Glob
10+
- Bash
11+
- AskUserQuestion
12+
- Agent
13+
---
14+
15+
# Implement Command
16+
17+
Guide wrapping a tmux command in libtmux, following project coding standards from CLAUDE.md.
18+
19+
Load the `tmux-parity` skill first for reference data and implementation patterns.
20+
21+
If `$ARGUMENTS` is empty, ask the user which tmux command to wrap. Consult `.claude-plugin/skills/tmux-parity/references/command-mapping.md` for the "Not Wrapped" list to suggest candidates.
22+
23+
## Phase 1: Analyze the tmux Command
24+
25+
1. Read `~/study/c/tmux/cmd-{command}.c` fully
26+
2. Extract from the `cmd_entry` struct:
27+
- **name** and **alias**
28+
- **getopt string** — enumerate all flags, which take values, which are boolean
29+
- **usage string** — human-readable flag descriptions
30+
- **target type** — `CMD_FIND_PANE`, `CMD_FIND_WINDOW`, `CMD_FIND_SESSION`, or none
31+
- **command flags** — `CMD_READONLY`, `CMD_AFTERHOOK`, etc.
32+
3. Read the `exec` function to understand:
33+
- What arguments it processes
34+
- What side effects it has (creates objects, modifies state, produces output)
35+
- What it returns or prints
36+
- Error conditions
37+
38+
4. Present a summary to the user:
39+
```
40+
## tmux command: {name} ({alias})
41+
Target: {pane|window|session|none} → libtmux class: {Pane|Window|Session|Server}
42+
Flags: {table of flags with descriptions}
43+
Behavior: {what the command does}
44+
```
45+
46+
## Phase 2: Determine libtmux Placement
47+
48+
Map the target type to libtmux class:
49+
| Target | Primary Class | File |
50+
|--------|--------------|------|
51+
| `CMD_FIND_PANE` | `Pane` | `src/libtmux/pane.py` |
52+
| `CMD_FIND_WINDOW` | `Window` | `src/libtmux/window.py` |
53+
| `CMD_FIND_SESSION` | `Session` | `src/libtmux/session.py` |
54+
| none | `Server` | `src/libtmux/server.py` |
55+
56+
Some commands may also get convenience methods on parent classes. Ask the user if they want additional convenience methods.
57+
58+
## Phase 3: Find a Similar Implementation
59+
60+
Search libtmux for a wrapped command with similar characteristics:
61+
- Same target type
62+
- Similar flag pattern (boolean flags, value flags, creates objects, etc.)
63+
- Read that method as a template
64+
65+
Consult `.claude-plugin/skills/tmux-parity/references/libtmux-patterns.md` for the five implementation patterns.
66+
67+
## Phase 4: Design the Method Signature
68+
69+
Present a proposed method signature to the user before implementing. Include:
70+
- Method name (snake_case, derived from tmux command name)
71+
- Parameters mapped from tmux flags (with Python-friendly names and types)
72+
- Return type
73+
- Which flags to include (not all flags need wrapping — ask user about ambiguous ones)
74+
75+
**This is a good point to ask the user to write the method signature and core logic (5-10 lines).** Present the trade-offs:
76+
- Which flags to expose (all vs. commonly used)?
77+
- Return type (Self vs. new object vs. None)?
78+
- Naming conventions for parameters?
79+
80+
## Phase 5: Implement
81+
82+
Follow CLAUDE.md coding standards strictly:
83+
84+
1. **Imports**: `from __future__ import annotations`, `import typing as t`
85+
2. **Method**: Add to the appropriate class file
86+
3. **Docstring**: NumPy format with Parameters, Returns, Examples sections
87+
4. **Doctests**: Working doctests using `doctest_namespace` fixtures (`server`, `session`, `window`, `pane`)
88+
- Use `# doctest: +ELLIPSIS` for variable output
89+
- NEVER use `# doctest: +SKIP`
90+
5. **Logging**: `logger.info("descriptive msg", extra={"tmux_subcommand": "...", ...})`
91+
6. **Error handling**: Check `proc.stderr`, raise `exc.LibTmuxException`
92+
93+
## Phase 6: Create Tests
94+
95+
Add tests in `tests/test_{class}.py` (or a new file if warranted):
96+
97+
1. **Functional tests only** — no test classes
98+
2. **Use fixtures**: `server`, `session`, `window`, `pane` from conftest.py
99+
3. **Test each parameter/flag** combination
100+
4. **Test error cases** if applicable
101+
5. **Use descriptive function names**: `test_{command}_{scenario}`
102+
103+
## Phase 7: Verify
104+
105+
Run the full verification workflow:
106+
107+
```bash
108+
# Format
109+
uv run ruff format .
110+
111+
# Lint
112+
uv run ruff check . --fix --show-fixes
113+
114+
# Type check
115+
uv run mypy src tests
116+
117+
# Test the specific file
118+
uv run pytest tests/test_{class}.py -x -v
119+
120+
# Run doctests
121+
uv run pytest --doctest-modules src/libtmux/{class}.py -v
122+
123+
# Full test suite
124+
uv run pytest
125+
```
126+
127+
All must pass before considering the implementation complete.

‎.claude-plugin/commands/parity-audit.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
description: Generate a feature parity report between tmux commands and libtmux wrappers
3+
argument-hint: "[command-name] — audit a specific command, or leave empty for full audit"
4+
allowed-tools:
5+
- Read
6+
- Grep
7+
- Glob
8+
- Bash
9+
- Agent
10+
---
11+
12+
# Parity Audit
13+
14+
Load the `tmux-parity` skill first to access reference data and domain knowledge.
15+
16+
## Single Command Audit (when $ARGUMENTS specifies a command name)
17+
18+
1. **Read the tmux C source** for the specified command:
19+
- Read `~/study/c/tmux/cmd-{command}.c` to find the `cmd_entry` struct
20+
- Extract: name, alias, getopt string, usage, target type, command flags
21+
- Parse the getopt string to enumerate all flags (boolean vs value-taking)
22+
- Read the `exec` function to understand behavior and return semantics
23+
24+
2. **Search libtmux source** for the command:
25+
- Grep `src/libtmux/*.py` for the command string (e.g., `"send-keys"`)
26+
- For each match, read the surrounding method to understand which flags are exposed as Python parameters
27+
- Check mixins: `src/libtmux/common.py` (EnvironmentMixin), `src/libtmux/options.py`, `src/libtmux/hooks.py`
28+
29+
3. **Produce a detailed report**:
30+
- Command name, alias, target type
31+
- Table of all tmux flags: flag | description (from usage string) | exposed in libtmux? | Python parameter name
32+
- Missing flags with notes on what they do
33+
- Recommendations for which missing flags to add
34+
35+
## Full Audit (when no arguments given)
36+
37+
1. **Run extraction scripts** for up-to-date data:
38+
```bash
39+
bash .claude-plugin/scripts/extract-tmux-commands.sh ~/study/c/tmux
40+
bash .claude-plugin/scripts/extract-libtmux-methods.sh
41+
```
42+
43+
2. **Cross-reference the results**:
44+
- Parse script output to classify each command: Wrapped, Not Wrapped
45+
- For wrapped commands, compare getopt strings against Python method signatures to find partially-covered commands
46+
47+
3. **Audit format variables** (optional, if specifically requested):
48+
- Read `~/study/c/tmux/format.c` and search for `format_add` calls to list all format variables
49+
- Compare against `src/libtmux/formats.py`
50+
- Report missing format variables
51+
52+
4. **Audit options table** (optional, if specifically requested):
53+
- Read `~/study/c/tmux/options-table.c` to list all options with their scopes
54+
- Compare against libtmux options handling
55+
- Report missing options
56+
57+
5. **Produce the full parity report**:
58+
59+
```
60+
## tmux/libtmux Parity Report
61+
62+
### Summary
63+
- Commands: X/Y wrapped (Z%)
64+
- Partially wrapped: N commands (some flags missing)
65+
66+
### Coverage by Category
67+
| Category | Wrapped | Total | % |
68+
|----------|---------|-------|---|
69+
| Session mgmt | ... | ... | ... |
70+
| Window mgmt | ... | ... | ... |
71+
| Pane mgmt | ... | ... | ... |
72+
| ...
73+
74+
### Not Wrapped — High Priority
75+
| Command | Alias | Target | Why Important |
76+
77+
### Not Wrapped — Medium Priority
78+
...
79+
80+
### Partially Wrapped (Missing Flags)
81+
| Command | libtmux Method | Missing Flags |
82+
```
83+
84+
Consult `.claude-plugin/skills/tmux-parity/references/command-mapping.md` for the baseline mapping data. Run the extraction scripts for the most current data.

0 commit comments

Comments
 (0)