Integrations Works with every AI coding agent

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, OpenAI Codex, OpenCode, Copilot CLI, Cursor, Cline, and Windsurf.

Claude Code Codex CLI OpenCode Copilot CLI Cursor Cline Windsurf

Requires Worktale CLI v1.5.0+ — npm install -g worktale@latest

01

Prerequisites

Worktale CLI

The plugin requires Worktale CLI v1.5.0 or higher installed globally. The Claude Code, Codex, and Copilot plugins ship a SessionEnd hook that captures session metrics automatically (tokens, cost, model, tools); per-commit narrative is added via worktale note. For rules-based integrations (Cursor, Cline, Windsurf) the worktale session add --write-note pattern does both in one call.

$ npm install -g worktale@latest

# Verify: worktale --version → 1.5.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

01

Claude Code

Plugin

Native plugin with marketplace distribution. The /worktale skill handles per-commit narrative. Session metrics are captured automatically when the session ends — no agent cooperation required.

Automated capture

Model, input & output tokens (including cache), cost in USD, tools used, MCP servers, session duration — all recorded automatically at session end. Cost matches what your account is charged.

claude code

# 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:

recommended

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.

Source: github.com/worktale/worktale-plugin

02

OpenAI Codex CLI

Skill + auto-capture

Skill drives per-commit narrative; a session hook records tokens, model, and computed cost automatically. No agent cooperation required.

terminal

# Install:

$ git clone https://github.com/worktale/worktale-codex-plugin.git

# Skill (per-commit narrative):

$ mkdir -p ~/.codex/skills/worktale

$ cp -r worktale-codex-plugin/skills/worktale/* ~/.codex/skills/worktale/

# Auto token + cost capture:

$ mkdir -p ~/.codex/hooks

$ cp worktale-codex-plugin/hooks/session-track.mjs ~/.codex/hooks/

$ cp worktale-codex-plugin/hooks/hooks.json ~/.codex/hooks.json

Automated capture

Model, input + cached + output tokens, computed cost, session duration — all recorded automatically when each session goes idle. Covers the GPT-5 / 4o / 4.1 / o3 / o4 / Codex-mini families. The agent only handles per-commit narrative.

Source: github.com/worktale/worktale-codex-plugin

03

OpenCode

Native plugin

Drop-in TypeScript plugin for the OpenCode plugin framework. Aggregates session metrics in real time and records them automatically after each session goes idle.

terminal

# 1. Drop the plugin file into your project:

$ mkdir -p .opencode/plugins

$ curl -o .opencode/plugins/worktale.ts \

https://raw.githubusercontent.com/worktale/worktale-opencode-plugin/main/src/index.ts

# 2. Reference it in .opencode/opencode.jsonc:

{ "plugin": ["./.opencode/plugins/worktale.ts"] }

Automated capture

Provider, model, input + cached + output + reasoning tokens, exact cost (matches the host’s own ledger), tools used, duration. All recorded without agent cooperation.

Source: github.com/worktale/worktale-opencode-plugin

04

GitHub Copilot CLI

Agent + auto-capture

Agent drives per-commit narrative; a session hook records tokens, model, tools, MCP servers, and exact cost automatically — matching what your subscription is charged.

terminal

# Install:

$ git clone https://github.com/worktale/worktale-copilot-plugin.git

# Agent (per-commit narrative):

$ mkdir -p .github/copilot

$ cp worktale-copilot-plugin/agents/worktale.md .github/copilot/

# Auto token + cost capture:

$ mkdir -p ~/.copilot/hooks

$ cp worktale-copilot-plugin/hooks/session-track.mjs ~/.copilot/hooks/

$ cp worktale-copilot-plugin/hooks/hooks.json ~/.copilot/hooks.json

Automated capture

Model, input + cached + output tokens, exact cost, tools, MCP servers, duration — all recorded automatically when each session goes idle. Cost matches what Copilot bills.

Source: github.com/worktale/worktale-copilot-plugin

04

Cursor

Rules

Add Worktale narration instructions to your Cursor rules. The agent will follow them and run worktale note after each commit.

terminal

# 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.

05

Cline

Rules

Add Worktale narration rules to .clinerules/. Cline automatically loads all rule files in the directory.

terminal

# 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

06

Windsurf

Rules

Add Worktale narration rules to .windsurf/rules/.

terminal

# 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.

terminal

# 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	Narrative	Tokens & cost	Tools & MCP
Claude Code	Plugin + auto-capture	✓ per commit	✓ automated	✓ automated
Copilot CLI	Agent + auto-capture	✓ per commit	✓ automated	✓ automated
Codex CLI	Skill + auto-capture	✓ per commit	✓ automated	✓ automated (model)
OpenCode	Native plugin	✓ per commit	✓ automated	✓ automated
Cursor	Rules file	✓ per commit	Manual only	Agent-supplied
Cline	Rules file	✓ per commit	Manual only	Agent-supplied
Windsurf	Rules file	✓ per commit	Manual only	Agent-supplied
Git hook	Post-commit	—	—	—

Auto = the plugin records the field without agent cooperation. Agent = filled in by the AI agent at session end. Four official hosts get automated tokens + cost; rules-based hosts (Cursor/Cline/Windsurf) are agent-supplied.

04

What gets captured

Narrative (every host)

✓ 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

NOT written

✗ File paths or line counts (git has this)
✗ Raw diffs or code snippets
✗ Mechanical descriptions ("Updated 3 files")
✗ Source code or secrets

Session metrics (where supported)

Field	Claude Code	Codex	OpenCode	Copilot
Provider / model	Auto	Auto	Auto	Auto
Input / output tokens	Auto	Auto	Auto	Auto
Cost in USD	Auto	Auto	Auto	Auto
Tools used	Auto	Agent	Auto	Auto
MCP servers	Auto	—	—	Auto
Duration	Auto	Auto	Auto	Auto
Commits	Agent	Agent	Agent	Agent

Auto = recorded automatically without agent cooperation. Agent = filled in by the AI agent at session end. Manual = supply the flag yourself when calling worktale session add.

05

How it works

1

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.

2

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.

3

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.

4

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.

06

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.

Open source

Both the CLI and the plugin are MIT-licensed. Read every line.

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

Worktale for AI Coding Agents

Prerequisites

Worktale CLI

Initialize your repo

Claude Code

OpenAI Codex CLI

OpenCode

GitHub Copilot CLI

Cursor

Cline

Windsurf

Universal: Git Post-Commit Hook

Integration comparison

What gets captured

Narrative (every host)

NOT written

Session metrics (where supported)

How it works

Privacy

FAQ

Resources

Worktale for
AI Coding Agents