Worktale for
AI Coding Agents
Your AI coding agent automatically narrates every commit — adding intent, decisions, and context to your daily work journal. Works with Claude Code, Codex CLI, Copilot CLI, Cursor, Cline, and Windsurf.
Requires Worktale CLI v1.1.0+ — npm install -g worktale@latest
Prerequisites
Worktale CLI
The plugin requires Worktale CLI v1.1.0 or higher installed globally. It uses worktale note (introduced in v1.1.0) to write to your local journal.
$ npm install -g worktale@latest
# Verify: worktale --version → 1.1.0+
Initialize your repo
Run worktale init in any git repository you want to track. This scans your history and sets up capture hooks.
$ cd your-project
$ worktale init
✓ 847 commits analyzed in 2.1s
Claude Code
PluginNative plugin with marketplace distribution. The agent narrates after every commit via the /worktale skill.
# Step 1: Add the marketplace (one-time):
> /plugin marketplace add worktale/worktale-plugin
# Step 2: Install the plugin:
> /plugin install worktale-plugin@worktale-plugin
✓ Plugin "worktale" installed successfully
# Step 3: Restart Claude Code, then activate:
> /worktale
⚠ After installing, restart Claude Code (close and reopen) for the skill to be available. /reload-plugins may not be sufficient.
When prompted, choose an install scope:
Install for you (user scope)
Available in every project, every session. This is what most developers want — Worktale narrates wherever you code.
Install for all collaborators (project scope)
Adds the plugin to your repo’s config so teammates get it too. Good for teams that all use Worktale.
Install for you, in this repo only (local scope)
Only works in one specific repo. Use this if you just want to try it out first.
Once approved on the official Claude Code marketplace, this will simplify to a single install command.
OpenAI Codex CLI
SkillCodex uses the same SKILL.md format. Install the skill to ~/.agents/skills/worktale/ and enable skills mode.
# Install:
$ git clone https://github.com/worktale/worktale-codex-plugin.git
$ cp -r worktale-codex-plugin/skills/worktale ~/.agents/skills/worktale
# Run with skills enabled:
$ codex --enable skills
GitHub Copilot CLI
Plugin + HooksNative plugin with a postToolUse hook that deterministically captures every commit. Also ships a worktale agent for session narration.
# Install (one-time):
> /plugin install worktale/worktale-copilot-plugin
# Activate narration agent:
> /agent
# Select "worktale" from the list
Cursor
RulesAdd Worktale narration instructions to your Cursor rules. The agent will follow them and run worktale note after each commit.
# Copy the rules file into your project:
$ mkdir -p .cursor/rules
$ curl -o .cursor/rules/worktale.md \
https://raw.githubusercontent.com/worktale/worktale-cli/main/integrations/cursor-rules.md
Or copy from node_modules/worktale/integrations/cursor-rules.md if the CLI is installed.
Cline
RulesAdd Worktale narration rules to .clinerules/. Cline automatically loads all rule files in the directory.
# Copy the rules file into your project:
$ mkdir -p .clinerules
$ curl -o .clinerules/worktale.md \
https://raw.githubusercontent.com/worktale/worktale-cli/main/integrations/cline-rules.md
Windsurf
RulesAdd Worktale narration rules to .windsurf/rules/.
# Copy the rules file into your project:
$ mkdir -p .windsurf/rules
$ curl -o .windsurf/rules/worktale.md \
https://raw.githubusercontent.com/worktale/worktale-cli/main/integrations/windsurf-rules.md
For older Windsurf versions (pre-Wave 8), use .windsurfrules single file at project root instead. Rule files are limited to 6,000 characters each.
Universal: Git Post-Commit Hook
Works with every AI tool that commits via git — Aider, any IDE agent, or manual commits. This is deterministic and requires zero cooperation from the AI agent.
# Already built into Worktale:
$ worktale init
# Or install hooks on a specific repo:
$ worktale hook install
The post-commit hook runs worktale capture after every commit, regardless of which tool or person made it.
Integration comparison
| Platform | Type | Install | Per-commit? | Reliability |
|---|---|---|---|---|
| Claude Code | Plugin | /plugin install | ✓ Yes | Deterministic |
| Copilot CLI | Plugin + hooks | /plugin install | ✓ Yes | Deterministic |
| Codex CLI | Skill | git clone + copy | ✓ Yes | Advisory |
| Cursor | Rules file | curl + copy | ✓ Yes | Advisory |
| Cline | Rules file | curl + copy | ✓ Yes | Advisory |
| Windsurf | Rules file | curl + copy | ✓ Yes | Advisory |
| Git hook | Post-commit | worktale init | ✓ Yes | Deterministic |
Deterministic = enforced by hooks/plugins. Advisory = the agent follows instructions but isn't mechanically enforced. Combine with worktale hook install for guaranteed capture.
What gets captured
The agent writes
- ✓ Intent — why the change was made
- ✓ Decisions — trade-offs and alternatives considered
- ✓ Root causes — bugs found and how they were fixed
- ✓ Context — the high-level story of each change
The agent does NOT write
- ✗ File paths or line counts (git has this)
- ✗ Raw diffs or code snippets
- ✗ Mechanical descriptions ("Updated 3 files")
- ✗ Source code or secrets
How it works
Plugin installs the /worktale skill
The skill is a prompt template that instructs Claude how to narrate commits. It runs inside the existing Claude Code session — no background processes, no extra infrastructure.
After each git commit, the agent runs worktale note "..."
The agent composes a 1-2 sentence note from the session context — what it was asked to do, what it decided, what problems it solved.
Notes are stored in your local Worktale database
Each note is appended to the user_notes field in the daily_summaries table at ~/.worktale/data.db. Nothing leaves your machine.
Review everything in worktale digest or the dashboard
At end of day, your AI-narrated notes appear alongside commit stats, module activity, and streak data. Save the digest to build a long-term record of your work.
Privacy
Local-first
All notes are stored in a local SQLite database at ~/.worktale/data.db. No cloud, no API calls, no telemetry.
No code exfiltration
Notes contain narrative text, not source code. The agent writes about intent, not implementation details.
You own your data
Delete ~/.worktale/ and everything is gone. No account to close, no data retention policy to worry about.
FAQ
The worktale note command auto-registers repos that have a .git directory. However, for best results, run worktale init first to scan your history and install capture hooks.
Yes. The worktale note command is a standard CLI. You can call it from any script, CI pipeline, git hook, or AI tool. The plugin is just a convenient wrapper for Claude Code users.
No. The worktale note command writes to a local SQLite database and completes in under 50ms. The agent runs it right after each commit as a single shell command.
In Claude Code:
> /plugin uninstall worktale
The skill prompt is open source. Fork the plugin repo, edit skills/worktale/SKILL.md to change the narration style, and install your fork instead.
Resources
Claude Code plugin
github.com/worktale/worktale-plugin
Codex CLI skill
github.com/worktale/worktale-codex-plugin
Copilot CLI plugin
github.com/worktale/worktale-copilot-plugin
Worktale CLI
github.com/worktale/worktale-cli
Full documentation
worktale.org/docs — AI Integration
npm package
npmjs.com/package/worktale