# Concepts

## The pipeline

cinsights processes coding agent sessions in three stages. Each stage is independently runnable.

**Index** (`cinsights index`) discovers sessions from the configured source, parses tool call timelines, computes quality metrics, and scores each session against the developer's baseline. Zero LLM cost. This is the stage you can run as often as you want.

**Analyze** (`cinsights analyze`) sends scored sessions to the LLM for per-session insight extraction - friction points, wins, recommendations, patterns, and skill proposals. Costs tokens, but only runs on sessions above the score threshold.

**Digest** (`cinsights digest project <name>` or `cinsights digest user <id>`) aggregates analyzed sessions into a cross-session report scoped to a project or developer. Runs three concurrent LLM calls to produce a narrative, actionable recommendations, and forward-looking patterns.

`cinsights refresh` chains index and analyze in one shot. Run digest separately per project or user.

Index is free. Analyze and digest cost tokens. They're separate so you can run index as often as you want and only spend tokens when it matters.

## Quality metrics

Computed during indexing from tool call sequences alone. No LLM needed.

| Metric | What it measures | Good | Degraded |
|--------|-----------------|------|----------|
| `read_edit_ratio` | Read calls / Edit calls - how much the agent researches before modifying | ~6.6 | ~2.0 |
| `edits_without_read_pct` | % of Edit calls where the file was not Read first | ~6% | ~34% |
| `research_mutation_ratio` | All research calls (Read+Grep+Glob) / all mutations (Edit+Write) | ~8.7 | ~2.8 |
| `write_vs_edit_pct` | Full-file Write calls as % of all mutations | ~5% | ~11% |
| `error_rate` | % of tool calls that failed | low | high |
| `repeated_edits_count` | Consecutive edits to the same file (thrashing indicator) | 0-1 | 5+ |
| `tokens_per_useful_edit` | Total tokens / successful Edit+Write calls | low | high |
| `context_pressure_score` | Fraction of turns where prompt tokens grew by >50% (0-1) | <0.1 | >0.5 |
| `subagent_spawn_rate` | Agent/Task tool calls as % of total | varies | - |
| `turn_count` | Number of conversation turns | - | - |
| `tool_calls_per_turn` | Average tool calls per turn | - | - |

Quality metrics are the smoke detectors. They tell you something is off before you spend tokens figuring out what.

## Scoring and budget modes

Not every session is worth analyzing with an LLM. cinsights scores sessions on "interestingness" - how much they deviate from the developer's baseline.

**Scoring signals** (weighted 0-1 each):
- Error rate deviation from baseline (15%)
- New project / cold start (15%)
- Read:Edit ratio drop (10%)
- Blind edit rate deviation (10%)
- Repeated edits / thrashing (10%)
- New agent type (10%)
- Turn count deviation (7%)
- Duration deviation (7%)
- Context pressure (6%)
- Research:mutation ratio drop (5%)
- Session abandonment (5%)

Routine sessions cluster at 0.2-0.4. Interesting ones land at 0.6+.

**Budget modes** control what gets analyzed:

| Mode | Threshold | Use case |
|------|-----------|----------|
| `frugal` | top ~10% | Minimize spend, surface only clear outliers |
| `balanced` | score >= 0.4 (default) | Good coverage without waste |
| `thorough` | top ~50% | Deeper analysis, higher token cost |
| `all` | everything | Full coverage, use for small teams or audits |

**Cold start**: the first N sessions per (user, project) pair are always analyzed regardless of score (default: 10). This builds the baseline before scoring kicks in.

Most coding sessions are routine. Budget modes exist because your LLM bill should scale with how much you learn, not how much you code.

## Per-session insights

What the LLM extracts from each analyzed session:

| Category | What it captures |
|----------|-----------------|
| **Summary** | 2-3 sentences on what happened - interaction efficiency, tool usage, overall flow |
| **Friction** | Where the developer-agent interaction broke down - wrong approaches, permission blocks, wasted reads, token waste |
| **Wins** | Efficient moments - multi-step tasks in one shot, good tool selection, effective sub-agent usage |
| **Recommendations** | How to configure the coding agent better - CLAUDE.md rules, skills, hooks, permissions |
| **Patterns** | Usage patterns - tool preferences, interaction style, session types |
| **Skill proposals** | Repeated workflows that could become custom slash commands |

Each insight has a severity: `info`, `warning`, or `critical`.

![Session detail with insights](../.github/images/session-insights.png)

![Recommendations with difficulty tags](../.github/images/project-insights-recommendations.png)

## Cross-session digest

The digest aggregates analyzed sessions over a time window (default: 7 days) for a specific project or developer. It runs three concurrent LLM calls:

**Narrative** - at-a-glance summary (what's working, what's hindering, quick wins, ambitious ideas), detected work areas, and a developer persona narrative.

**Actions** - friction analysis with categories and severity, copy-paste-ready CLAUDE.md suggestions with explanations, and feature recommendations for tools the developer might not know about.

**Forward-looking** - impressive wins worth repeating, workflow patterns codified as starter prompts, and ambitious automation ideas.

The digest is the product. Individual session insights are evidence. If you only look at one thing, look at the digest.

![Developer digest - at a glance](../.github/images/developer-insights-summary.png)

![Work areas and developer persona](../.github/images/project-insights-workareas.png)

## Developer mood quotes

![Things you've said when you were...](../.github/images/mood-quotes.png)

During analysis, cinsights extracts notable things developers say to their coding agents, categorized by mood:

| Mood | What it captures |
|------|-----------------|
| **Frustrated** | Anger, annoyance, disappointment, impatience |
| **Curious** | Exploring, questioning, "what if..." |
| **Amused** | Humor, sarcasm, playful jabs at the agent |
| **Relieved** | Celebration, satisfaction, "it works!" |
| **Assertive** | Firm boundaries, taking control, "Bad bot!" |

These are exact verbatim quotes from developer input — not summaries or paraphrases. Up to one quote per mood per session. The web UI groups them by mood across sessions under "Things you've said when you were..."

The five mood categories are derived from Plutchik's emotion wheel, filtered to emotions that commonly surface in developer-agent interactions.

## Behavioral patterns

![Behavioral patterns dot timeline](../.github/images/behavioral-patterns.png)

Computed from tool call sequences during analysis. These surface recurring interaction habits:

- **Tool preferences** — which tools the developer reaches for (heavy Bash user? prefers Read over Grep?)
- **Session structure** — focused single-task sessions vs. multi-task exploratory sessions
- **Interaction style** — terse directives vs. detailed specs vs. exploratory prompting
- **Friction patterns** — repeated edits to the same file, high error rates, permission prompt interruptions

Behavioral patterns appear in the Activity section of developer profiles and require analyzed sessions to populate.

## Quality comparison

![Quality metrics with team comparison](../.github/images/quality-metrics-trends.png)

The web UI computes team averages for each quality metric and shows how individual developers compare. When a developer's metric deviates more than 15% from the team average, a directional indicator shows whether they're above or below. This helps identify developers who might benefit from specific CLAUDE.md rules or workflow changes.

## Scope stats

Quality metrics and activity data are pre-computed per user and per project after every `analyze` run. This means the web UI shows fresh metrics immediately — even before a digest is generated. Digests are still valuable for narrative insights, but you don't need one to see basic activity charts and behavioral patterns.

Stats are stored in the `scope_stats` table and refreshed automatically. You can also compute them without running the LLM using `cinsights digest <scope> --stats-only`.

---

**[← Previous: Getting Started](./getting-started.md)**

<div align="right">

**[Next: How It Works →](./how-it-works.md)**

</div>
