Skip to content

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.md
index 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.md
index 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.md
index 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.