Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Refactor documentation: convert markdown tables to HTML and update sync markers

Maximilian Roos31b9b1225b71
diff --git a/README.md b/README.md
index d1793873d..cf15437b5 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
> **December 2025**: I've been using Worktrunk as my daily driver, and am releasing it as Open Source this week; I think folks will find it really helpful. It's built with love (there's no slop!). If social proof is helpful: I also created [PRQL](https://github.com/PRQL/prql) (10k stars) and am a maintainer of [Xarray](https://github.com/pydata/xarray) (4k stars), [Insta](https://github.com/mitsuhiko/insta), & [Numbagg](https://github.com/numbagg/numbagg).
-Worktrunk is a CLI for git worktree management, designed for parallel AI agent workflows. Git worktrees give each agent an isolated branch and directory; Worktrunk adds branch-based navigation, unified status, and lifecycle hooks. Creating a new agent workspace is as immediate as `git switch`.
+Worktrunk is a CLI for git worktree management, designed for parallel AI agent workflows. Git worktrees give each agent an isolated branch and directory; Worktrunk wraps them in a clean interface and extension points. Scaling agents becomes as simple as scaling git branches.
Here's a quick demo:
@@ -22,30 +22,59 @@ Here's a quick demo:
> ## 📚 Full documentation at [worktrunk.dev](https://worktrunk.dev) 📚
-<!-- ⚠️ AUTO-GENERATED from docs/content/worktrunk.md#git-worktrees-are-a-great-primitive..worktrunk-makes-git-worktrees-easy — edit source to update -->
+<!-- ⚠️ AUTO-GENERATED from docs/content/worktrunk.md#context-git-worktrees..worktrunk-makes-git-worktrees-easy — edit source to update -->
-## Git worktrees are a great primitive
+## Context: git worktrees
-For context, AI agents like Claude Code and Codex can increasingly handle longer tasks
-without supervision, and it's very practical to run several in parallel. Git
-worktrees provide each agent with its own working directory, avoiding agents
-stepping on each other's changes.
+AI agents like Claude Code and Codex can handle longer tasks without supervision,
+and running several in parallel is practical. Git worktrees give each agent its
+own working directory — no stepping on each other's changes.
-But the git worktree UX is clunky. Even something as simple as "start a new worktree" is verbose:
-`git worktree add -b feature ../repo.feature`, then `cd ../repo.feature`.
+But the git worktree UX is clunky. Even starting a new worktree means typing the
+branch name three times: `git worktree add -b feature ../repo.feature`, then
+`cd ../repo.feature`.
## Worktrunk makes git worktrees easy
-Worktrunk makes git worktrees easy to use — branch-based navigation, unified status, and workflow automation.
+Start with the core commands; add workflow automation as needed.
**Core commands:**
-| Task | Worktrunk | Plain git |
-| --------------------- | -------------------------------- | ----------------------------------------------------------------------------- |
-| Switch worktrees | `wt switch feature` | `cd ../repo.feature` |
-| Create + start Claude | `wt switch -c -x claude feature` | `git worktree add -b feature ../repo.feature && cd ../repo.feature && claude` |
-| Clean up | `wt remove` | `cd ../repo && git worktree remove ../repo.feature && git branch -d feature` |
-| List with status | `wt list` | `git worktree list` (paths only) |
+<table class="cmd-compare">
+ <thead>
+ <tr>
+ <th>Task</th>
+ <th>Worktrunk</th>
+ <th>Plain git</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Switch worktrees</td>
+ <td><code>wt switch feature</code></td>
+ <td><pre>cd ../repo.feature</pre></td>
+ </tr>
+ <tr>
+ <td>Create + start Claude</td>
+ <td><code>wt switch -c -x claude feature</code></td>
+ <td><pre>git worktree add -b feature ../repo.feature && \
+cd ../repo.feature && \
+claude</pre></td>
+ </tr>
+ <tr>
+ <td>Clean up</td>
+ <td><code>wt remove</code></td>
+ <td><pre>cd ../repo && \
+git worktree remove ../repo.feature && \
+git branch -d feature</pre></td>
+ </tr>
+ <tr>
+ <td>List with status</td>
+ <td><code>wt list</code></td>
+ <td><pre>git worktree list</pre> (paths only)</td>
+ </tr>
+ </tbody>
+</table>
**Workflow automation:**
@@ -56,57 +85,6 @@ Worktrunk makes git worktrees easy to use — branch-based navigation, unified s
<!-- END AUTO-GENERATED -->
-## Core commands in practice
-
-Create a worktree for a new task:
-
-<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_simple_switch.snap — edit source to update -->
-
-```bash
-$ wt switch --create fix-auth
-✅ Created new worktree for fix-auth from main at ../repo.fix-auth
-```
-
-<!-- END AUTO-GENERATED -->
-
-Switch to an existing worktree:
-
-<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_switch_back.snap — edit source to update -->
-
-```bash
-$ wt switch feature-api
-✅ Switched to worktree for feature-api at ../repo.feature-api
-```
-
-<!-- END AUTO-GENERATED -->
-
-See all worktrees at a glance:
-
-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list.snap — edit source to update -->
-
-```console
-$ wt list
- Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message
-@ feature-api + ↕⇡ +54 -5 ↑4 ↓1 ./repo.feature-api ⇡3 ec97decc 30m Add API tests
-^ main ^⇅ ./repo ⇡1 ⇣1 6088adb3 4d Merge fix-auth:…
-+ fix-auth ↕| ↑2 ↓1 ./repo.fix-auth | 127407de 5h Add secure token…
-
-⚪ Showing 3 worktrees, 1 with changes, 2 ahead
-```
-
-<!-- END AUTO-GENERATED -->
-
-Clean up when done:
-
-<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_remove.snap — edit source to update -->
-
-```console
-$ wt remove
-🔄 Removing feature-api worktree & branch in background (same commit as main)
-```
-
-<!-- END AUTO-GENERATED -->
-
<!-- ⚠️ AUTO-GENERATED from docs/content/worktrunk.md#install..further-reading — edit source to update -->
## Install
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index 3dcf84684..8b5d9e84c 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -3,7 +3,10 @@ title = "Worktrunk"
weight = 1
+++
-Worktrunk is a CLI for git worktree management, designed for parallel AI agent workflows. Git worktrees give each agent an isolated branch and directory; Worktrunk adds branch-based navigation, unified status, and lifecycle hooks. Creating a new agent workspace is as immediate as `git switch`.
+Worktrunk is a CLI for git worktree management, designed for parallel AI agent
+workflows. Git worktrees give each agent an isolated branch and directory;
+Worktrunk wraps them in a clean interface and extension points. Scaling agents
+becomes as simple as scaling git branches.
Here's a quick demo:
@@ -12,28 +15,57 @@ Here's a quick demo:
<figcaption>Listing worktrees, creating a worktree, working, merging back</figcaption>
</figure>
-## Git worktrees are a great primitive
+## Context: git worktrees
-For context, AI agents like Claude Code and Codex can increasingly handle longer tasks
-without supervision, and it's very practical to run several in parallel. Git
-worktrees provide each agent with its own working directory, avoiding agents
-stepping on each other's changes.
+AI agents like Claude Code and Codex can handle longer tasks without supervision,
+and running several in parallel is practical. Git worktrees give each agent its
+own working directory — no stepping on each other's changes.
-But the git worktree UX is clunky. Even something as simple as "start a new worktree" is verbose:
-`git worktree add -b feature ../repo.feature`, then `cd ../repo.feature`.
+But the git worktree UX is clunky. Even starting a new worktree means typing the
+branch name three times: `git worktree add -b feature ../repo.feature`, then
+`cd ../repo.feature`.
## Worktrunk makes git worktrees easy
-Worktrunk makes git worktrees easy to use — branch-based navigation, unified status, and workflow automation.
+Start with the core commands; add workflow automation as needed.
**Core commands:**
-| Task | Worktrunk | Plain git |
-| --------------------- | -------------------------------- | ----------------------------------------------------------------------------- |
-| Switch worktrees | `wt switch feature` | `cd ../repo.feature` |
-| Create + start Claude | `wt switch -c -x claude feature` | `git worktree add -b feature ../repo.feature && cd ../repo.feature && claude` |
-| Clean up | `wt remove` | `cd ../repo && git worktree remove ../repo.feature && git branch -d feature` |
-| List with status | `wt list` | `git worktree list` (paths only) |
+<table class="cmd-compare">
+ <thead>
+ <tr>
+ <th>Task</th>
+ <th>Worktrunk</th>
+ <th>Plain git</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Switch worktrees</td>
+ <td><code>wt switch feature</code></td>
+ <td>{% rawcode() %}cd ../repo.feature{% end %}</td>
+ </tr>
+ <tr>
+ <td>Create + start Claude</td>
+ <td><code>wt switch -c -x claude feature</code></td>
+ <td>{% rawcode() %}git worktree add -b feature ../repo.feature && \
+cd ../repo.feature && \
+claude{% end %}</td>
+ </tr>
+ <tr>
+ <td>Clean up</td>
+ <td><code>wt remove</code></td>
+ <td>{% rawcode() %}cd ../repo && \
+git worktree remove ../repo.feature && \
+git branch -d feature{% end %}</td>
+ </tr>
+ <tr>
+ <td>List with status</td>
+ <td><code>wt list</code></td>
+ <td>{% rawcode() %}git worktree list{% end %} (paths only)</td>
+ </tr>
+ </tbody>
+</table>
**Workflow automation:**
@@ -42,57 +74,6 @@ Worktrunk makes git worktrees easy to use — branch-based navigation, unified s
- **[Merge workflow](@/merge.md)** — squash, rebase, merge, clean up in one command
- ...and [lots more](#next-steps)
-## Core commands in practice
-
-Create a worktree for a new task:
-
-<!-- ⚠️ AUTO-GENERATED-HTML from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_simple_switch.snap — edit source to update -->
-
-{% terminal() %}
-<span class="prompt">$</span> <span class="cmd">wt switch --create fix-auth</span>
-✅ <span class=g>Created new worktree for <b>fix-auth</b> from <b>main</b> at <b>../repo.fix-auth</b></span>
-{% end %}
-
-<!-- END AUTO-GENERATED -->
-
-Switch to an existing worktree:
-
-<!-- ⚠️ AUTO-GENERATED-HTML from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_switch_back.snap — edit source to update -->
-
-{% terminal() %}
-<span class="prompt">$</span> <span class="cmd">wt switch feature-api</span>
-✅ <span class=g>Switched to worktree for <b>feature-api</b> at <b>../repo.feature-api</b></span>
-{% end %}
-
-<!-- END AUTO-GENERATED -->
-
-See all worktrees at a glance:
-
-<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__readme_example_list.snap — edit source to update -->
-
-{% terminal() %}
-<span class="prompt">$</span> <span class="cmd">wt list</span>
- <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Path</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>
-@ <b>feature-api</b> <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <b>./repo.feature-api</b> <span class=g>⇡3</span> <span class=d>ec97decc</span> <span class=d>30m</span> <span class=d>Add API tests</span>
-^ main <span class=d>^</span><span class=d>⇅</span> ./repo <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>6088adb3</span> <span class=d>4d</span> <span class=d>Merge fix-auth:…</span>
-+ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> ./repo.fix-auth <span class=d>|</span> <span class=d>127407de</span> <span class=d>5h</span> <span class=d>Add secure token…</span>
-
-⚪ <span class=d>Showing 3 worktrees, 1 with changes, 2 ahead</span>
-{% end %}
-
-<!-- END AUTO-GENERATED -->
-
-Clean up when done:
-
-<!-- ⚠️ AUTO-GENERATED-HTML from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_remove.snap — edit source to update -->
-
-{% terminal() %}
-<span class="prompt">$</span> <span class="cmd">wt remove</span>
-🔄 <span class=c>Removing <b>feature-api</b> worktree &amp; branch in background (same commit as main)</span>
-{% end %}
-
-<!-- END AUTO-GENERATED -->
-
## Install
**Homebrew (macOS & Linux):**
diff --git a/docs/sass/custom.scss b/docs/sass/custom.scss
index da3d6f686..0e3769ee7 100644
--- a/docs/sass/custom.scss
+++ b/docs/sass/custom.scss
@@ -588,6 +588,17 @@ main {
white-space: nowrap;
}
+ // But allow multiline code blocks in tables to wrap
+ td pre code {
+ white-space: pre;
+ }
+
+ // Plain multiline code without block styling
+ td code.multiline {
+ white-space: pre;
+ display: block;
+ }
+
td:first-child {
font-weight: 550;
color: var(--wt-color-text);
diff --git a/docs/templates/shortcodes/rawcode.html b/docs/templates/shortcodes/rawcode.html
new file mode 100644
index 000000000..b4e06a0ef
--- /dev/null
+++ b/docs/templates/shortcodes/rawcode.html
@@ -0,0 +1 @@
+<code class="multiline">{{ body | safe }}</code>
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 54d4c5f3b..316b3157f 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -93,6 +93,11 @@ static RUST_RAW_STRING_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
static ZOLA_LINK_PATTERN: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r"\[([^\]]+)\]\(@/([^)#]+)\.md(#[^)]*)?\)").unwrap());
+/// Regex to convert Zola rawcode shortcode to HTML pre tags
+/// Matches: {% rawcode() %}...{% end %}
+static ZOLA_RAWCODE_PATTERN: LazyLock<Regex> =
+ LazyLock::new(|| Regex::new(r"(?s)\{% rawcode\(\) %\}(.*?)\{% end %\}").unwrap());
+
// =============================================================================
// Unified Template Infrastructure
// =============================================================================
@@ -685,14 +690,24 @@ fn heading_to_anchor(heading: &str) -> String {
/// Converts:
/// - `[text](@/page.md)` → `[text](https://worktrunk.dev/page/)`
/// - `[text](@/page.md#anchor)` → `[text](https://worktrunk.dev/page/#anchor)`
+/// - `{% rawcode() %}...{% end %}` → `<pre>...</pre>`
fn transform_zola_to_github(content: &str) -> String {
- ZOLA_LINK_PATTERN
+ // Transform internal links
+ let content = ZOLA_LINK_PATTERN
.replace_all(content, |caps: &regex::Captures| {
let text = caps.get(1).unwrap().as_str();
let page = caps.get(2).unwrap().as_str();
let anchor = caps.get(3).map_or("", |m| m.as_str());
format!("[{text}](https://worktrunk.dev/{page}/{anchor})")
})
+ .into_owned();
+
+ // Transform rawcode shortcodes to pre tags
+ ZOLA_RAWCODE_PATTERN
+ .replace_all(&content, |caps: &regex::Captures| {
+ let inner = caps.get(1).unwrap().as_str();
+ format!("<pre>{}</pre>", inner)
+ })
.into_owned()
}