tmux-python · tony · Mar 15, 2026 · Mar 15, 2026 · Mar 15, 2026 · Mar 15, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -282,7 +282,7 @@ Raw `print()` is forbidden in command/business logic. The `print()` call lives o
 
 When writing documentation (README, CHANGES, docs/), follow these rules for code blocks:
 
-**One command per code block.** This makes commands individually copyable.
+**One command per code block.** This makes commands individually copyable. For sequential commands, either use separate code blocks or chain them with `&&` or `;` and `\` continuations (keeping it one logical command).
 
 **Put explanations outside the code block**, not as comments inside.
 
@@ -310,6 +310,42 @@ $ uv run pytest
 $ uv run pytest --cov
 ```
 
+### Shell Command Formatting
+
+These rules apply to shell commands in documentation (README, CHANGES, docs/), **not** to Python doctests.
+
+**Use `console` language tag with `$ ` prefix.** This distinguishes interactive commands from scripts and enables prompt-aware copy in many terminals.
+
+Good:
+
+```console
+$ uv run pytest
+```
+
+Bad:
+
+```bash
+uv run pytest
+```
+
+**Split long commands with `\` for readability.** Each flag or flag+value pair gets its own continuation line, indented. Positional parameters go on the final line.
+
+Good:
+
+```console
+$ pipx install \
+    --suffix=@next \
+    --pip-args '\--pre' \
+    --force \
+    'tmuxp'
+```
+
+Bad:
+
+```console
+$ pipx install --suffix=@next --pip-args '\--pre' --force 'tmuxp'
+```
+
 ## Important Notes
 
 - **QA every edit**: Run formatting and tests before committing

diff --git a/CHANGES b/CHANGES
@@ -23,7 +23,11 @@ $ uvx --from 'tmuxp' --prerelease allow tmuxp
 [pipx](https://pypa.github.io/pipx/docs/):
 
 ```console
-$ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force
+$ pipx install \
+    --suffix=@next \
+    --pip-args '\--pre' \
+    --force \
+    'tmuxp'
 // Usage: tmuxp@next load yoursession
 ```
 
@@ -453,8 +457,8 @@ _Maintenance only, no bug fixes or new features_
 
   via ruff v0.8.4, all automated lint fixes, including unsafe and previews were applied for Python 3.9:
 
-  ```sh
-  ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes; ruff format .
+  ```console
+  $ ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes; ruff format .
   ```
 
 ## tmuxp 1.49.0 (2024-11-26)
@@ -560,14 +564,14 @@ _Maintenance only, no bug fixes or new features_
 
   via ruff v0.3.4, all automated lint fixes, including unsafe and previews were applied:
 
-  ```sh
-  ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes; ruff format .
+  ```console
+  $ ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes; ruff format .
   ```
 
   Branches were treated with:
 
-  ```sh
-  git rebase \
+  ```console
+  $ git rebase \
       --strategy-option=theirs \
       --exec 'poetry run ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes; poetry run ruff format .; git add src tests; git commit --amend --no-edit' \
       origin/master

diff --git a/docs/cli/completion.md b/docs/cli/completion.md
@@ -32,26 +32,26 @@ $ uvx shtab --help
 
 :::{tab} bash
 
-```bash
-shtab --shell=bash -u tmuxp.cli.create_parser \
+```console
+$ shtab --shell=bash -u tmuxp.cli.create_parser \
   | sudo tee "$BASH_COMPLETION_COMPAT_DIR"/TMUXP
 ```
 
 :::
 
 :::{tab} zsh
 
-```zsh
-shtab --shell=zsh -u tmuxp.cli.create_parser \
+```console
+$ shtab --shell=zsh -u tmuxp.cli.create_parser \
   | sudo tee /usr/local/share/zsh/site-functions/_TMUXP
 ```
 
 :::
 
 :::{tab} tcsh
 
-```zsh
-shtab --shell=tcsh -u tmuxp.cli.create_parser \
+```console
+$ shtab --shell=tcsh -u tmuxp.cli.create_parser \
   | sudo tee /etc/profile.d/TMUXP.completion.csh
 ```
 

diff --git a/docs/developing.md b/docs/developing.md
@@ -175,13 +175,15 @@ $ env PYTEST_ADDOPTS="tests/workspace/test_builder.py" uv run make start
 Drop into `test_automatic_rename_option()` in `tests/workspace/test_builder.py`:
 
 ```console
-$ env PYTEST_ADDOPTS="-s -x -vv tests/workspace/test_builder.py" uv run make start
+$ env PYTEST_ADDOPTS="-s -x -vv tests/workspace/test_builder.py" \
+    uv run make start
 ```
 
 Drop into `test_automatic_rename_option()` in `tests/workspace/test_builder.py` and stop on first error:
 
 ```console
-$ env PYTEST_ADDOPTS="-s -x -vv tests/workspace/test_builder.py::test_automatic_rename_option" uv run make start
+$ env PYTEST_ADDOPTS="-s -x -vv tests/workspace/test_builder.py::test_automatic_rename_option" \
+    uv run make start
 ```
 
 Drop into `pdb` on first error: