sidetone 0.1.8

Sidetone for AI-assisted coding — feeds your own cognitive behavior back to you. A reference implementation of the offloading-score and attention-residue constructs, computed from your own Claude Code sessions.

sidetone

Sidetone is the feed of your own voice that a telephone or aviation headset plays back into your ear. Without it, people shout and mis-modulate; with it, they self-regulate automatically. This tool is sidetone for AI-assisted coding: it feeds your own cognitive behavior back to you so you self-correct.

Personal cognitive-behavior telemetry for Claude Code. A reference implementation for the offloading-score and attention-residue constructs, computed from your own AI-assisted coding sessions.

Sidetone measures whether you're asking questions or just giving orders, how long you think before delegating, how much you revise AI output vs. accepting it, and how attention residue from switching between sessions is degrading your engagement. Every metric is behaviorally grounded and cited.

The core finding that motivated this: Anthropic's 2026 study found developers who primarily direct AI assistance show measurably lower skill retention than those who inquire. The METR 2025 RCT found experienced developers were 19% slower with AI tools, with unmanaged idle time cited as a leading factor. Sidetone measures which patterns you're falling into.

---

Install

Requirements: Python 3.11+, Claude Code

pip install sidetone   # or: uv tool install sidetone
sidetone start          # instant retro from your existing Claude Code history
sidetone setup          # register hooks (needed once for future capture)

sidetone start computes your last 30 days from ~/.claude/projects/**/*.jsonl — no hook install required, real numbers immediately. sidetone setup registers the two hooks in ~/.claude/settings.json (backing up the existing file first) so future sessions capture the full metric set. Restart Claude Code after setup.

Everything after install runs through one command: sidetone in your shell, or /sidetone inside Claude Code.

Where your data lives

Everything sidetone records — the SQLite database, its update cache, and config.json (per-project planning-path overrides, managed for you by sidetone config) — lives in a single directory: ~/.sidetone. Set SIDETONE_DATA_DIR to move it. Set SIDETONE_PLANNING_PATHS (colon-separated globs) to override which folders count as "planning" globally.

If you already had mirror-cognitive installed, your existing ~/.mirror directory keeps working untouched — sidetone detects it and keeps recording there instead of starting a fresh ~/.sidetone. Nothing is moved automatically; run sidetone migrate whenever you want to move it over (refuses to overwrite an existing ~/.sidetone, no-op if there's nothing to migrate).

Uninstall

sidetone setup --uninstall surgically removes sidetone's two hook entries from settings.json (your other hooks are untouched). Behavioral history is kept by default; add --purge to delete it too.

---

What it tracks

Each metric carries a status icon in the report: 🟢 healthy · 🟡 caution · 🔴 warning · ⚪ no baseline.

The report splits into two tables — What you said (your prompts) and How it landed (what the AI did with them) — plus a Learned knowledge section.

What you said:

Metric	What it measures
Inquiry %	Share of your prompts that are genuine questions (healthy: ≥ 25%)
Direction %	Share of your prompts that are commands or directives (watch: > 70% paired with low Inquiry %)
Feedback %	Share of prompts that correct or redirect prior output — no fixed range; trend only
Other %	Share of prompts that fit none of the above categories
Prompts / Sessions / Days	Interaction volume in the week
Words/msg	Average prompt length — a proxy for how much context you give
Word variety	Lexical diversity of your prompts (--verbose only, trend only)

The four prompt shares are exclusive — each prompt counts once, classified as feedback > inquiry > direction > other. They sum to 100%.

How it landed:

Metric	What it measures
Planning %	Share of tool events that are investigation-type (reads, searches, doc edits) — trend only
Time-to-impl	Seconds from your first message to the AI's first implementation action — code edits and commands; reading and spec-writing don't count (healthy: ≥ 60s)
Revision %	Fraction of AI edits you then revised yourself — active engagement proxy (healthy: ≥ 30%)
Judgment	Stick rate — share of decisions NOT reverted later (git reverts + cross-session rework + prompt walkbacks); trend only
Parallel sessions	Time-weighted average concurrency. Sidetone learns your personal ceiling — the level where your own engagement still holds — from your data, not a fixed rule

Learned knowledge: topics new to your prompts this week versus the prior 8 weeks (needs ≥ 2 prior weeks of history before it leaves "building baseline").

v0.2 (in design): four attention-residue metrics — task-switch residue score, eager-wait rate, wait-fill classification, ready-to-resume signal. Instruments the Leroy 2009 / Mark 2015 constructs directly against your Claude Code sessions. See docs/specs/2026-07-03-attention-residue-metrics.md.

---

Sample output

                              sidetone — What you said
┏━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┓
┃ Week       ┃ Prompts ┃ Sessions ┃ Days ┃ Inquiry % ┃ Direction % ┃ Feedback % ┃ Other % ┃ Words/msg ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━┩
│ 2026-W23   │ 764     │ 51       │ 7    │ 18%       │ 38%         │ 0%         │ 44%     │ 455.4     │
│ 2026-W24   │ 378     │ 19       │ 6    │ 11%       │ 42%         │ 1%         │ 46%     │ 218.8     │
│ 2026-W25   │ 376     │ 24       │ 7    │ 16%       │ 33%         │ 0%         │ 50%     │ 113.3     │
│ 2026-W26   │ 446     │ 31       │ 5    │ 11%       │ 49%         │ 0%         │ 40%     │ 517.2     │
└────────────┴──────────┴──────────┴──────┴───────────┴─────────────┴────────────┴─────────┴───────────┘

Learned knowledge  topics new to your prompts vs the prior 8 weeks
  New this week: pack, perimeter, poc, evident, emergent
  Asked about:   axi, gpa, scroll, summation, lavish

                              sidetone — How it landed
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Week       ┃ Planning % ┃ Time-to-impl ┃ Revision % ┃ Judgment   ┃ Parallel     ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2026-W23   │ 5%         │ 17s          │ 45%        │ 88%        │ 1.5× (≤4)    │
│ 2026-W24   │ 15%        │ 16s          │ 49%        │ 92%        │ 1.1× (≤3)    │
│ 2026-W25   │ 7%         │ 25s          │ 40%        │ 97%        │ 1.2× (≤3)    │
│ 2026-W26   │ 0%         │ 45s          │ 39%        │ 100%       │ 1.6× (≤6)    │
└────────────┴────────────┴──────────────┴────────────┴────────────┴──────────────┘

Explain  🟢 healthy · 🟡 caution · 🔴 warning · ⚪ no baseline
         🔴 Time-to-impl (s): 45s (healthy ≥ 60s)
         🔴 Inquiry %: 11% (healthy ≥ 25%)
         🟢 Parallel sessions  this: 1.6× (peaked at 6)   your engagement holds up to ~2 at once (last 90d)
         → Try one paragraph of plan before the first tool call next session

SIDETONE_ASSUMPTIONS {"projects": [...]}   ← machine-readable footer the /sidetone skill parses

The Parallel sessions value is the time-weighted average number of sessions running at once (its weekly peak in parens). The personalized --explain line is sidetone's read of your own data: the concurrency ceiling where your engagement still holds, derived from your inquiry rate at each level over a trailing 90-day window — never a hardcoded rule. It stays silent ("more data needed") until there's enough signal.

The last line, SIDETONE_ASSUMPTIONS {…}, is a machine-readable JSON footer (per-project planning-glob assumptions) that the /sidetone skill parses; it is always the final line of output.

Data sources. The What you said table and Learned knowledge are computed from JSONL history in ~/.claude/projects/ — no hook needed, works from sidetone start day one. The How it landed table (Planning %, Time-to-impl, Revision %, Judgment, Parallel sessions) comes from the hook event log at your sidetone data directory's events.db (Judgment also reads local git history), so it fills in after your next session with the hooks active.

A --legacy flag re-enables the old first-call latency metric.

---

Two interfaces: sidetone (shell) and /sidetone (Claude Code)

Inside Claude Code — the /sidetone skill is the read-optimized surface: a terse daily check-in by default with structured reports behind arguments.

Slash command	What it does
/sidetone	5-line terse check-in — one flagged metric, one experiment, one "did last week's experiment move?" line
/sidetone full	Full structured report: tables, learned knowledge, metric explanations, assumption check-in
/sidetone diff	What changed since the last run (only shows metrics that moved ≥ 5% or crossed a band)
/sidetone knowledge	Just the learned-knowledge word lists — useful as a weekly digest
/sidetone probe	Hypothesis-testing scripts (AFK work, trivial delegation, fast-approved commits)
/sidetone scan	Project attention map — which repos you've been active in and their themes
/sidetone refs	Research citations behind each metric
/sidetone setup / /sidetone uninstall	Hook (re-)registration and removal

In your shell — the sidetone CLI is the install/maintenance and one-shot surface:

Shell command	What it does
sidetone start	First-run: instant retro over your existing Claude Code history (no hook install required)
sidetone insights [--days N] [--explain] [--verbose]	The core report; what the /sidetone skill invokes under the hood
sidetone scan	Project attention map
sidetone setup [--dry-run] [--uninstall] [--purge]	Register or remove the hooks in ~/.claude/settings.json (idempotent; migrates old flat-layout and pre-rename mirror entries; --purge also deletes your data dir)
sidetone migrate [--dry-run]	One-time move of legacy ~/.mirror data into ~/.sidetone (refuses to overwrite; no-op if there's nothing to migrate)
sidetone config show / set-planning-paths <root> <glob>... / confirm <root>	Per-project planning-glob overrides
sidetone update sync-now / apply	Manual self-update (usually automatic on /sidetone runs)
sidetone hook	Wire-level hook entry point — ~/.claude/settings.json invokes this; not for humans
sidetone checkin	Session check-in save command

---

Architecture

~/.claude/projects/**/*.jsonl   ← Claude Code session transcripts (existing)
~/.sidetone/events.db           ← SQLite, WAL mode (created by hook; ~/.mirror if that's
                                    where an existing pre-rename install already lives)
    tool_events   timestamp, session_id, tool_name, cwd, input_summary
    user_prompts  timestamp, session_id, cwd, prompt_text, position_in_session

src/sidetone/
    cli.py        → typer app dispatching every sidetone subcommand
    hook.py       → writes rows on every Edit/Write/Bash/UserPromptSubmit
    insights.py   → reads both sources, computes weekly metrics, renders tables
    taxonomy.py   → classifies prompts (feedback / inquiry / direction / other)
    knowledge.py  → detects new vs. prior-8-week topics (Learned knowledge)
    judgment.py   → stick rate from git reverts + rework + walkback prompts
    parallel.py   → personalized concurrency ceiling from user's own engagement
    config.py     → planning-glob config (show / set-planning-paths / confirm)
    scan.py       → reads git log across ~/devel, surface project themes
    install.py    → hook registration in ~/.claude/settings.json
    update.py     → tag-tracking self-updater
    checkin.py    → session check-in save-command
    db.py         → SQLite schema + WAL init
    paths.py      → single resolver for the data dir (~/.sidetone, with silent
                     ~/.mirror fallback for pre-rename installs; SIDETONE_DATA_DIR override)

scripts/          → hypothesis testing probes (post-hoc, read-only)

---

Status

v0.1.7 — first pip-installable release. The author uses this daily; metrics are behaviorally grounded and cited. Install path is pip install sidetone → sidetone start → sidetone setup.

v0.2 — attention-residue metrics (in design). Four new metrics for the offloading-during-agent-wait failure mode. Spec at docs/specs/2026-07-03-attention-residue-metrics.md.

If you install it and find something interesting in your own numbers, open an issue — external signal is one of the explicit gates before v0.2 ships.

---

Research grounding

Sidetone's metrics operationalize published findings:

• Delegation vs. inquiry, skill retention. Shen & Tamkin (Anthropic, 2026) — arXiv:2601.20245.
• Code acceptance as a perverse signal. Mozannar et al., AAAI 2024.
• Active vs. passive supervision. Casner & Schooler (2014) — aviation deskilling.
• Prompt evolution patterns. Tafreshipour et al. (2024) — arXiv:2412.17298.
• LLM use and recall degradation. Kosmyna et al., MIT (2025).
• Attention residue (motivates v0.2). Sophie Leroy (2009), Organizational Behavior and Human Decision Processes.
• Recovery cost of interruptions (motivates v0.2). Mark, Gudith & Klocke (2008), CHI.
• Empirical evidence of unmanaged-wait cost. METR (2025) — 19% slower with AI tools.

Full citations in docs/metrics-reference.md.