Skip to content

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

feat: Improve CI visibility and documentation

Maximilian Roos1b8197f0b02e
diff --git a/.claude-plugin/skills/worktrunk/reference/README.md b/.claude-plugin/skills/worktrunk/reference/README.md
index 893b1cb37..2609545b7 100644
--- a/.claude-plugin/skills/worktrunk/reference/README.md
+++ b/.claude-plugin/skills/worktrunk/reference/README.md
@@ -20,6 +20,8 @@ Worktrunk offers control, transparency & automation for this workflow.
## Demo
+List worktrees, create a worktree, make a trivial change, merge the change:
+
![Worktrunk Demo](dev/wt-demo/out/wt-demo.gif)
## Quick Start
@@ -33,7 +35,7 @@ $ wt switch --create fix-auth
✅ Created new worktree for fix-auth from main at ../repo.fix-auth/
```
-...then do work / have an agent do work. Then, when ready...
+...then do work. Then, when ready...
**Merge it:**
@@ -79,23 +81,18 @@ See [Shell Integration](#shell-integration) for details.
## Design Philosophy
-Worktrunk is opinionated! It's not designed to be all things to all people. Its
-choices optimize for parallel AI agent workflow:
+Worktrunk is opinionated! Currently the workflow that best optimizes for zero marginal cost of parallel agents:
-- Trunk-based development
-- Lots of short-lived worktrees
-- Terminal-based, both coding agents & shell navigation
-- Inner dev loops are local
-- Linear commit histories
+- Trunk-based — lots of short-lived worktrees, linear commit histories
+- Local — terminal-based agents, local inner dev loops
...and that means...
-- Total focus on zero-cost of additional parallel agents
-- A fairly small surface area: three core commands
- - Worktrees are addressed by their branch
- Maximum automation: LLM commit messages, lifecycle hooks, Claude Code hooks
- - A robust "run auto-merge when 'local-CI' passes" approach
-- Defaults for commits is "everything and squash merge" (but configurable)
+ - A robust "auto-merge when 'local-CI' passes" approach
+- A small surface area: three core commands
+- 1:1 mapping between worktree and branch, worktrees are addressed by their branch
+- Defaults to "stage everything and squash merge" (but configurable)
- Extreme UI responsiveness; slow ops can't delay fast ones
- Pluggable; adopting Worktrunk for a portion of a workflow doesn't require
adopting it for everything. standard `git worktree` commands continue working
@@ -144,13 +141,13 @@ For more details, including custom prompt templates: `wt config --help`
Automate tasks at different points in the worktree lifecycle. Configure hooks in `.config/wt.toml`.
-| Hook | When | On Failure |
-| ----------------------- | ---------------------------------------- | ---------------- |
-| **post-create-command** | After worktree created | Warn, continue |
-| **post-start-command** | After success message (background) | Warn, continue |
-| **pre-commit-command** | Before squash commit created | Stop merge |
-| **pre-merge-command** | After squash, before push | Stop merge |
-| **post-merge-command** | After successful merge | Warn, continue |
+| Hook | When | On Failure |
+| ----------------------- | ---------------------------------- | -------------- |
+| **post-create-command** | After worktree created | Warn, continue |
+| **post-start-command** | After success message (background) | Warn, continue |
+| **pre-commit-command** | Before squash commit created | Stop merge |
+| **pre-merge-command** | After squash, before push | Stop merge |
+| **post-merge-command** | After successful merge | Warn, continue |
```toml
# Install dependencies, build setup
@@ -804,9 +801,7 @@ The custom emoji appears directly after the git status symbols.
<details>
<summary>Automation with Claude Code Hooks</summary>
-Claude Code can automatically set/clear emoji status when coding sessions start and end. This shows which branches have active AI sessions.
-
-**Easy setup:** The Worktrunk repository includes a `.claude-plugin` directory with pre-configured hooks.
+Claude Code can automatically set/clear emoji status when coding sessions start and end.
When using Claude:
@@ -814,8 +809,6 @@ When using Claude:
- Changes to `💬` when Claude needs input (waiting for permission or idle)
- Clears the status completely when the session ends
-**Status from another terminal:**
-
<!-- Output from: tests/snapshots/integration__integration_tests__list__with_user_status.snap -->
```bash
@@ -839,31 +832,22 @@ $ wt list
</details>
-</details>
-
-### Custom Worktree Paths
-
-By default, worktrees live as siblings to the main repo:
+### Customization
-```
-myapp/ # main worktree
-myapp.feature-x/ # secondary worktree
-myapp.bugfix-y/ # secondary worktree
-```
+By default, worktrees live as siblings to the main repo (`myapp.feature-x/`).
-Customize the pattern in `~/.config/worktrunk/config.toml`:
+Run `wt config --help` for details on customizing paths, commit templates, and more.
-```toml
-# Inside the repo (keeps everything contained)
-worktree-path = ".worktrees/{{ branch }}"
+## Status
-# Shared directory with multiple repos
-worktree-path = "../worktrees/{{ main_worktree }}/{{ branch }}"
-```
+Worktrunk is in active development. The core features are stable and ready for
+use. There may be backward-incompatible changes.
-## Status
+The most helpful way to contribute:
-Worktrunk is in active development. The core features are stable and ready for use. While the project is pre-1.0, the CLI interface and major features are unlikely to change significantly.
+- Use it!
+- Star the repo / tell friends / post about it
+- Find bugs, file reproducible bug reports
<details>
<summary>Developing</summary>
diff --git a/src/commands/list/ci_status.rs b/src/commands/list/ci_status.rs
index 408e53edf..9f56b486a 100644
--- a/src/commands/list/ci_status.rs
+++ b/src/commands/list/ci_status.rs
@@ -87,13 +87,17 @@ impl PrStatus {
fn detect_github(branch: &str, local_head: &str, repo_root: &str) -> Option<Self> {
// Check if gh is available and authenticated
- if !Command::new("gh")
- .args(["auth", "status"])
- .output()
- .map(|o| o.status.success())
- .unwrap_or(false)
- {
- return None;
+ let auth = Command::new("gh").args(["auth", "status"]).output();
+ match auth {
+ Err(e) => {
+ log::debug!("gh not available for {}: {}", branch, e);
+ return None;
+ }
+ Ok(o) if !o.status.success() => {
+ log::debug!("gh not authenticated for {}", branch);
+ return None;
+ }
+ _ => {}
}
// Use `gh pr list --head` instead of `gh pr view` to handle numeric branch names correctly.
@@ -121,14 +125,32 @@ impl PrStatus {
// This handles forks correctly (gh will detect upstream repo from git context)
cmd.current_dir(repo_root);
- let output = cmd.output().ok()?;
+ let output = match cmd.output() {
+ Ok(output) => output,
+ Err(e) => {
+ log::warn!("gh pr list failed to execute for branch {}: {}", branch, e);
+ return None;
+ }
+ };
if !output.status.success() {
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ log::debug!("gh pr list failed for {}: {}", branch, stderr.trim());
return None;
}
// gh pr list returns an array, take the first (and only) item
- let pr_list: Vec<GitHubPrInfo> = serde_json::from_slice(&output.stdout).ok()?;
+ let pr_list: Vec<GitHubPrInfo> = match serde_json::from_slice(&output.stdout) {
+ Ok(list) => list,
+ Err(e) => {
+ log::warn!(
+ "Failed to parse gh pr list JSON for branch {}: {}",
+ branch,
+ e
+ );
+ return None;
+ }
+ };
let pr_info = pr_list.first()?;
// Only process open PRs
@@ -169,16 +191,38 @@ impl PrStatus {
}
// Get MR info for the branch
- let output = Command::new("glab")
+ let output = match Command::new("glab")
.args(["mr", "view", branch, "--output", "json"])
.output()
- .ok()?;
+ {
+ Ok(output) => output,
+ Err(e) => {
+ log::warn!(
+ "glab mr view failed to execute for branch {}: {}",
+ branch,
+ e
+ );
+ return None;
+ }
+ };
if !output.status.success() {
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ log::debug!("glab mr view failed for {}: {}", branch, stderr.trim());
return None;
}
- let mr_info: GitLabMrInfo = serde_json::from_slice(&output.stdout).ok()?;
+ let mr_info: GitLabMrInfo = match serde_json::from_slice(&output.stdout) {
+ Ok(info) => info,
+ Err(e) => {
+ log::warn!(
+ "Failed to parse glab mr view JSON for branch {}: {}",
+ branch,
+ e
+ );
+ return None;
+ }
+ };
// Only process open MRs
if mr_info.state != "opened" {
@@ -212,6 +256,7 @@ impl PrStatus {
fn detect_github_workflow(branch: &str, local_head: &str, repo_root: &str) -> Option<Self> {
// Check if gh is available and authenticated
+ // Note: We don't log auth failures here since detect_github already logged them
if !Command::new("gh")
.args(["auth", "status"])
.output()
@@ -246,13 +291,31 @@ impl PrStatus {
// This handles forks correctly (gh will detect upstream repo from git context)
cmd.current_dir(repo_root);
- let output = cmd.output().ok()?;
+ let output = match cmd.output() {
+ Ok(output) => output,
+ Err(e) => {
+ log::warn!("gh run list failed to execute for branch {}: {}", branch, e);
+ return None;
+ }
+ };
if !output.status.success() {
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ log::debug!("gh run list failed for {}: {}", branch, stderr.trim());
return None;
}
- let runs: Vec<GitHubWorkflowRun> = serde_json::from_slice(&output.stdout).ok()?;
+ let runs: Vec<GitHubWorkflowRun> = match serde_json::from_slice(&output.stdout) {
+ Ok(runs) => runs,
+ Err(e) => {
+ log::warn!(
+ "Failed to parse gh run list JSON for branch {}: {}",
+ branch,
+ e
+ );
+ return None;
+ }
+ };
let run = runs.first()?;
// Check if the workflow run matches our local HEAD commit
@@ -285,18 +348,40 @@ impl PrStatus {
}
// Get most recent pipeline for the branch using JSON output
- let output = Command::new("glab")
+ let output = match Command::new("glab")
.args(["ci", "list", "--per-page", "1", "--output", "json"])
.env("BRANCH", branch) // glab ci list uses BRANCH env var
.output()
- .ok()?;
+ {
+ Ok(output) => output,
+ Err(e) => {
+ log::warn!(
+ "glab ci list failed to execute for branch {}: {}",
+ branch,
+ e
+ );
+ return None;
+ }
+ };
if !output.status.success() {
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ log::debug!("glab ci list failed for {}: {}", branch, stderr.trim());
return None;
}
// Parse JSON output
- let pipelines: Vec<GitLabPipelineList> = serde_json::from_slice(&output.stdout).ok()?;
+ let pipelines: Vec<GitLabPipelineList> = match serde_json::from_slice(&output.stdout) {
+ Ok(pipelines) => pipelines,
+ Err(e) => {
+ log::warn!(
+ "Failed to parse glab ci list JSON for branch {}: {}",
+ branch,
+ e
+ );
+ return None;
+ }
+ };
let pipeline = pipelines.first()?;
// Check if the pipeline matches our local HEAD commit