Skip to main content
plugin CX Codex

aidd-telemetry — Claude Code plugin for token tracking

aidd-telemetry is a plugin for Claude Code that tracks token use in Claude Code and Codex sessions, grouped by task, model, or other dimensions. Records stay local.

MIT ★ 571 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add ai-driven-dev/framework
/plugin install aidd-telemetry@aidd-framework
Open on GitHub

What aidd-telemetry does

The plugin reads Claude Code and Codex session files, counting each model call once. Reports can group usage by person, session, model, agent, tool, day, repository, task, or ticket. You declare tasks and tickets yourself; the plugin does not infer them from conversation text.

Turn tracking on separately in each clone with aidd telemetry on. It records new activity from that point forward, and hooks ask for a task when the current branch has no declaration. The aidd-telemetry:00-init skill handles setup and identity choices; aidd-telemetry:01-usage helps request reports. Local records live in ~/.config/aidd/telemetry and the clone’s git config. Run forget --yes to erase them.

Hooks require node on PATH. Codex also requires one-time hook approval through /hooks in the TUI; Codex will not run hooks it has not been told to trust.

What it helps with

  • break token use down by task or ticket
  • compare usage across models and tools
  • inspect daily or repository-level token totals
  • enable tracking for a chosen clone
  • erase locally stored telemetry records

Example prompts for the agent

  • Enable token tracking for this clone and ask how I want to be identified.
  • Show token use for this task, grouped by model.
  • Turn tracking off and erase the saved telemetry records.

How to install aidd-telemetry

Plugin marketplace

/plugin marketplace add ai-driven-dev/framework
/plugin install aidd-telemetry@aidd-framework

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about aidd-telemetry

How do I install aidd-telemetry in Claude Code?

Add the marketplace with /plugin marketplace add ai-driven-dev/framework, then install the plugin with /plugin install aidd-telemetry@aidd-framework.

What does aidd-telemetry do?

It counts tokens in Claude Code and Codex sessions and creates reports grouped by a selected dimension, such as task or model. The records remain local.

How does aidd-telemetry assign usage to a task?

Declare one with aidd telemetry task <name> [--ticket <ref>] or answer a hook’s prompt. The plugin does not guess task names.

Source text

aidd-telemetry · MIT
← [aidd-framework](../../README.md)

# aidd-telemetry

Counts the tokens your Claude Code and Codex sessions consume, each model call once, by person, session, model, agent, tool, day, repository, task and ticket. Local only: nothing is sent anywhere.

> For: people who measure their work. Formats, rules and limits: [usage contract](../../aidd_docs/product/usage-contract.md).

## How it works

```mermaid
flowchart LR
  Claude["Claude Code and Codex sessions"] -->|"write"| Files["session files"]
  Files -->|"read, each call once"| Ledger[("local ledger")]
  You["you"] -->|"aidd telemetry task"| Tasks[("task declarations")]
  Hooks["plugin hooks"] -->|"ask when none"| You
  Ledger --> Report["aidd telemetry report"]
  Tasks -->|"attribute"| Report
```

- Only clones that ran `aidd telemetry on` are measured, from that moment on.
- A task and a ticket come only from what you declare; nothing is guessed.
- Every axis splits the same total.
- Codex is read with the rest, from `CODEX_HOME` or `~/.codex`, whenever `aidd telemetry ingest` or `report` runs, a trusted Codex session start included.

## Start

1. Install: `npm install -g @ai-driven-dev/cli`, then `aidd plugin install aidd-telemetry`. Its hooks need `node` on `PATH`.
2. In each clone to measure: `aidd telemetry on`. With no identity set, it asks how you appear: your git name, another identifier, or anonymous. Without a terminal, answer with `--yes --as <id>` or `--yes --anonymous`.
3. In Codex, trust the plugin's hooks once with `/hooks` in the TUI. Codex runs none it was not told to trust, and asks again when an update changes a hook's entry. The desktop app offers no review of its own: it runs the hooks once they are trusted from the TUI.
4. Work. While the branch has no task, Claude Code and the Codex TUI hold each prompt and ask for one: send `aidd telemetry task <name> [--ticket <ref>]` (or `--none`) as your next prompt, or run it in a terminal. Once declared, the branch is never asked again, unless a copy or rename onto it changes its keys. A declaration belongs to the branch it was made on: a branch copied or renamed with `git branch -c` or `-m` is asked again, unless the declaration was written by cli-v5.5.0 or earlier (see the usage contract's limits).
5. Read: `aidd telemetry report --axis task`.

## Where you are asked

| Surface | Asked |
| --- | --- |
| Claude Code, terminal and desktop app | yes |
| Claude Code, an IDE extension or the SDK | no |
| Codex TUI | yes, unless in full-access mode (approval `never`) |
| `codex exec`, and the Codex IDE extension and desktop app on their own threads (`originator` is not `codex-tui`) | no |
| a Codex TUI thread resumed in the desktop app or the IDE extension | yes, unless approvals are off there (inferred: a resume keeps the thread's first line). The desktop app shows a block's reason; the IDE extension was not observed |

Where nobody is asked, a call takes its task from its branch's declaration, so declare the branch with `aidd telemetry task` in a terminal. A Codex `/clear` or fork starts a new session, which is asked again on an undeclared branch; Claude Code keeps the task across both. The usage contract lists the rest.

## Commands

| Command | Does |
| --- | --- |
| `aidd telemetry on` / `off` | start or stop measuring this clone; what was measured stays. `on --as <id>` names you, `on --anonymous` names nobody |
| `aidd telemetry status` | whether this clone is measured, since when, its task, and under which name |
| `aidd telemetry task <name> [--ticket <ref>]` | declare the task; `--none` for no task |
| `aidd telemetry report [--axis <axis>] [--days <n>] [--task <name>]` | what the work consumed, split along one axis, narrowed by `--task`, `--ticket`, `--repository .` and the other filters of `--help`; `--json` for the envelope |
| `aidd telemetry identity <id>` / `--off` | be named on your own measurement, or not |
| `aidd telemetry forget` / `--yes` | show what is kept, then erase it |

## Skills

| Skill | Use it to |
| --- | --- |
| `aidd-telemetry:00-init` | opt in, stop, set or remove your identity, forget |
| `aidd-telemetry:01-usage` | ask what a period, a task or a ticket consumed |

## Privacy

- Consent is per clone and never committed: a teammate who pulls is not measured until they run `on`.
- Data stays in `~/.config/aidd/telemetry` and the clone's git config; `forget --yes` erases it.
- You are named only by choosing to be, at `on` or with `identity`. Otherwise the person axis reads `anonymous`; that choice is not stored, so the next `on` asks again.
- `AIDD_TELEMETRY=0` refuses measurement everywhere.

© AI-Driven Dev · MIT · ai-driven-dev/framework

Similar plugins

All plugins for Data and databases →

From the same set80

The whole set →
tools Defines AI assistant and IDE profiles, build contracts, and capability interfaces under src/contexts/tools/ in the framework. CX Codex +1 ★ 571repo stars framework framework — a skill for Claude Code, Cursor, and other platforms that tracks every installed file and coordinates project setup, recovery, diagnostics, and cleanup through a single manifest. CX Codex +1 ★ 571repo stars 00-async-dev 00-async-dev is a Claude Code skill that takes a task through the async-dev pipeline: repo setup, running a ready issue, and clearing review comments on a PR. CX Codex +1 ★ 571repo stars aidd-qa aidd-qa validates browser acceptance criteria against observable behavior and records short review videos. Useful right before submitting a completed task. CX Codex +1 ★ 571repo stars aidd-ui aidd-ui is a plugin for the UI/UX direction of the AI-Driven Development framework; in alpha, its only smoke-test skill checks that the plugin loads. CX Codex +1 ★ 571repo stars aidd-refine The aidd-refine plugin for Claude Code provides five meta-cognition skills to sharpen vague prompts, find blind spots in written specs, check facts, and critique code against plans. CX Codex +1 ★ 571repo stars aidd-orchestrator aidd-orchestrator — a plugin for Claude Code, Cursor and other platforms that orchestrates synchronous development pipelines, automates issue-to-PR workflows, and manages product backlogs. CX Codex +1 ★ 571repo stars aidd-pm The aidd-pm plugin for Claude Code turns a rough idea into tickets a planner can consume through ten product skills. CX Codex +1 ★ 571repo stars

Project sponsors

Companies that keep this analytics open