# Analyze Usage

> Graphic monthly/weekly digest of Claude Code session patterns — biome aquarium (whale/shark/dolphin/fish/shrimp/plankton), 8-class archetype, rhythm, stack palette, DORA radar (CFR + lead time + pushes), friction (compacts/pivots/subagents). Backend installs on first run via curl.

- **Type:** Skill
- **Install:** `agentstack add skill-meteora-pro-devboy-tools-analyze-usage`
- **Verified:** Pending review
- **Seller:** [meteora-pro](https://agentstack.voostack.com/s/meteora-pro)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [meteora-pro](https://github.com/meteora-pro)
- **Source:** https://github.com/meteora-pro/devboy-tools/tree/main/crates/devboy-skills/skills/03-self-feedback/analyze-usage
- **Website:** https://meteora-pro.github.io/devboy-tools/

## Install

```sh
agentstack add skill-meteora-pro-devboy-tools-analyze-usage
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# analyze-usage

This is a **thin baseline skill** that delegates the heavy lifting to a
sibling Python backend (`bin/analyze-usage` and `lib/`/`scripts/`)
auto-installed on first use into `~/.claude/skills/analyze-usage/`. The
backend reads `~/.claude/projects/*.jsonl` directly — there is nothing
to push, post or upload.

The output is a **graphic period digest** with metaphors:

- 🌊 **Aquarium** of biomes: 🐋 Whale (R≥500) · 🦈 Shark (100-499) ·
  🐬 Dolphin (30-99) · 🐟 Fish (10-29) · 🦐 Shrimp (3-9) · 🦠 Plankton (0-2)
- 🎭 **8 archetypes** (Variant B 45/25 thresholds): 🏗 Constructor /
  ⚙️ Operator / 🔬 Researcher / 🛠 Builder / 📝 Scholar / 🔍 Inspector /
  🌐 Polymath / 💬 Discusser
- 🎵 **Rhythm**: 🎼 Mono · 📊 Phased · 🎲 Mixed · 🌪 Chaos
- 🎨 **Stack palette** (LOC by frontend/backend/infra/docs/config)
- 🚀 **DORA radar**: pushes, PR/MR, feat, fix (review-fix vs prod-fix
  split), True CFR with Elite/High/Medium/Low classification
- ⚡ **Friction**: compacts · pivots · subagent spawns

## When to use

- *"Сделай отчёт за неделю / месяц / квартал"*
- *"Какие у меня DORA метрики?"*, *"что с CFR?"*
- *"Покажи биомы за апрель"*, *"когда сессия стала китом?"*
- *"Drill into session 2c052d83"* — глубокий single-session breakdown
- Quarterly review of how Claude Code time was actually spent

## Procedure

### 1. Ensure backend is installed

The Python backend is **not** embedded in the `devboy` binary (it would
bloat the release). Check whether it exists; if not, fetch it.

```bash
SKILL_DIR="$HOME/.claude/skills/analyze-usage"
if [ ! -x "$SKILL_DIR/bin/analyze-usage" ]; then
    echo "Installing analyze-usage backend (~1MB sparse checkout)..."
    curl -sSL https://raw.githubusercontent.com/meteora-pro/devboy-tools/main/.claude/skills/analyze-usage/scripts/install.sh | bash
fi
```

The installer does a `git sparse-checkout` of `.claude/skills/analyze-usage/`
only — no full repo clone, no Cargo build. Requires `uv` for running
Python (https://docs.astral.sh/uv/).

The installer is idempotent: re-running it just refreshes to the latest
`main` (or pin via `REF=v0.22.0 curl ... | bash`).

### 2. Begin a trace for this report

```bash
result=$(devboy trace begin --skill analyze-usage)
SESSION_DIR=$(echo "$result" | jq -r .session_dir)
SESSION_ID=$(echo "$result" | jq -r .session_id)
```

This skill is traceable — `retro` will see when it ran and how
long it took.

### 3. Resolve the period

Parse the user's intent into ISO dates and a granularity:

| User says | `--from` | `--to` | `--period` |
|-----------|----------|--------|------------|
| "за прошлую неделю" / "last week" | Monday of previous ISO week | Sunday of previous ISO week | `weekly` |
| "за этот месяц" / "this month" | 1st of current month | today | `monthly` |
| "за апрель" / "April" | first day of April | last day of April | `monthly` |
| "за квартал" / "Q1" / "за 3 месяца" | start month | end month | `both` |
| explicit dates given | use them verbatim | | as requested |

If the user did not specify a format, default to `text` for terminal
output. Prefer `html` with `--open` when the user explicitly asks for a
"graphic" / "красивый" / "в браузере" report.

### 4. Run the period report

```bash
"$SKILL_DIR/bin/analyze-usage" period \
    --from "$FROM" --to "$TO" --period "$PERIOD" \
    --format "$FORMAT" \
    ${OUT:+--out "$OUT"} \
    ${OUT_DIR:+--out-dir "$OUT_DIR"} \
    ${OPEN:+--open}
```

Available `--format` values:

| Format     | Output destination                            |
|------------|----------------------------------------------|
| `text`     | stdout (default)                             |
| `markdown` | use with `--out FILE.md` for Slack/GitHub    |
| `html`     | use with `--out FILE.html` (or auto `/tmp/`) |
| `all`      | writes `.txt`+`.md`+`.html` into `--out-dir` |

For long quarters wallclock-heavy reports, prefer `--out-dir /tmp/`
and `--format all` so the user has all three artefacts at once.

### 5. Drill-down on a specific session (if requested)

If the user names a session ID prefix (e.g. *"посмотри сессию 2c052d83"*):

```bash
"$SKILL_DIR/bin/analyze-usage" session 2c052d83
```

Output: biome / archetype / rhythm / first 5 prompts / bash subcategory mix
+ subagent count.

### 6. (Optional) Generate parquet bundles for further analysis

Only if the user wants raw data for ad-hoc queries:

```bash
"$SKILL_DIR/bin/analyze-usage" pipeline --since 2026-04-01
```

This runs all 10 extractors sequentially (~4-5 minutes on a full
corpus) and writes:

- `outputs/raw/*.parquet`  — original UUIDs/paths/branches (owner-only)
- `outputs/anon/*.parquet` — anonymized version, shareable
- `outputs/llm/*.parquet`  — Tier 2 LLM-augmented (filled by the agent
  in step 7)

After regenerating, **always audit anon before sharing**:

```bash
"$SKILL_DIR/bin/analyze-usage" audit
# exits 1 if any raw UUID / abs path / bash command / branch / mcp slug
# leaks into anon parquet
```

### 7. Tier 2: LLM-augmented narratives (if the user wants them)

Tier 1 (extractors) is pure stat — deterministic, anonymizable. Tier 2
narratives require the agent itself to read the raw jsonl and write
back a summary. The skill never calls an external LLM.

To enqueue Whales/Sharks/Dolphins for narrative:

```bash
"$SKILL_DIR/bin/analyze-usage" llm-queue
# writes outputs/llm/_queue.jsonl with one row per session
```

Then iterate the queue, read each session's jsonl, summarize (≤200
words: name, phases, what was created, pivots, finale), and append rows
to `outputs/llm/session_names.parquet`. The full schema is documented
in `extract_llm_session_names.py`.

### 8. End the trace

```bash
devboy trace end \
    --session-dir "$SESSION_DIR" --session-id "$SESSION_ID" \
    --skill analyze-usage \
    --outcome "$OUTCOME" \
    --summary ":  sessions,  +LOC, CFR "
```

## Success criteria

- The user receives a digest in the requested format (default: terminal text).
- Numbers reconcile: `+LOC = sum across sessions`, `True CFR = prod_fix /
  feat`, biome counts add up to total session count.
- HTML output renders standalone — no external CSS/JS, opens offline.
- `audit` exits 0 after every `pipeline` regeneration before any sharing.
- Tier 2 narratives, if requested, are appended (not overwriting) to
  `outputs/llm/session_names.parquet`.

## Guardrails

- **Never share `outputs/raw/`** — it contains real UUIDs, file paths,
  branch names, prompt tokens. Only `outputs/anon/` is shareable, and
  only after `audit` passes.
- **Tier 1 must remain deterministic.** If you find yourself wanting an
  LLM call inside an `extract_*.py`, that's a Tier 2 feature — put it in
  `extract_llm_*.py` instead.
- **Don't write to `~/.claude/projects/`** — that's the source data,
  read-only.
- The backend is `uv run`-based. If `uv` is missing, the installer warns
  but still copies the files; the user must install `uv` separately
  (https://docs.astral.sh/uv/).

## Non-goals

- This skill does **not** post the report anywhere. Pipe output into
  `notify` (category 5) if you need delivery.
- It does **not** call external LLM APIs. Tier 2 enrichment runs
  agent-side.
- It does **not** modify session jsonls. Source data stays untouched.
- It does **not** analyse long-term trends — that's `retro`.

## Concepts reference

A full glossary (biome thresholds, archetype rules, rhythm classifier,
stack heuristics, bash subcategory regexes, DORA proxy formulas,
scaling-law findings) lives next to the backend at
`~/.claude/skills/analyze-usage/GLOSSARY.md` after install.

The architecture (extractor list, library API, anonymization contract,
extension guide for new metrics) is in
`~/.claude/skills/analyze-usage/SKILL.md`.

## Examples

```bash
# Quick weekly digest:
analyze-usage period --from 2026-04-23 --to 2026-04-30 --period weekly

# Quarter, all formats, open HTML in browser:
analyze-usage period --from 2026-02-01 --to 2026-04-30 --period both \
    --format all --out-dir /tmp/q1_2026 --open

# Drill into one Whale:
analyze-usage session 2c052d83

# Generate parquet bundles + audit:
analyze-usage pipeline --since 2026-04-01
analyze-usage audit
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [meteora-pro](https://github.com/meteora-pro)
- **Source:** [meteora-pro/devboy-tools](https://github.com/meteora-pro/devboy-tools)
- **License:** Apache-2.0
- **Homepage:** https://meteora-pro.github.io/devboy-tools/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-meteora-pro-devboy-tools-analyze-usage
- Seller: https://agentstack.voostack.com/s/meteora-pro
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.