>_
worktale university

university / course 03

Intermediate 7 lessons · ~60 min

AI Sessions.

The most differentiated feature of Worktale. Every AI coding session — tokens, cost, model, tools, MCP servers — captured automatically across Claude Code, OpenAI Codex, OpenCode, and GitHub Copilot. One dashboard for all four.

Lesson 3.1

The four-agent capture model.

WHAT YOU'LL LEARN

What an AI session is in Worktale's data model, what fields are captured, and how the four supported agents feed into the same local table.

Every AI coding session gets one row in the ai_sessions table. The shape is the same regardless of which agent produced it:

repo_idwhich project the session ran in
dateYYYY-MM-DD (local)
provideranthropic / openai / github / ...
modelclaude-opus-4-7 / gpt-5 / ...
toolclaude-code / codex / opencode / copilot
cost_usdcomputed from tokens × model price
input_tokensprompt + cached + system
output_tokenscompletion tokens
tools_usedJSON array: [Read, Edit, Bash, Grep]
mcp_serversJSON array: [github, claude-mem]
duration_secswall-clock session time
commitsJSON array of git shas made during session
notefree-form narrative from the agent

How each agent fills this in

  • Claude Code — the Worktale plugin's SessionEnd hook parses the live transcript JSONL and extracts every field above, automatically.
  • OpenAI Codex — plugin watches ~/.codex/sessions/YYYY/MM/DD/*.jsonl rollout files, extracts on session end.
  • OpenCode — native plugin via @opencode-ai/plugin event hooks.
  • GitHub Copilot — plugin reads ~/.copilot/session-state/<sessionId>/events.jsonl.

The agents never have to know about Worktale. The capture happens from files the agents already write to disk. No agent cooperation, no API keys, no telemetry.

KEY INSIGHT

“Session” here means “one agent conversation”, not “one command”. A 90-minute refactor with Claude Code = one session, one row, full token & cost total. The agent decides when a session ends; Worktale just captures what the agent already wrote to disk.

Lesson 3.2

Claude Code plugin.

WHAT YOU'LL LEARN

Install the Worktale plugin for Claude Code so every session's cost, tokens, tools, and MCP servers are captured automatically.

Install

From inside Claude Code:

> /plugin marketplace add worktale/worktale-plugin

Added marketplace: worktale

> /plugin install worktale-plugin@worktale-plugin

Installed worktale-plugin v1.4.x

What it does

  • Registers a SessionEnd hook with Claude Code.
  • When the session ends, parses the session transcript JSONL (which Claude Code writes to disk for every session).
  • Extracts model name, tokens (input/output/cache), final cost in USD, tools used, MCP servers invoked, and the full duration.
  • Calls worktale session add ... with the extracted fields, which inserts one row into the ai_sessions table.
  • Also calls worktale note "..." at natural commit boundaries so your Daily Log gets per-commit narrative context.

Verify it's working

Run a short Claude Code session (anything — ask it a question, let it edit a file), then exit. Then:

$ worktale session stats --days 1

⚡ AI Usage — today

  Sessions: 1 · Cost: $0.31 · Tokens: 58k in / 1.3k out

  Model: claude-opus-4-7

  Tools: Read, Edit, Bash, Grep

GOTCHA

The plugin captures on session end, not periodically. If Claude Code crashes or you force-kill it, the session may not be recorded. The partial transcript is still on disk; you can run worktale session add --from-claude-transcript /path/to/transcript.jsonl to import it manually. We cover this in Mastery (Lesson 7.7).

Lesson 3.3

Codex plugin.

WHAT YOU'LL LEARN

Install the Worktale Codex plugin so OpenAI Codex sessions are captured from their rollout JSONL files.

Codex writes a rollout JSONL per session at ~/.codex/sessions/YYYY/MM/DD/<session-id>.jsonl. The Worktale Codex plugin watches this directory and imports every rollout when it finishes.

Install

$ npm install -g worktale-codex-plugin

$ worktale-codex init

Watching ~/.codex/sessions/

✓ Background watcher started.

What gets captured

Same table, same shape. The rollout files contain token counts, model used, tools called (via the Codex tool-use events), and the full session duration. The plugin parses the JSONL line-by-line, aggregates, and writes one row per session.

Backfill existing sessions

# Import every historical Codex session from disk

$ worktale-codex import --since 2026-01-01

Imported 42 sessions (total cost: $18.40).

Lesson 3.4

OpenCode plugin.

WHAT YOU'LL LEARN

Use OpenCode's native plugin framework to capture session data into Worktale.

OpenCode has a first-class plugin API. Worktale's OpenCode plugin registers event hooks (onSessionStart, onSessionEnd, onToolCall) and emits one ai_session row at session end.

Install

$ opencode plugin install worktale-opencode-plugin

✓ Plugin registered.

What's different from Claude/Codex

Because OpenCode exposes structured events, this plugin gets more real-time data: tool calls are captured as they happen, token usage is streamed, and if a session crashes mid-flight, whatever fired before the crash is still recorded.

For Claude Code and Codex the capture is end-of-session only; for OpenCode it's progressive. The ai_sessions row still lands at session end, but with higher fidelity.

Lesson 3.5

Copilot plugin.

WHAT YOU'LL LEARN

Capture GitHub Copilot CLI sessions by tailing the events JSONL file Copilot already writes.

Copilot CLI writes per-session state to ~/.copilot/session-state/<sessionId>/events.jsonl. That file contains token usage and model identity events. The Worktale Copilot plugin tails these files and imports at session end.

Install

$ npm install -g worktale-copilot-plugin

$ worktale-copilot init

✓ Watching ~/.copilot/session-state/

GOTCHA

Copilot's event format is less rich than Claude's transcript. Tool-call granularity is lower, and MCP server info is not always present. We capture what's there and backfill the rest from commit history. Cost numbers are computed from token counts using the model's list price — if you're on an enterprise seat, your actual cost may differ.

Lesson 3.6

Manual session add.

WHAT YOU'LL LEARN

How to add a session manually — for agents without a plugin, for ad-hoc ChatGPT/Claude.ai work, or to fix a missed capture.

worktale session add takes the same fields the plugins fill in, via CLI flags. Use it when:

  • You pasted code from Claude.ai / ChatGPT / other agent without a plugin.
  • A plugin crashed mid-session and didn't record.
  • You want to attribute an AI-assisted commit to the right provider for cost tracking.

Example

$ worktale session add \

  --provider anthropic \

  --model claude-opus-4-7 \

  --tool claude-ai-web \

  --cost 0.80 \

  --input-tokens 12000 \

  --output-tokens 2500 \

  --duration 1800 \

  --note "pair-debugged the webhook issue with Claude on the web"

✓ Session added.

Minimum viable add

Only --provider and --tool are required. Everything else defaults to null / zero. Use this for quick attribution even when you don't have exact numbers:

$ worktale session add --provider openai --tool chatgpt-web --note "quick api design review"

Lesson 3.7

Reading AI stats.

WHAT YOU'LL LEARN

Three ways to look at your AI data: worktale session stats, the TUI AI Sessions tab, and the desktop app.

1. CLI: worktale session stats

$ worktale session stats --days 30

⚡ AI Usage — last 30 days

  Sessions: 147 · Cost: $184.20 · Tokens: 12.4M

By agent:

  claude-code   78 sessions   $94.30

  codex       41 sessions   $58.40

  opencode     19 sessions   $22.10

  copilot      9 sessions   $9.40

Add --format json for scripting, --format csv for spreadsheets. Covered in Course 04 Lesson 4.1.

2. TUI: AI Sessions tab

Open worktale, press 4. You get:

  • Four KPI totals (sessions, cost, tokens, active time) for the last 30 days.
  • Cost/day and tokens/day sparklines with peak labels.
  • Breakdowns for agents, models, providers, top tools, and MCP servers.

3. Desktop: full charts

The desktop app (Course 05) has an AI view with interactive charts, per-repo filtering, and model cost comparison. Same underlying data; better for exploration.

Cost attribution: per-project

Every session has a repo_id. The plugins attribute to whichever repo the agent was running in when the session started. So your Claude Opus spend on acme-portal is cleanly separable from your side-project spend. This is the single most valuable stat for freelancers — it makes AI cost pass-through trivial (covered in Mastery 7.3).

KEY INSIGHT

The cost numbers are list price computations from token counts. They're accurate if you pay per-token (API). They're indicative if you're on a subscription (Pro / Team). For subscription users, the tokens/sessions/tools numbers are still exact; only the dollar figure is a model estimate.