# How TeamAI Tracks Usage Statistics and Generates Weekly Digests

> Discover how TeamAI CLI automatically tracks usage statistics using IDE hooks and team YAML data. Generate weekly digests for team health and usage trends.

- Repository: [Tencent/teamai-cli](https://github.com/tencent/teamai-cli)
- Tags: how-to-guide
- Published: 2026-09-11

---

**TeamAI CLI automatically captures every skill invocation via IDE hooks, aggregates those events with team-reported YAML statistics, and compiles a formatted weekly digest showing team health, usage trends, and recent learnings.**

TeamAI CLI, the open-source command-line tool developed by Tencent, provides engineering teams with detailed visibility into AI-assisted coding workflows. Understanding how TeamAI tracks usage statistics and generates weekly digests allows teams to monitor skill adoption, measure productivity impacts, and identify coaching opportunities across their organization.

## The Three-Stage Analytics Pipeline

The usage tracking system operates through a sophisticated three-stage pipeline that flows from raw event capture to high-level team reporting.

### Stage 1: Capturing Raw Usage Events

Every skill invocation begins its journey in [`src/usage-tracker.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/usage-tracker.ts), where **PostToolUse** and **UserPromptSubmit** hooks feed JSON payloads into the `teamai track` command. The system normalizes tool input through `extractSkillName()`, which parses fields like `skill`, `skill_name`, `command`, or file paths to identify the canonical skill identifier.

The `isValidSkillName()` function validates the extracted name against `SKILL_NAME_REGEX` before persistence. Valid events are written via `appendUsageEvent()` to `~/.teamai/usage.jsonl` as newline-delimited JSON records containing the skill name, ISO timestamp, and tool identifier. Simultaneously, `updateKnownSkills()` maintains a durable reference set in [`known-skills.json`](https://github.com/Tencent/teamai-cli/blob/main/known-skills.json), ensuring skill history survives even if the JSONL file is truncated.

```typescript
// src/usage-tracker.ts – core tracking logic
export async function track(rawToolName: string, toolInput: string, tool?: string) {
  const toolName = normalizeToolName(rawToolName);
  if (toolName !== 'Skill') return;
  const skillName = extractSkillName(toolInput);
  if (!skillName || !isValidSkillName(skillName)) return;
  const event: UsageEvent = { 
    skill: skillName, 
    timestamp: new Date().toISOString(), 
    tool: tool ?? 'claude' 
  };
  await appendUsageEvent(event);
  await updateKnownSkills(skillName);
}

```

### Stage 2: Aggregating Local and Reported Statistics

When users run `teamai stats`, the system invokes `showStats()` in [`src/stats.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/stats.ts) to merge local telemetry with team-wide data. The process begins with `readUsageEvents()`, which robustly parses the local JSONL file while skipping malformed lines. These raw events feed into `aggregateUsage()`, which constructs a `Map<string, SkillStats>` keyed by skill name and sorted by usage frequency.

The pipeline then loads *reported* statistics via `loadReportedStats()`, reading per-user YAML files (e.g., [`alice.yaml`](https://github.com/Tencent/teamai-cli/blob/main/alice.yaml)) from the repository's `stats/` directory. These files store cumulative counts, last-used timestamps, and intervention metrics. The `mergeLocalAndReported()` function overlays unreported local counts onto the reported totals, presenting a unified view of pending and committed data.

Additional session-level metrics arrive through `readEvents()` and `aggregateSessionMetrics()`, which process dashboard events from `events.jsonl` to calculate conversation turns, token consumption, and intervention rates.

```typescript
// src/stats.ts – merging local and reported data
export async function showStats(options: ShowStatsOptions = {}): Promise<void> {
  const events = await readUsageEvents();
  const localStats = aggregateUsage(events);               // ← raw JSONL → per‑skill
  const reported = await loadReportedStats();              // ← YAML files
  const stats = mergeLocalAndReported(localStats, reported);
  // ... renders comprehensive console output
}

```

### Stage 3: Building the Weekly Team Digest

The `teamai digest` command triggers `generateDigest()` in [`src/digest.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/digest.ts), orchestrating a multi-source analysis that produces the weekly report. The function first calls `loadTeamStats()` to ingest all YAML files under the `stats/` directory, then calculates team health scores via `calculateTeamStats()` and trend comparisons through `summarizeTeamTrends()`.

The digest compiler gathers contextual data by scanning the repository structure: `getRecentSessions()` pulls markdown files from the `sessions/` folder, `getRecentLearnings()` scans `learnings/` for weekly updates, and `getRecentSkillChanges()` executes git log queries to classify skill modifications as **new** or **updated**. Finally, `summarizeInterventions()` and `summarizeConversation()` compute aggregate metrics before the system emits a formatted ASCII report directly to `stdout`.

```typescript
// src/digest.ts – digest generation orchestration
export async function generateDigest(options: GlobalOptions): Promise<void> {
  const projectConfig = await detectProjectConfig();
  const localConfig = projectConfig ?? (await requireInit()).localConfig;
  const repoPath = localConfig.repo.localPath;

  const teamStats = await loadTeamStats(reportsRoot);
  const health = calculateTeamHealth(teamStats);
  const sessions = await getRecentSessions(reportsRoot);
  const trends = summarizeTeamTrends(teamStats); // 7d vs prior 7d
  
  console.log('📈 Session trends (7d vs prior 7d):');
  if (trends) for (const line of formatTrendLines(trends)) console.log(line);
  // ... additional report sections
}

```

## Key Source Files and Functions

- **[`src/usage-tracker.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/usage-tracker.ts)**: Contains `track()`, `extractSkillName()`, and `isValidSkillName()` for hook-based event capture and validation.
- **[`src/stats.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/stats.ts)**: Implements `showStats()`, `aggregateUsage()`, and `mergeLocalAndReported()` for local and remote data fusion.
- **[`src/digest.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/digest.ts)**: Houses `generateDigest()`, `loadTeamStats()`, and `calculateTeamHealth()` for weekly report generation.
- **[`src/dashboard-collector.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/dashboard-collector.ts)**: Persists low-level session events to `events.jsonl` for token and intervention tracking.
- **[`src/session-trends.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/session-trends.ts)**: Provides 7-day window comparisons used in digest trend analysis.
- **[`src/skill-health.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/skill-health.ts)**: Calculates usage frequency and recency rankings for the "Most Used Skills" digest section.

## Practical CLI Workflows

### Manual Skill Tracking

While normally invoked automatically by IDE hooks, you can manually track usage for testing or scripting:

```bash
echo '{"tool_name":"Skill","tool_input":{"skill":"tdd"}}' | \
  teamai track --stdin --tool claude

```

### Viewing Aggregated Statistics

Display local usage combined with previously reported team data:

```bash
teamai stats --by-repo --by-time

```

### Generating the Weekly Digest

First synchronize with the team repository, then generate the report:

```bash
teamai pull   # gathers latest reported stats from remote

teamai digest # outputs formatted weekly digest to console

```

### Debugging Raw Telemetry

Inspect the local event stream for troubleshooting:

```bash
cat ~/.teamai/usage.jsonl | jq .

```

## Summary

- **Automatic Capture**: Hook-driven tracking in [`src/usage-tracker.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/usage-tracker.ts) validates and persists every skill invocation to `~/.teamai/usage.jsonl`.
- **Hybrid Aggregation**: The `showStats()` function merges local JSONL events with per-user YAML reports from the `stats/` directory.
- **Comprehensive Digesting**: `generateDigest()` synthesizes usage data, session metrics, learnings, and git history into a formatted weekly report.
- **Persistent Storage**: Skills are tracked in both ephemeral JSONL logs and durable [`known-skills.json`](https://github.com/Tencent/teamai-cli/blob/main/known-skills.json) files to prevent data loss.
- **Team Visibility**: The three-stage pipeline transitions from individual telemetry to team-wide analytics through standardized YAML reporting.

## Frequently Asked Questions

### Where does TeamAI store local usage data before it is reported?

TeamAI writes raw usage events to `~/.teamai/usage.jsonl` as newline-delimited JSON records, while maintaining a deduplicated skill list in [`known-skills.json`](https://github.com/Tencent/teamai-cli/blob/main/known-skills.json). These files reside in the user's home directory and persist data until explicitly cleared or reported to the team repository via `teamai push`.

### Can TeamAI track usage when working offline?

Yes, the CLI captures all usage events locally through the hook system regardless of network connectivity. The `usage.jsonl` file accumulates events continuously, and `teamai stats` displays aggregated data from both local storage and any previously synchronized YAML reports. Synchronization to the team repository occurs only when you explicitly run `teamai push`.

### How does the weekly digest determine "recent" sessions and learnings?

The digest generator uses configurable time windows (defaulting to 7 days) when scanning directories. The `getRecentSessions()` function examines file modification times in the `sessions/` folder, while `getRecentLearnings()` filters markdown files in `learnings/` by date. Skill changes are detected via git log queries filtered to the relevant subdirectory, ensuring the digest reflects only the current week's activity.

### What is the difference between `teamai stats` and `teamai digest`?

`teamai stats` displays immediate, personalized usage metrics combining your local `usage.jsonl` with your individual reported statistics, ideal for checking personal productivity. `teamai digest` generates a comprehensive team-wide report that aggregates data from all members' YAML files in the `stats/` directory, including trends, health scores, and collective learnings suitable for weekly team reviews.