# /team-insights

> Reads `~/.claude/usage-data/session-meta/*.json` (the per-session telemetry


# Team Insights

## What it does

Reads `~/.claude/usage-data/session-meta/*.json` (the per-session telemetry
written when `/insights` runs) and `~/.claude/usage-data/session-tags/*.json`
(sidecars written by bridge/executor spawns), then produces a partitioned
report at `~/.claude/usage-data/team-insights.md`.

## When to use

- "What's my team working on, where is the bridge failing?"
- "Show me insights split between my work and Slack-spawned work"
- "Per-channel breakdown of bridge activity"
- "Which colleague is hitting the most subprocess errors?"

## Data flow

1. `claude_bridge.mjs` / `clickup_executor.mjs` / `sales_call_prep.mjs` spawn
   `claude -p --session-id <uuid>` and write a sidecar to
   `~/.claude/usage-data/session-tags/<uuid>.json` with `{channel, user,
   thread_ts, source, prompt_pACME Agencyw, ...}`.
2. Anthropic's `/insights` command refreshes per-session telemetry in
   `~/.claude/usage-data/session-meta/`.
3. `shared/team_insights.mjs` joins the two on `session_id` and writes
   `team-insights.md`.

## Steps

1. **Refresh session-meta if stale.** Check the newest file mtime in
   `~/.claude/usage-data/session-meta/`. If it's older than 6 hours, tell the
   user to run `/insights` first so the report reflects recent activity. The
   skill itself cannot invoke `/insights` (it's a built-in command, not a
   skill).

2. **Run the analyzer.** From the repo root:
   ```bash
   node shared/team_insights.mjs [--since YYYY-MM-DD] [--top N]
   ```
   Default: all sessions, top 10. Pass `--since` for a date-bounded view, e.g.
   `--since 2026-04-01` for "since last month".

3. **Read the output.** `~/.claude/usage-data/team-insights.md` — present the
   key numbers inline (don't dump the whole file):
   - Volume split (bridge vs terminal session counts)
   - Bridge error rate and top error categories
   - Top channels and top users (if any sessions are tagged)
   - Anything anomalous compared to terminal (e.g. error rate 2× higher)

4. **If `--slack` was passed**, post a summary to `#your-channel` (or whichever
   channel the user names) via slack-reporter agent. Otherwise just respond
   inline.

## Important caveats to surface

- **Tagged-session count.** The first line of the report shows how many
  bridge sessions have sidecars. If it's 0 or low, tell the user: "the
  per-channel/per-user tables won't populate fully until enough Slack/ClickUp
  activity flows through the new instrumentation. Restart the bridge with
  `pull` if you haven't already."
- **Range is bounded by what `/insights` analyzed.** session-meta only
  contains sessions Anthropic's analyzer has touched. Encourage running
  `/insights` regularly (or wire it into a cron/loop).

## Args

| Arg | Effect |
|---|---|
| `--since YYYY-MM-DD` | Only include sessions starting on/after this date |
| `--top N` | Show top N tools / errors / channels / users (default 10) |
| `--slack [channel]` | Post a brief summary to Slack (default `#your-channel`) |

## Example invocations

- `/team-insights` — full historical split
- `/team-insights --since 2026-05-01` — May only
- `/team-insights --top 20 --slack` — top-20 leaderboards, post to Slack

## Source files

- Analyzer: `shared/team_insights.mjs`
- Subprocess instrumentation: `shared/run_claude_subprocess.mjs`
- Sidecar dir: `~/.claude/usage-data/session-tags/`
- Output: `~/.claude/usage-data/team-insights.md`