Skip to content

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

Add LLM tool commands to example config as single source of truth (#1531)

Maximilian Roos5a2895cd03b2
diff --git a/Taskfile.yaml b/Taskfile.yaml
index 2ef47cdec..fd9366659 100644
--- a/Taskfile.yaml
+++ b/Taskfile.yaml
@@ -385,10 +385,10 @@ tasks:
# Documented commands from llm-commits.md
declare -A COMMANDS
- COMMANDS["claude"]='MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='"'"''"'"' --disable-slash-commands --setting-sources='"'"''"'"' --system-prompt='"'"''"'"''
+ COMMANDS["claude"]='CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='"'"''"'"' --disable-slash-commands --setting-sources='"'"''"'"' --system-prompt='"'"''"'"''
COMMANDS["llm"]='llm -m claude-haiku-4.5'
COMMANDS["aichat"]='aichat -m claude:claude-haiku-4.5'
- COMMANDS["codex"]='codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='"'"'low'"'"' --sandbox=read-only --json - | jq -sr '"'"'[.[] | select(.item.type? == "agent_message")] | last.item.text'"'"''
+ COMMANDS["codex"]='codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='"'"'low'"'"' -c system_prompt='"'"''"'"' --sandbox=read-only --json - | jq -sr '"'"'[.[] | select(.item.type? == "agent_message")] | last.item.text'"'"''
# Check which tools are available
echo "=== LLM Commit Message Benchmark ==="
diff --git a/dev/config.example.toml b/dev/config.example.toml
index e3a2ac38c..3bfdeca66 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -39,6 +39,16 @@
#
# Generate commit messages automatically during merge. Requires an external CLI tool.
#
+# ### Claude Code
+#
+# # [commit.generation]
+# # command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
+#
+# ### Codex
+#
+# # [commit.generation]
+# # command = "codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"
+#
# See LLM commits docs (https://worktrunk.dev/llm-commits/) for setup and Custom prompt templates (#custom-prompt-templates) for template customization.
#
# ## Command config
diff --git a/docs/content/config.md b/docs/content/config.md
index 5422943e2..f8f4fa1c6 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -53,7 +53,7 @@ Organizations can also deploy a system-wide config file for shared defaults —
worktree-path = ".worktrees/{{ branch | sanitize }}"
[commit.generation]
-command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
+command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
```
**Project config** — shared team settings:
@@ -111,6 +111,20 @@ worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"
Generate commit messages automatically during merge. Requires an external CLI tool.
+### Claude Code
+
+```toml
+# [commit.generation]
+# command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
+```
+
+### Codex
+
+```toml
+# [commit.generation]
+# command = "codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"
+```
+
See [LLM commits docs](@/llm-commits.md) for setup and [Custom prompt templates](#custom-prompt-templates) for template customization.
## Command config
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 6c4feaced..9292867d5 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -44,7 +44,7 @@ Organizations can also deploy a system-wide config file for shared defaults —
worktree-path = ".worktrees/{{ branch | sanitize }}"
[commit.generation]
-command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
+command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
```
**Project config** — shared team settings:
@@ -102,6 +102,20 @@ worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"
Generate commit messages automatically during merge. Requires an external CLI tool.
+### Claude Code
+
+```toml
+# [commit.generation]
+# command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
+```
+
+### Codex
+
+```toml
+# [commit.generation]
+# command = "codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"
+```
+
See [LLM commits docs](https://worktrunk.dev/llm-commits/) for setup and [Custom prompt templates](#custom-prompt-templates) for template customization.
## Command config
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 130e75604..3f876a84c 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1575,7 +1575,7 @@ Organizations can also deploy a system-wide config file for shared defaults —
worktree-path = ".worktrees/{{ branch | sanitize }}"
[commit.generation]
-command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
+command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
```
**Project config** — shared team settings:
@@ -1633,6 +1633,20 @@ worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"
Generate commit messages automatically during merge. Requires an external CLI tool.
+### Claude Code
+
+```toml
+# [commit.generation]
+# command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
+```
+
+### Codex
+
+```toml
+# [commit.generation]
+# command = "codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"
+```
+
See [LLM commits docs](@/llm-commits.md) for setup and [Custom prompt templates](#custom-prompt-templates) for template customization.
## Command config
diff --git a/src/output/commit_generation.rs b/src/output/commit_generation.rs
index 290ad3ad0..fba9ad626 100644
--- a/src/output/commit_generation.rs
+++ b/src/output/commit_generation.rs
@@ -4,7 +4,9 @@
//! attempt a commit without configuration. Detects available tools (claude, codex)
//! and offers to auto-configure the recommended settings.
+use std::collections::HashMap;
use std::io::{self, IsTerminal};
+use std::sync::LazyLock;
use color_print::cformat;
use worktrunk::config::UserConfig;
@@ -12,6 +14,15 @@ use worktrunk::styling::{eprintln, format_toml, hint_message, info_message, succ
use super::prompt::{PromptResponse, prompt_yes_no_preview};
+/// Example config file content, used to extract recommended commands.
+const CONFIG_EXAMPLE: &str = include_str!("../../dev/config.example.toml");
+
+/// Recommended commands parsed from the config example file (single source of truth).
+///
+/// Keyed by the h3 heading text in the config example (e.g., "Claude Code", "Codex").
+static RECOMMENDED_COMMANDS: LazyLock<HashMap<String, String>> =
+ LazyLock::new(|| parse_recommended_commands(CONFIG_EXAMPLE));
+
/// Detected LLM tool available on the system.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LlmTool {
@@ -28,19 +39,22 @@ impl LlmTool {
}
}
- /// Returns the recommended configuration command for this tool.
- ///
- /// These must match the examples in docs/content/llm-commits.md.
- pub fn recommended_config(&self) -> &'static str {
+ /// The h3 heading text in config.example.toml for this tool's section.
+ fn config_heading(&self) -> &'static str {
match self {
- LlmTool::Claude => {
- "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
- }
- LlmTool::Codex => {
- r#"codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='low' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == "agent_message")] | last.item.text'"#
- }
+ LlmTool::Claude => "Claude Code",
+ LlmTool::Codex => "Codex",
}
}
+
+ /// Returns the recommended configuration command for this tool.
+ ///
+ /// Parsed from the double-commented examples in dev/config.example.toml,
+ /// which is the single source of truth for these commands.
+ pub fn recommended_config(&self) -> &str {
+ // Indexing is safe: all LlmTool variants have entries in the config example.
+ &RECOMMENDED_COMMANDS[self.config_heading()]
+ }
}
impl std::fmt::Display for LlmTool {
@@ -49,6 +63,38 @@ impl std::fmt::Display for LlmTool {
}
}
+/// Parse tool commands from the double-commented config example.
+///
+/// Scans the entire file for `# ### ToolName` headings followed by `# # command = "..."`
+/// lines. Currently only the LLM section uses this pattern; if other sections gain
+/// `# # command = ` lines, scope the scan to the `## LLM commit messages` section.
+/// The command value is TOML-unescaped via the `toml` crate.
+fn parse_recommended_commands(config: &str) -> HashMap<String, String> {
+ let mut commands = HashMap::new();
+ let mut current_heading: Option<String> = None;
+
+ for line in config.lines() {
+ // H3 headings: "# ### Claude Code", "# ### Codex"
+ if let Some(heading) = line.strip_prefix("# ### ") {
+ current_heading = Some(heading.trim().to_string());
+ continue;
+ }
+
+ // Double-commented command: "# # command = "...""
+ if let Some(toml_part) = line.strip_prefix("# # ")
+ && toml_part.starts_with("command = ")
+ && let Some(heading) = current_heading.take()
+ {
+ // Config example is compile-time data; unwrap is safe.
+ let table: toml::Table = toml_part.parse().unwrap();
+ let cmd = table["command"].as_str().unwrap().to_string();
+ commands.insert(heading, cmd);
+ }
+ }
+
+ commands
+}
+
/// Check if a command is available in PATH.
///
/// Uses platform-appropriate method: `where` on Windows, `which` on Unix.
@@ -198,8 +244,46 @@ mod tests {
#[test]
fn test_llm_tool_recommended_config() {
- assert_snapshot!(LlmTool::Claude.recommended_config(), @"MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''");
- assert_snapshot!(LlmTool::Codex.recommended_config(), @r#"codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='low' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == "agent_message")] | last.item.text'"#);
+ assert_snapshot!(LlmTool::Claude.recommended_config(), @"CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''");
+ assert_snapshot!(LlmTool::Codex.recommended_config(), @r#"codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == "agent_message")] | last.item.text'"#);
+ }
+
+ #[test]
+ fn test_parse_recommended_commands() {
+ let config = "\
+# ### MyTool
+#
+# # [commit.generation]
+# # command = \"echo hello\"
+#
+# ### OtherTool
+#
+# # [commit.generation]
+# # command = \"jq -sr '[.[] | select(.type? == \\\"msg\\\")]'\"
+";
+ let commands = parse_recommended_commands(config);
+ assert_eq!(commands.len(), 2);
+ assert_eq!(commands["MyTool"], "echo hello");
+ assert_eq!(
+ commands["OtherTool"],
+ r#"jq -sr '[.[] | select(.type? == "msg")]'"#
+ );
+ }
+
+ #[test]
+ fn test_parse_recommended_commands_ignores_non_command_lines() {
+ let config = "\
+# ### ToolA
+#
+# # [commit.generation]
+# # template = \"not a command\"
+# ### ToolB
+# # command = \"real command\"
+";
+ let commands = parse_recommended_commands(config);
+ // ToolA has no command line, ToolB does
+ assert_eq!(commands.len(), 1);
+ assert_eq!(commands["ToolB"], "real command");
}
#[test]
@@ -217,7 +301,7 @@ mod tests {
// Long commands stay as single-line TOML
let cmd = LlmTool::Claude.recommended_config();
let result = format_command_for_display(cmd);
- assert_snapshot!(result, @r#""MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''""#);
+ assert_snapshot!(result, @r#""CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''""#);
}
#[test]
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 15b3a18b4..8752ac030 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -1092,6 +1092,51 @@ fn test_config_docs_include_all_sections() {
}
}
+/// Verify that LLM tool commands in docs/content/llm-commits.md match
+/// the double-commented examples in config.example.toml (the single source of truth).
+#[test]
+fn test_llm_docs_commands_match_config_example() {
+ let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
+ let config_example = fs::read_to_string(project_root.join("dev/config.example.toml")).unwrap();
+ let llm_docs = fs::read_to_string(project_root.join("docs/content/llm-commits.md")).unwrap();
+
+ // Extract commands from config example: "# # command = ..." lines
+ let config_commands: Vec<String> = config_example
+ .lines()
+ .filter_map(|line| line.strip_prefix("# # "))
+ .filter(|line| line.starts_with("command = "))
+ .filter_map(|line| {
+ let table: toml::Table = toml::from_str(line).ok()?;
+ Some(table["command"].as_str()?.to_string())
+ })
+ .collect();
+
+ // Extract commands from llm-commits.md: "command = ..." lines in TOML code blocks
+ let doc_commands: Vec<String> = llm_docs
+ .lines()
+ .filter(|line| line.starts_with("command = "))
+ .filter_map(|line| {
+ let table: toml::Table = toml::from_str(line).ok()?;
+ Some(table["command"].as_str()?.to_string())
+ })
+ .collect();
+
+ assert!(
+ config_commands.len() >= 2,
+ "Expected at least 2 tool commands in config.example.toml, found {}",
+ config_commands.len()
+ );
+
+ for cmd in &config_commands {
+ assert!(
+ doc_commands.contains(cmd),
+ "Command from config.example.toml not found in docs/content/llm-commits.md:\n {cmd}\n\
+ Update llm-commits.md to match the config example (source of truth: dev/config.example.toml, \
+ generated from src/cli/mod.rs)."
+ );
+ }
+}
+
#[test]
fn test_config_source_templates_are_in_sync() {
let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index 747b0cf89..6100555d5 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -98,6 +98,16 @@ Creates ~/.config/worktrunk/config.toml with the following content:
  #
  # Generate commit messages automatically during merge. Requires an external CLI tool.
  #
+  # ### Claude Code
+  #
+  # # [commit.generation]
+  # # command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
+  #
+  # ### Codex
+  #
+  # # [commit.generation]
+  # # command = "codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"
+  #
  # See LLM commits docs (https://worktrunk.dev/llm-commits/) for setup and Custom prompt templates (#custom-prompt-templates) for template customization.
  #
  # ## Command config
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 9d35cf643..a1dc20b4e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -91,7 +91,7 @@ Organizations can also deploy a system-wide config file for shared defaults —
  worktree-path = ".worktrees/{{ branch | sanitize }}"
 
  [commit.generation]
-  command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
+  command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
Project config — shared team settings:
@@ -143,6 +143,16 @@ Controls where new worktrees are created.
Generate commit messages automatically during merge. Requires an external CLI tool.
+Claude Code
+
+  # [commit.generation]
+  # command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"
+
+Codex
+
+  # [commit.generation]
+  # command = "codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"
+
See LLM commits docs for setup and Custom prompt templates for template customization.
Command config