This repository has no description
tools.claude: swap tmux-mcp for skill, add python3 for plugin hooks
- new skills/tmux documents the claude- session prefix, run-and-wait
marker pattern, output capture, and parallel sessions
- drops the tmux-mcp MCP server and the 5pkgs/tmux-mcp wrapper package
- adds python3 + tmux to the wrapper's extraPackages so plugin hooks
resolve a real python3 inside Nix dev shells where DEVELOPER_DIR
points at a Nix Apple SDK (otherwise /usr/bin/python3 -> xcrun ->
"tool 'python3' not found")
author
lassulus
date
(Apr 27, 2026, 11:55 PM CEST)
commit
abce2a61
abce2a61133ec87ddc2a0a763236bd67d681a199
parent
32c7e792
32c7e792ef9149e9c72586ce983f2cae481aab85
+133
-38
-34
5pkgs/tmux-mcp/package.nix
-34
5pkgs/tmux-mcp/package.nix
···
1
-
{
2
-
lib,
3
-
buildNpmPackage,
4
-
fetchFromGitHub,
5
-
tmux,
6
-
nodejs,
7
-
}:
8
-
9
-
buildNpmPackage rec {
10
-
pname = "tmux-mcp";
11
-
version = "0.1.0";
12
-
13
-
src = fetchFromGitHub {
14
-
owner = "nickgnd";
15
-
repo = "tmux-mcp";
16
-
rev = "96db73220b449487e2be4427d1e86b8ccefc29ef";
17
-
hash = "sha256-lMgRXfzPclPqFO85zi7jvAe/aX1HL2LNk0cf3CkY7tM=";
18
-
};
19
-
20
-
npmDepsHash = "sha256-D/kOVT7BmJJ/g5h9b0LZp5VFnRGtw7qmyIv4Pea+yXE=";
21
-
22
-
buildInputs = [
23
-
tmux
24
-
nodejs
25
-
];
26
-
27
-
meta = with lib; {
28
-
description = "MCP server for tmux integration with Claude";
29
-
homepage = "https://github.com/nickgnd/tmux-mcp";
30
-
license = licenses.mit;
31
-
maintainers = [ ];
32
-
platforms = platforms.all;
33
-
};
34
-
}
+112
skills/tmux/SKILL.md
+112
skills/tmux/SKILL.md
···
1
+
---
2
+
name: tmux
3
+
description: Run long-running commands in a tmux session and capture their output. Use when you need to start a build/test/server that takes minutes, run multiple commands in parallel, or interact with a process across tool calls.
4
+
---
5
+
6
+
# Tmux Skill
7
+
8
+
Drive `tmux` directly via shell commands — no MCP needed. Use this for any
9
+
long-running task whose output you'll want to inspect later, or for processes
10
+
that need to outlive a single Bash tool call.
11
+
12
+
## Session naming convention
13
+
14
+
All sessions you create must be prefixed with `claude-`. This keeps them
15
+
namespaced and lets you find idle ones to reuse.
16
+
17
+
## Find an idle session, or create one
18
+
19
+
Before starting a new session, check whether an existing `claude-*` session
20
+
is idle and reuse it. A session is "idle" if its current pane is at a shell
21
+
prompt with no running command.
22
+
23
+
```bash
24
+
# List existing claude- sessions
25
+
tmux list-sessions -F '#{session_name}' 2>/dev/null | grep '^claude-' || true
26
+
27
+
# Create a fresh detached session
28
+
tmux new-session -d -s claude-build
29
+
30
+
# Create a session only if missing (idempotent)
31
+
tmux has-session -t claude-build 2>/dev/null || tmux new-session -d -s claude-build
32
+
```
33
+
34
+
## Run a command and wait for it
35
+
36
+
Send the command followed by a unique completion marker, then poll
37
+
`capture-pane` until the marker appears.
38
+
39
+
```bash
40
+
SESSION=claude-build
41
+
MARKER="__DONE_$$_$RANDOM__"
42
+
43
+
tmux send-keys -t "$SESSION" "your-long-command; echo $MARKER" Enter
44
+
45
+
# Poll until the marker shows up
46
+
until tmux capture-pane -p -t "$SESSION" | grep -q "$MARKER"; do
47
+
sleep 2
48
+
done
49
+
50
+
# Capture the full output (scrollback included)
51
+
tmux capture-pane -p -S - -t "$SESSION"
52
+
```
53
+
54
+
Use `Bash(run_in_background=true)` for the polling loop if you want to do
55
+
other work while waiting.
56
+
57
+
## Capture output
58
+
59
+
```bash
60
+
# Just what's currently visible
61
+
tmux capture-pane -p -t claude-build
62
+
63
+
# Full scrollback (everything since session start)
64
+
tmux capture-pane -p -S - -t claude-build
65
+
66
+
# Last 200 lines of scrollback
67
+
tmux capture-pane -p -S -200 -t claude-build
68
+
```
69
+
70
+
`-p` prints to stdout. Without it, output goes to a paste buffer.
71
+
72
+
## Run things in parallel
73
+
74
+
Use multiple sessions or multiple windows in one session.
75
+
76
+
```bash
77
+
# Multiple sessions (independent, clean)
78
+
tmux new-session -d -s claude-build -- bash -c 'nix build .#foo'
79
+
tmux new-session -d -s claude-tests -- bash -c 'pytest'
80
+
81
+
# Multiple windows in one session
82
+
tmux new-session -d -s claude-work
83
+
tmux new-window -t claude-work -n build -- bash -c 'nix build .#foo'
84
+
tmux new-window -t claude-work -n tests -- bash -c 'pytest'
85
+
tmux list-windows -t claude-work
86
+
```
87
+
88
+
Note: when a command passed via `--` exits, the window closes too. To keep
89
+
the pane around for inspection, wrap with `bash -c 'cmd; exec bash'` or use
90
+
the `send-keys` pattern above.
91
+
92
+
## Inspect
93
+
94
+
```bash
95
+
tmux list-sessions # all sessions
96
+
tmux list-windows -t claude-build # windows in a session
97
+
tmux list-panes -t claude-build # panes in current window
98
+
```
99
+
100
+
## Clean up
101
+
102
+
```bash
103
+
tmux kill-session -t claude-build # one session
104
+
tmux kill-server # everything (nuclear)
105
+
```
106
+
107
+
## When NOT to use tmux
108
+
109
+
- One-shot commands that complete in seconds → just use `Bash` directly.
110
+
- Commands you want to background but don't need to interact with later →
111
+
`Bash(run_in_background=true)` is simpler.
112
+
- Anything that needs structured stdout/stderr separation — tmux merges them.
+16
skills/tmux/default.nix
+16
skills/tmux/default.nix
···
1
+
{ stdenv, ... }:
2
+
3
+
stdenv.mkDerivation {
4
+
pname = "tmux-skill";
5
+
version = "0.1.0";
6
+
src = ./.;
7
+
8
+
installPhase = ''
9
+
mkdir -p $out/share/tmux
10
+
cp SKILL.md $out/share/tmux/SKILL.md
11
+
'';
12
+
13
+
meta = {
14
+
description = "Drive tmux to run long-running commands and capture output";
15
+
};
16
+
}
+1
-1
tools/claude/CLAUDE.md
+1
-1
tools/claude/CLAUDE.md
···
13
13
- Use the `gh` tool to interact with GitHub.
14
14
- Do not include "claude" in commit messages.
15
15
- Take extra care not to commit lines with trailing whitespace.
16
-
- Use tmux-mcp for long-running tasks. Use a session with a `claude-` prefix — create one if no idle session exists.
16
+
- Use the `tmux` skill for long-running tasks. Use a session with a `claude-` prefix — create one if no idle session exists.
17
17
- Use git-mcp for advanced git operations (interactive staging, stash management, bisecting).
18
18
19
19
## Nix
+4
-3
tools/claude/flake-module.nix
+4
-3
tools/claude/flake-module.nix
···
26
26
git-mcp = {
27
27
command = "${self.packages.${system}.git-mcp}/bin/git-mcp";
28
28
};
29
-
tmux-mcp = {
30
-
command = "${self.packages.${system}.tmux-mcp}/bin/tmux-mcp";
31
-
};
32
29
};
33
30
34
31
skills = {
···
36
33
reverse-engineering = "${
37
34
self.legacyPackages.${system}.skills.reverse-engineering
38
35
}/share/reverse-engineering";
36
+
tmux = "${self.legacyPackages.${system}.skills.tmux}/share/tmux";
39
37
websearch = "${self.legacyPackages.${system}.skills.websearch}/share/websearch";
40
38
};
41
39
···
132
130
"Bash(ruff:*)"
133
131
"Bash(kagi-search:*)"
134
132
"Bash(curl:*)"
133
+
"Bash(tmux:*)"
135
134
# file edits
136
135
"Edit"
137
136
"Write"
···
143
142
self.packages.${system}.kagi-search
144
143
pkgs.curl
145
144
pkgs.jq
145
+
pkgs.python3
146
146
pkgs.ripgrep
147
147
pkgs.fd
148
+
pkgs.tmux
148
149
pkgs.tree
149
150
];
150
151