Metadata-Version: 2.4
Name: chalk-analytics
Version: 0.1.2
Summary: Team analytics for Claude Code usage
Home-page: https://github.com/chalk/chalk
Author: Chalk Team
Author-email: Chalk Team <team@chalk.io>
License: MIT
Project-URL: Homepage, https://chalk.io
Project-URL: Documentation, https://chalk.io/docs
Project-URL: Repository, https://github.com/jg-chalk-io/ccanalytics
Project-URL: Issues, https://github.com/jg-chalk-io/ccanalytics/issues
Keywords: claude,analytics,ai,development,productivity
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9
Requires-Dist: requests>=2.28
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# AI Workforce Analytics

**The problem:** Every company is pouring money into AI tools — Claude, Copilot, Cursor, ChatGPT — and nobody can answer the basic question: *is it working?*

The existing observability tools (LiteLLM, Helicone, Portkey, Langsmith) track API requests from applications. They tell you "API key xyz consumed 500K tokens." They can't tell you which *person* used those tokens, on which *project*, whether they picked the right *model*, or whether the $200/mo subscription is actually delivering value.

There's no system of record for how humans use AI. Not backend API calls — how *people* use AI as part of their daily work.

## What We're Building

A workforce-level analytics layer for AI tool usage. The unit of analysis isn't the API request — it's the **human AI session**: who was working on what, in which tool, for how long, using which model, and was it a good use of resources.

The vision is tool-agnostic: Claude Code today, Claude Desktop and Cowork tomorrow, Cursor and Copilot after that. One dashboard that shows a manager — or a power user — exactly how AI is being used across their team.

## First PoC: Chalk (Claude Code + Cowork + Desktop Chat)

The [`chalk/`](chalk/) directory contains a working proof of concept that reads session data from Claude Code, Cowork, and Desktop Chat — no proxy, no traffic interception — and produces detailed usage analytics with rich reporting.

**Real numbers from the first user (Jan–Mar 2026):**

| | |
|---|---|
| Sessions analyzed | 3,840 across 43 projects |
| Client breakdown | 3,594 Claude Code · 48 Cowork · 187 Desktop Chat |
| API-equivalent value consumed | $9,211 |
| Actual cost (Max $200/mo × 3) | $600 |
| **Leverage ratio** | **15.4x** |
| Peak month (Feb) | 30.2x leverage, 2,145 sessions |
| Subagent sessions | 542 (14.1%) with 1,882 total subagent spawns |
| MCP integrations detected | 11 (Jira, Supabase, Playwright, GitHub, ...) |

The PoC immediately surfaced actionable insights: a single project consuming 67% of all cost, weekly trend analysis showing productivity patterns, 542 sessions spawning subagents for parallel work, and 48 Cowork sessions that were previously invisible.

### Session Summarizer & Maturity Scoring

A **two-phase batch summarizer** produces per-session reports combining local analysis with AI-generated summaries:

- **Local analysis** — session health, tool leverage, workflow maturity scoring, key actions, files modified, and improvement tips — all computed without any API calls
- **AI summaries** — concise session descriptions generated via the Anthropic Messages API (Haiku by default), rate-limited and cached so subsequent runs skip unchanged sessions
- **Maturity scoring** — each session is rated Exploratory → Ad-hoc → Structured → Optimized based on 7 best-practice checks (planning, scope control, tool leverage, verification, etc.)
- **Client-type detection** — automatically classifies sessions as Claude Code, Cowork, or Desktop Chat based on tool signatures and working directory patterns
- **Subagent tracking** — Task tool spawns are counted per session, with parallel execution detection and per-project breakdowns

### Rich Batch Report

The `--report` flag generates a comprehensive analytics report with:

- **Weekly Activity Trend** — last 12 weeks with quality and high-productivity percentages, trend comparison
- **Cost Per Project** — top 10 projects by API spend with percentage breakdown
- **Session Complexity Scoring** — weighted formula across duration, tools, compactions, MCP usage, and messages; 4 tiers from Lightweight to Heavy
- **Subagent Analysis** — per-project subagent usage, distribution histogram, parallel execution detection
- **Client Type Breakdown** — Claude Code vs. Cowork vs. Desktop Chat distribution

See [`chalk/README.md`](chalk/README.md) for setup and usage, or [`concept-doc.md`](concept-doc.md) for the full product thesis and technical architecture.

## Team Layer (NEW)

The **Team Analytics Layer** enables managers to answer "How is my team using Claude Code?" while preserving developer privacy for personal projects.

### Quick Start

```bash
# Install
pip install chalk
chalk install

# Local usage (no account needed)
chalk report

# Cloud sync (optional)
chalk login
chalk sync

# Join a team
chalk team join <invite-code>
chalk share-patterns import-suggested
chalk sync
```

### Features

**For Individual Developers:**
- **Local reports** — `chalk report` works instantly, no account needed
- **Optional cloud sync** — View your data in a web dashboard at chalk.io
- **Privacy control** — Configure sharing patterns to separate work/personal projects

**For Team Leads:**
- **Team dashboard** — See aggregate stats: members, sessions, cost
- **Member breakdown** — View individual contributions (work projects only)
- **Suggested patterns** — Set default tracking patterns for your team
- **Sync compliance** — Track who's syncing and when

### Privacy Model

All data syncs to the server, but views are filtered by role:

| Viewer | What They See |
|--------|---------------|
| Self | Everything (work + personal) |
| Manager | Work projects only (`is_work=true`) |
| Other members | Nothing (aggregates only) |

Work patterns use glob syntax: `github.com/acme-corp/*` matches all repos under the org.

### Architecture

- **CLI** — Python package with auth, sync, team commands
- **Server** — FastAPI + Supabase (Postgres with Row Level Security)
- **Dashboard** — Next.js web app for visualization

See [`server/migrations/`](server/migrations/) for the database schema.

## Where This Goes

**Individual → Team → Org.** The team layer is now implemented! Team leads see per-person breakdowns, adoption insights, and cost tracking across their engineering org while respecting developer privacy.

**Claude Code → Everything.** The PoC already captures Claude Code, Cowork, and Desktop Chat sessions from separate storage locations. The same model extends to API usage and eventually third-party tools like Cursor and Copilot. One system of record for all AI activity.

---

Built by [Jeremy Greven](mailto:jeremy@6squared.vc) and Ryan Meyers.
