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.mdindex 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 -->## Installdiff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.mdindex 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 & 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.scssindex 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.htmlnew file mode 100644index 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.rsindex 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: ®ex::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: ®ex::Captures| {+ let inner = caps.get(1).unwrap().as_str();+ format!("<pre>{}</pre>", inner)+ }).into_owned()}