Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(agents): document the activity-marker contract for agent CLIs without a plugin (#3848)
Worktrunk Bota6f26e5c6a6a
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.mdindex 4bd54db69..d65451ef3 100644--- a/docs/content/claude-code.md+++ b/docs/content/claude-code.md@@ -95,6 +95,22 @@ Set status markers manually for any workflow:<span class="cmd">git config worktrunk.state.feature.marker '{"marker":"π¬","set_at":0}' # Direct</span>{% end %}+### Agent CLIs without a plugin++Activity tracking is not plugin-specific. The plugins above only call `wt` on their host's session events, and the marker itself is plain git config β so any CLI that can run a command on session lifecycle events drives the same π€/π¬ markers with no worktrunk plugin:++| Host event | Command |+|---|---|+| Session starts, or the agent resumes work | `wt config state marker set "π€"` |+| Agent finishes a turn and waits for input | `wt config state marker set "π¬"` |+| Session ends | `wt config state marker clear` |++Three things to get right:++- **Run the command inside the worktree.** Each one resolves the branch from its working directory, so a hook that runs elsewhere marks the wrong branch, and one that runs outside a repository fails. Where the host pins the working directory elsewhere, pass the global `-C <worktree>`, which moves both the repository lookup and the branch resolution; `--branch <branch>` names the branch but still needs the working directory to be inside the repository.+- **Don't let a failed marker call fail the session.** Both `set` and `clear` exit non-zero outside a repository, and hosts differ on what a non-zero hook does. Append `|| true` (or the host's equivalent) to every call unless you want that surfaced.+- **Clear on exit.** A marker set on session start persists until something clears it, so pair every set with a clear on the host's session-end event β and expect the same stale marker as above if the process is killed first.+## Worktree isolation (Claude Code only)Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management.diff --git a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md b/plugins/worktrunk/skills/worktrunk/reference/claude-code.mdindex 44728d87a..3a68f0ba6 100644--- a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md+++ b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md@@ -97,6 +97,22 @@ $ wt config state marker set "β " --branch feature # Specific branch$ git config worktrunk.state.feature.marker '{"marker":"π¬","set_at":0}' # Direct```+### Agent CLIs without a plugin++Activity tracking is not plugin-specific. The plugins above only call `wt` on their host's session events, and the marker itself is plain git config β so any CLI that can run a command on session lifecycle events drives the same π€/π¬ markers with no worktrunk plugin:++| Host event | Command |+|---|---|+| Session starts, or the agent resumes work | `wt config state marker set "π€"` |+| Agent finishes a turn and waits for input | `wt config state marker set "π¬"` |+| Session ends | `wt config state marker clear` |++Three things to get right:++- **Run the command inside the worktree.** Each one resolves the branch from its working directory, so a hook that runs elsewhere marks the wrong branch, and one that runs outside a repository fails. Where the host pins the working directory elsewhere, pass the global `-C <worktree>`, which moves both the repository lookup and the branch resolution; `--branch <branch>` names the branch but still needs the working directory to be inside the repository.+- **Don't let a failed marker call fail the session.** Both `set` and `clear` exit non-zero outside a repository, and hosts differ on what a non-zero hook does. Append `|| true` (or the host's equivalent) to every call unless you want that surfaced.+- **Clear on exit.** A marker set on session start persists until something clears it, so pair every set with a clear on the host's session-end event β and expect the same stale marker as above if the process is killed first.+## Worktree isolation (Claude Code only)Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management.diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.mdindex 44728d87a..3a68f0ba6 100644--- a/skills/worktrunk/reference/claude-code.md+++ b/skills/worktrunk/reference/claude-code.md@@ -97,6 +97,22 @@ $ wt config state marker set "β " --branch feature # Specific branch$ git config worktrunk.state.feature.marker '{"marker":"π¬","set_at":0}' # Direct```+### Agent CLIs without a plugin++Activity tracking is not plugin-specific. The plugins above only call `wt` on their host's session events, and the marker itself is plain git config β so any CLI that can run a command on session lifecycle events drives the same π€/π¬ markers with no worktrunk plugin:++| Host event | Command |+|---|---|+| Session starts, or the agent resumes work | `wt config state marker set "π€"` |+| Agent finishes a turn and waits for input | `wt config state marker set "π¬"` |+| Session ends | `wt config state marker clear` |++Three things to get right:++- **Run the command inside the worktree.** Each one resolves the branch from its working directory, so a hook that runs elsewhere marks the wrong branch, and one that runs outside a repository fails. Where the host pins the working directory elsewhere, pass the global `-C <worktree>`, which moves both the repository lookup and the branch resolution; `--branch <branch>` names the branch but still needs the working directory to be inside the repository.+- **Don't let a failed marker call fail the session.** Both `set` and `clear` exit non-zero outside a repository, and hosts differ on what a non-zero hook does. Append `|| true` (or the host's equivalent) to every call unless you want that surfaced.+- **Clear on exit.** A marker set on session start persists until something clears it, so pair every set with a clear on the host's session-end event β and expect the same stale marker as above if the process is killed first.+## Worktree isolation (Claude Code only)Claude Code agents can run in isolated worktrees (`isolation: "worktree"`). By default, Claude Code creates these with `git worktree add`. The plugin's `WorktreeCreate` and `WorktreeRemove` hooks route this through `wt switch --create` and `wt remove` instead, so worktrees created by agents get worktrunk's naming conventions, hooks, and lifecycle management.