Skip to content

Commit cf54ac3

Browse files
tonytony
committed
docs(tools): split area pages into per-tool pages by tmux scope
why: The 7 area pages (`tools/{panes,sessions,windows,buffers, hooks,options,waits}.md`) packed 47 tools into long documents organized by safety tier (Inspect/Act/Destroy). Agent-facing navigation was by-tool, not by-area, and every {tool}\`…\` role in prose produced deep links into section anchors on those long pages. Per-tool pages are easier to cite, easier to cache, and match the hierarchy agents already reason about (Server > Session > Window > Pane). what: - **6 per-scope directories.** `docs/tools/{server,session, window,pane,buffer,hook}/`. Each holds one page per tool (kebab-case filename; title-case `# Tool name` heading) plus an `index.md` with a grid-item-card overview and a hidden toctree so the sidebar populates when an area page is open. - **Mechanical extraction.** Each tool page is the old `{fastmcp- tool}` directive + "Use when / Avoid when / Side effects / Example" prose + `{fastmcp-tool-input}` directive, copy-pasted from the old area pages unchanged. No content was rewritten. - **`docs/tools/index.md` toctree** now lists the 6 area indexes (`server/index`, `session/index`, …). The existing grid-card navigation and "Which tool do I want?" decision tree remain unchanged; their `:link: <tool-ref> :link-type: ref` bindings still resolve because the `fastmcp-tool` directive auto-creates the ref labels wherever the tool lives. - **`fastmcp_area_map`** in `docs/conf.py` re-mapped from old area basenames (`"pane_tools": "panes"`) to new area-index paths (`"pane_tools": "pane/index"`). `option_tools` / `env_tools` now live under `server/`; `wait_for_tools` lives under `pane/`. - **`sphinxext-rediraffe` redirects.** 7 new entries in `docs/redirects.txt` map the deleted area pages to their corresponding new area index: `tools/panes → tools/pane/index`, `tools/sessions → tools/server/index`, `tools/windows → tools/window/index`, `tools/buffers → tools/buffer/index`, `tools/hooks → tools/hook/index`, `tools/options → tools/server/index`, `tools/waits → tools/pane/index`. The build's rediraffe check confirms each old URL resolves to its new leaf. - **Old area pages deleted** (`panes.md`, `sessions.md`, `windows.md`, `buffers.md`, `hooks.md`, `options.md`, `waits.md`). Only their content was redistributed; no prose lost. - **One relative link fixed.** `search-panes.md` now points `../../../CHANGES` (three levels up) instead of the old `../../CHANGES` (two levels up). Zero-warning build on `just build-docs`. Full gate (`uv run ruff check`, `ruff format`, `mypy`, `py.test --reruns 0 -vvv` (366 passed), `just build-docs`) clean. Supersedes (closed unmerged) PR #12.
1 parent bd0ad2f commit cf54ac3

63 files changed

Lines changed: 2227 additions & 1893 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/conf.py‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -80,15 +80,15 @@
8080
"libtmux_mcp.tools.hook_tools",
8181
]
8282
conf["fastmcp_area_map"] = {
83-
"server_tools": "sessions",
84-
"session_tools": "sessions",
85-
"window_tools": "windows",
86-
"pane_tools": "panes",
87-
"option_tools": "options",
88-
"env_tools": "options",
89-
"buffer_tools": "buffers",
90-
"wait_for_tools": "waits",
91-
"hook_tools": "hooks",
83+
"server_tools": "server/index",
84+
"session_tools": "session/index",
85+
"window_tools": "window/index",
86+
"pane_tools": "pane/index",
87+
"option_tools": "server/index",
88+
"env_tools": "server/index",
89+
"buffer_tools": "buffer/index",
90+
"wait_for_tools": "pane/index",
91+
"hook_tools": "hook/index",
9292
}
9393
conf["fastmcp_server_module"] = "libtmux_mcp.server:mcp"
9494
conf["fastmcp_model_module"] = "libtmux_mcp.models"

‎docs/redirects.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,10 @@
1515
"concepts" "topics/concepts"
1616
"safety" "topics/safety"
1717
"guides/troubleshooting" "topics/troubleshooting"
18+
"tools/panes" "tools/pane/index"
19+
"tools/sessions" "tools/server/index"
20+
"tools/windows" "tools/window/index"
21+
"tools/buffers" "tools/buffer/index"
22+
"tools/hooks" "tools/hook/index"
23+
"tools/options" "tools/server/index"
24+
"tools/waits" "tools/pane/index"

‎docs/tools/buffer/delete-buffer.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Delete buffer
2+
3+
```{fastmcp-tool} buffer_tools.delete_buffer
4+
```
5+
6+
**Use when** you're done with a buffer and want to free server-side
7+
state. Always call this when the buffer's purpose is complete —
8+
tmux servers outlive the MCP process, so leaked buffers persist
9+
across MCP restarts.
10+
11+
**Side effects:** Removes the named buffer from the tmux server.
12+
Subsequent {tooliconl}`paste-buffer` calls against the deleted name
13+
return `ToolError`.
14+
15+
```{fastmcp-tool-input} buffer_tools.delete_buffer
16+
```

‎docs/tools/buffer/index.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Buffer tools
2+
3+
Paste-buffer tools — stage, push, inspect, and delete MCP-namespaced tmux buffers for multi-line input.
4+
5+
::::{grid} 1 2 2 3
6+
:gutter: 2 2 3 3
7+
8+
:::{grid-item-card} load_buffer
9+
:link: load-buffer
10+
:link-type: ref
11+
Stage content into a new tmux paste buffer.
12+
:::
13+
14+
:::{grid-item-card} paste_buffer
15+
:link: paste-buffer
16+
:link-type: ref
17+
Push a staged buffer into a pane.
18+
:::
19+
20+
:::{grid-item-card} show_buffer
21+
:link: show-buffer
22+
:link-type: ref
23+
Read a staged buffer's contents back.
24+
:::
25+
26+
:::{grid-item-card} delete_buffer
27+
:link: delete-buffer
28+
:link-type: ref
29+
Free the server-side state of a staged buffer.
30+
:::
31+
32+
::::
33+
34+
```{toctree}
35+
:hidden:
36+
:maxdepth: 1
37+
38+
load-buffer
39+
paste-buffer
40+
show-buffer
41+
delete-buffer
42+
```

‎docs/tools/buffer/load-buffer.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Load buffer
2+
3+
```{fastmcp-tool} buffer_tools.load_buffer
4+
```
5+
6+
**Use when** you need to stage multi-line text for paste — sending a
7+
shell script, prepared input for an interactive prompt, or content
8+
that's too long for a clean {tooliconl}`send-keys` invocation.
9+
10+
**Avoid when** the text is a single command line that {tooliconl}`send-keys`
11+
can deliver directly. `load_buffer` allocates server-side state that
12+
must be cleaned up via {tooliconl}`delete-buffer`.
13+
14+
**Side effects:** Allocates a tmux paste buffer. Use the returned
15+
`buffer_name` for follow-up calls. The `content` argument is redacted
16+
in audit logs.
17+
18+
**Example:**
19+
20+
```json
21+
{
22+
"tool": "load_buffer",
23+
"arguments": {
24+
"content": "for i in 1 2 3; do\n echo line $i\ndone\n",
25+
"logical_name": "loop"
26+
}
27+
}
28+
```
29+
30+
Response:
31+
32+
```json
33+
{
34+
"buffer_name": "libtmux_mcp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6_loop",
35+
"logical_name": "loop"
36+
}
37+
```
38+
39+
```{fastmcp-tool-input} buffer_tools.load_buffer
40+
```
41+
42+
---
43+
44+
## Paste

‎docs/tools/buffer/paste-buffer.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Paste buffer
2+
3+
```{fastmcp-tool} buffer_tools.paste_buffer
4+
```
5+
6+
**Use when** you've staged content via {tooliconl}`load-buffer` and
7+
need to push it into a target pane. Use bracketed paste mode
8+
(default `bracket=true`) for terminals that handle it; the wrapping
9+
escape sequences signal "this is pasted text, not typed input".
10+
11+
**Avoid when** the buffer name doesn't match the MCP namespace —
12+
`paste_buffer` refuses non-`libtmux_mcp_*` names so it cannot be
13+
turned into an arbitrary-buffer paster.
14+
15+
**Side effects:** Pastes content into the target pane (the pane's
16+
shell receives the bytes as input). Open-world: the resulting shell
17+
behavior is whatever the pasted bytes invoke.
18+
19+
```{fastmcp-tool-input} buffer_tools.paste_buffer
20+
```
21+
22+
---
23+
24+
## Inspect

‎docs/tools/buffer/show-buffer.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Show buffer
2+
3+
```{fastmcp-tool} buffer_tools.show_buffer
4+
```
5+
6+
**Use when** you need to confirm what was staged before pasting, or
7+
to read back a buffer between modifications. Restricted to
8+
MCP-namespaced buffers — non-agent buffers are rejected.
9+
10+
**Side effects:** None. Readonly.
11+
12+
```{fastmcp-tool-input} buffer_tools.show_buffer
13+
```
14+
15+
---
16+
17+
## Clean up

‎docs/tools/buffers.md‎

Lines changed: 0 additions & 111 deletions
This file was deleted.

‎docs/tools/hook/index.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Hook tools
2+
3+
Hook introspection — enumerate and inspect tmux hook bindings at each scope.
4+
5+
::::{grid} 1 2 2 3
6+
:gutter: 2 2 3 3
7+
8+
:::{grid-item-card} show_hooks
9+
:link: show-hooks
10+
:link-type: ref
11+
Enumerate bindings at a scope.
12+
:::
13+
14+
:::{grid-item-card} show_hook
15+
:link: show-hook
16+
:link-type: ref
17+
Inspect a single binding.
18+
:::
19+
20+
::::
21+
22+
```{toctree}
23+
:hidden:
24+
:maxdepth: 1
25+
26+
show-hooks
27+
show-hook
28+
```

‎docs/tools/hook/show-hook.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Show hook
2+
3+
```{fastmcp-tool} hook_tools.show_hook
4+
```
5+
6+
**Use when** you know which hook you want to inspect by name. Returns
7+
empty when the hook is unset; raises `ToolError` for unknown hook
8+
names (typos, wrong scope) so input mistakes don't masquerade as
9+
"nothing configured".
10+
11+
**Side effects:** None. Readonly.
12+
13+
```{fastmcp-tool-input} hook_tools.show_hook
14+
```

0 commit comments

Comments
 (0)