Metadata-Version: 2.4
Name: sidetone
Version: 0.1.7
Summary: 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.
Project-URL: Homepage, https://github.com/yijisoo/sidetone
Project-URL: Repository, https://github.com/yijisoo/sidetone
Project-URL: Issues, https://github.com/yijisoo/sidetone/issues
Author-email: Ji Soo Yi <yijisoo@gmail.com>
License: MIT
License-File: LICENSE
Keywords: attention-residue,claude-code,cognitive-load,developer-productivity,sidetone,telemetry
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.25.1
Description-Content-Type: text/markdown

# 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](https://arxiv.org/abs/2601.20245) 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](https://claude.ai/code)

```bash
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 or deleted automatically.

### 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](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 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](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](https://arxiv.org/abs/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](https://arxiv.org/abs/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](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/).

Full citations in [docs/metrics-reference.md](docs/metrics-reference.md).
