Skip to content

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

Add `intro` page to documentation

Maximilian Roosb1c0be741533
diff --git a/docs/content/advanced.md b/docs/content/advanced.md
index 36c6f3ef8..fb5771474 100644
--- a/docs/content/advanced.md
+++ b/docs/content/advanced.md
@@ -1,6 +1,6 @@
+++
title = "Advanced Features"
-weight = 6
+weight = 7
+++
Most Worktrunk users get everything they need from `wt switch`, `wt list`, `wt merge`, and `wt remove`. The features below are optional power-user capabilities.
@@ -13,14 +13,20 @@ Worktrunk includes a Claude Code plugin for tracking agent status across worktre
The plugin adds status indicators to `wt list`:
-```bash
-$ wt list
- Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message
-@ main ^ ./repo b834638e 1d Initial commit
-+ feature-api ↑ 🤖 ↑1 ./repo.feature-api 9606cd0f 1d Add REST API endpoints
-+ review-ui ? ↑ 💬 ↑1 ./repo.review-ui afd3b353 1d Add dashboard component
-+ wip-docs ?_ ./repo.wip-docs b834638e 1d Initial commit
-```
+<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__with_user_marker.snap — edit source to update -->
+
+{% terminal() %}
+<span class="prompt">$</span> wt list
+ <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>main</b> <span style='opacity:0.67'>^</span> <b>./repo</b> <span style='opacity:0.67'>b834638e</span> <span style='opacity:0.67'>1d</span> <span style='opacity:0.67'>Initial commit</span>
++ feature-api <span style='opacity:0.67'>↑</span> 🤖 <span style='color:var(--green,#0a0)'>↑1</span> ./repo.feature-api <span style='opacity:0.67'>9606cd0f</span> <span style='opacity:0.67'>1d</span> <span style='opacity:0.67'>Add REST API endpoints</span>
++ review-ui <span style='color:var(--cyan,#0aa)'>?</span> <span style='opacity:0.67'>↑</span> 💬 <span style='color:var(--green,#0a0)'>↑1</span> ./repo.review-ui <span style='opacity:0.67'>afd3b353</span> <span style='opacity:0.67'>1d</span> <span style='opacity:0.67'>Add dashboard component</span>
++ <span style='opacity:0.67'>wip-docs</span> <span style='color:var(--cyan,#0aa)'>?</span><span style='opacity:0.67'>_</span> <span style='opacity:0.67'>./repo.wip-docs</span> <span style='opacity:0.67'>b834638e</span> <span style='opacity:0.67'>1d</span> <span style='opacity:0.67'>Initial commit</span>
+
+⚪ <span style='opacity:0.67'>Showing 4 worktrees, 2 ahead</span>
+{% end %}
+
+<!-- END AUTO-GENERATED -->
- `🤖` — Claude is working
- `💬` — Claude is waiting for input
@@ -44,7 +50,9 @@ $ git config worktrunk.marker.feature "💬" # Direct git config
## Statusline Integration
-`wt list statusline` outputs a single-line status for shell prompts, starship, or editor integrations.
+`wt list statusline` outputs a single-line status for shell prompts, starship, or editor integrations.[^1]
+
+[^1]: Currently this grabs CI status, so is too slow to use in synchronous contexts. If a faster version would be helpful, please [open an issue](https://github.com/max-sixty/worktrunk/issues).
### Claude Code statusline
diff --git a/docs/content/commands.md b/docs/content/commands.md
index 07003c5a2..b4f2a54bf 100644
--- a/docs/content/commands.md
+++ b/docs/content/commands.md
@@ -1,6 +1,6 @@
+++
title = "Commands Reference"
-weight = 4
+weight = 5
+++
## wt switch
@@ -692,6 +692,9 @@ Global Options:
## wt select
+<!-- TODO: This content should come from `wt select --help-md` like other commands.
+ Add the keyboard shortcuts to the help text in the codebase. -->
+
Interactive fzf-like fuzzy-search worktree picker with diff preview. Unix only.
Navigate worktrees with keyboard shortcuts:
diff --git a/docs/content/concepts.md b/docs/content/concepts.md
index 402b559bb..8c96fcf2d 100644
--- a/docs/content/concepts.md
+++ b/docs/content/concepts.md
@@ -1,6 +1,6 @@
+++
title = "Concepts"
-weight = 2
+weight = 3
+++
## Why git worktrees?
@@ -29,6 +29,65 @@ Git's built-in `worktree` commands require remembering worktree locations and co
| List | `wt list` (with diffstats & status) | `git worktree list` (just names & paths) |
| List with CI status | `wt list --full` | N/A |
+### Local merging with `wt merge`
+
+`wt merge` handles the full merge workflow: stage, commit, squash, rebase, merge, cleanup. Includes LLM commit messages, project hooks, and flags for skipping steps.
+
+| Task | Worktrunk | Plain git |
+|------|-----------|-----------|
+| Merge + clean up | `wt merge` | `git add -A && git reset --soft $(git merge-base HEAD main) && git diff --staged \| llm "..." \| git commit -F - && git rebase main && cargo test && cd ../repo && git merge --ff-only feature && git worktree remove ../repo.feature && git branch -d feature && cargo install --path .` |
+
+<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap — edit source to update -->
+
+{% terminal() %}
+<span class="prompt">$</span> wt merge
+🔄 <span style='color:var(--cyan,#0aa)'>Squashing 3 commits into a single commit <span style='color:var(--bright-black,#555)'>(3 files, <span style='color:var(--green,#0a0)'>+33</span></span></span><span style='color:var(--bright-black,#555)'>)</span>...
+🔄 <span style='color:var(--cyan,#0aa)'>Generating squash commit message...</span>
+<span style='background:var(--bright-white,#fff)'> </span> <b>feat(auth): Implement JWT authentication system</b>
+<span style='background:var(--bright-white,#fff)'> </span>
+<span style='background:var(--bright-white,#fff)'> </span> Add comprehensive JWT token handling including validation, refresh logic,
+<span style='background:var(--bright-white,#fff)'> </span> and authentication tests. This establishes the foundation for secure
+<span style='background:var(--bright-white,#fff)'> </span> API authentication.
+<span style='background:var(--bright-white,#fff)'> </span>
+<span style='background:var(--bright-white,#fff)'> </span> - Implement token refresh mechanism with expiry handling
+<span style='background:var(--bright-white,#fff)'> </span> - Add JWT encoding/decoding with signature verification
+<span style='background:var(--bright-white,#fff)'> </span> - Create test suite covering all authentication flows
+✅ <span style='color:var(--green,#0a0)'>Squashed @ <span style='opacity:0.67'>95c3316</span></span>
+🔄 <span style='color:var(--cyan,#0aa)'>Running pre-merge <b>test</b>:</span>
+<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>cargo</span></span><span style='opacity:0.67'> test</span>
+ Finished test [unoptimized + debuginfo] target(s) in 0.12s
+ Running unittests src/lib.rs (target/debug/deps/worktrunk-abc123)
+
+running 18 tests
+test auth::tests::test_jwt_decode ... ok
+test auth::tests::test_jwt_encode ... ok
+test auth::tests::test_token_refresh ... ok
+test auth::tests::test_token_validation ... ok
+
+test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s
+🔄 <span style='color:var(--cyan,#0aa)'>Running pre-merge <b>lint</b>:</span>
+<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>cargo</span></span><span style='opacity:0.67'> clippy</span>
+ Checking worktrunk v0.1.0
+ Finished dev [unoptimized + debuginfo] target(s) in 1.23s
+🔄 <span style='color:var(--cyan,#0aa)'>Merging 1 commit to <b>main</b> @ <span style='opacity:0.67'>95c3316</span> (no rebase needed)</span>
+<span style='background:var(--bright-white,#fff)'> </span> * <span style='color:var(--yellow,#a60)'>95c3316</span> feat(auth): Implement JWT authentication system
+<span style='background:var(--bright-white,#fff)'> </span> auth.rs | 8 <span style='color:var(--green,#0a0)'>++++++++</span>
+<span style='background:var(--bright-white,#fff)'> </span> auth_test.rs | 17 <span style='color:var(--green,#0a0)'>+++++++++++++++++</span>
+<span style='background:var(--bright-white,#fff)'> </span> jwt.rs | 8 <span style='color:var(--green,#0a0)'>++++++++</span>
+<span style='background:var(--bright-white,#fff)'> </span> 3 files changed, 33 insertions(+)
+✅ <span style='color:var(--green,#0a0)'>Merged to <b>main</b> <span style='color:var(--bright-black,#555)'>(1 commit, 3 files, +33</span></span><span style='color:var(--bright-black,#555)'>)</span>
+🔄 <span style='color:var(--cyan,#0aa)'>Removing <b>feature-auth</b> worktree &amp; branch in background (already in main)</span>
+🔄 <span style='color:var(--cyan,#0aa)'>Running post-merge <b>install</b>:</span>
+<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>cargo</span></span><span style='opacity:0.67'> install </span><span style='opacity:0.67'><span style='color:var(--cyan,#0aa)'>--path</span></span><span style='opacity:0.67'> .</span>
+ Installing worktrunk v0.1.0
+ Compiling worktrunk v0.1.0
+ Finished release [optimized] target(s) in 2.34s
+ Installing ~/.cargo/bin/wt
+ Installed package `worktrunk v0.1.0` (executable `wt`)
+{% end %}
+
+<!-- END AUTO-GENERATED -->
+
### What Worktrunk adds
- **Branch-based navigation**: Address worktrees by branch name, not path
diff --git a/docs/content/configuration.md b/docs/content/configuration.md
index 15a92633c..4ca1fff01 100644
--- a/docs/content/configuration.md
+++ b/docs/content/configuration.md
@@ -1,8 +1,11 @@
+++
title = "Configuration"
-weight = 3
+weight = 4
+++
+<!-- TODO: This user config vs project config distinction is a good organizing
+ principle - consider orienting more of the docs around it -->
+
Worktrunk uses two configuration files:
- **User config**: `~/.config/worktrunk/config.toml` — Personal settings, LLM commands, saved approvals
diff --git a/docs/content/faq.md b/docs/content/faq.md
index d11048195..3cee0c329 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -1,6 +1,6 @@
+++
title = "FAQ"
-weight = 7
+weight = 8
+++
## What commands does Worktrunk execute?
@@ -15,7 +15,9 @@ Commands from project hooks and LLM configuration require approval on first run.
### Example approval prompt
-```
+<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_approval_prompt.snap — edit source to update -->
+
+```text
🟡 repo needs approval to execute 3 commands:
⚪ post-create install:
@@ -30,6 +32,8 @@ Commands from project hooks and LLM configuration require approval on first run.
💡 Allow and remember? [y/N]
```
+<!-- END AUTO-GENERATED -->
+
Use `--force` to bypass prompts (useful for CI/automation).
## How does Worktrunk compare to alternatives?
diff --git a/docs/content/intro.md b/docs/content/intro.md
new file mode 100644
index 000000000..10ff031aa
--- /dev/null
+++ b/docs/content/intro.md
@@ -0,0 +1,17 @@
++++
+title = "Intro"
+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. The goal is to make spinning up a new AI "developer" for a task feel as routine as `git switch`.
+
+![Worktrunk Demo](/wt-demo.gif)
+
+## Getting Started
+
+We recommend:
+
+- **Start with Worktrunk as a simpler & better `git worktree`**: create, navigate, list, and clean up git worktrees with ease
+- **Later use the more advanced features if they resonate**: [LLM commit messages](/configuration/#llm-commit-messages), [local merging with CI-like checks](/concepts/#local-merging-with-wt-merge), [fzf-like worktree picker](/commands/#wt-select), [Claude Code integration](/advanced/#claude-code-integration), and more
+
+Ready? Head to the [Quick Start](/quickstart/).
diff --git a/docs/content/quickstart.md b/docs/content/quickstart.md
index 7aa8c2706..aadb97f75 100644
--- a/docs/content/quickstart.md
+++ b/docs/content/quickstart.md
@@ -1,6 +1,6 @@
+++
title = "Quick Start"
-weight = 1
+weight = 2
+++
## Install
@@ -76,19 +76,8 @@ When you're done with a worktree (e.g., after merging via CI):
Worktrunk checks if your changes are already on main before deleting the branch.
-## Shortcuts
-
-Use these shortcuts for common targets:
-
-- `@` — current branch/worktree
-- `-` — previous worktree (like `cd -`)
-- `^` — main/default branch
-
-```bash
-$ wt switch - # Switch to previous worktree
-$ wt switch --create hotfix --base=@ # Branch from current HEAD
-$ wt remove @ # Remove current worktree
-```
+<!-- TODO: Add shortcuts (@, -, ^) somewhere more prominent in the docs -
+ too early for quickstart but should be discoverable -->
## Next steps
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 3e910576d..0434dada8 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -1,6 +1,6 @@
+++
title = "Tips & Patterns"
-weight = 5
+weight = 6
+++
Practical recipes for common Worktrunk workflows.
diff --git a/docs/static/wt-demo.gif b/docs/static/wt-demo.gif
new file mode 100644
index 000000000..47039f660
Binary files /dev/null and b/docs/static/wt-demo.gif differ
diff --git a/docs/templates/index.html b/docs/templates/index.html
index dd8cd1eb5..07f64e43d 100644
--- a/docs/templates/index.html
+++ b/docs/templates/index.html
@@ -107,14 +107,14 @@
{% endblock toc %}
{% block content %}
-{# Display quickstart content directly on homepage - relies on quickstart.md existing #}
+{# Display intro content directly on homepage #}
{% set docs_section = get_section(path="_index.md") %}
-{% set quickstart = docs_section.pages | filter(attribute="slug", value="quickstart") | first %}
-<div class="heading-text">{{ quickstart.title }}</div>
-{{ quickstart.content | safe }}
+{% set intro = docs_section.pages | filter(attribute="slug", value="intro") | first %}
+<div class="heading-text">{{ intro.title }}</div>
+{{ intro.content | safe }}
<div class="page-nav" style="justify-content: flex-end;">
- {% set concepts = docs_section.pages | filter(attribute="slug", value="concepts") | first %}
- <a href="{{ concepts.permalink | safe }}">{{ concepts.title }} →</a>
+ {% set quickstart = docs_section.pages | filter(attribute="slug", value="quickstart") | first %}
+ <a href="{{ quickstart.permalink | safe }}">{{ quickstart.title }} →</a>
</div>
{% endblock content %}
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 98dbc53cb..ea04fa314 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -808,6 +808,8 @@ fn test_docs_quickstart_examples_are_in_sync() {
let doc_files = [
"docs/content/quickstart.md",
"docs/content/configuration.md",
+ "docs/content/concepts.md",
+ "docs/content/advanced.md",
];
let mut all_errors = Vec::new();