# howitalk

Existing profiles teach the AI to write like you. This teaches it to read you:
locally, from your real transcripts, with a blind benchmark that says whether
it worked.

You know the feeling: a person sitting next to you would get what you mean on
the first try, because they know you. The AI does not. You pack six asks into
one run-on message and it answers the last one. howitalk distills how you
actually communicate, from your own chat history, into a plain text profile
you own, then hands that profile to the AI at the start of every session.

## The honest numbers, up front

Most tools launch with a winning benchmark chart. This one launches with its
real results:

1. Our own blinded N-of-1 test found no measurable effect on single-response
   quality (42 percent win rate, CI 26 to 61, n=27). Frontier models already
   parse messy one-shot prompts well. We publish that instead of hiding it.
2. A pre-registered study on 300 public WildChat users (110 prompts where
   the AI had misunderstood the person and they had to rephrase; four blinded
   conditions; the person's own later clarification as the answer key) found
   that the machine judges were the weak link: three LLM judge setups all
   caught obvious errors and all went blind to a single missing required
   piece. So the confirmatory result stays sealed. The exploratory result,
   with the uncertified judge, leaned toward the profile on every comparison
   (about 0.55 against raw prompts, 0.56 against generic rewriting, intervals
   touching 0.5). A lean, not a proof. Full protocol, amendments, and numbers
   are in the write-up.
3. The open question is session pace: how often you have to re-explain. We
   froze the author's baseline (3.8 percent of messages are corrections)
   before the tool went live, and the before and after comparison is running.
4. It took three rounds to build a self-benchmark honest enough to trust,
   and three judge configurations to learn that judging is the hard part.
   Every failure is documented, and the instrument ships in this repo so you
   can run it on your own data.

## Quickstart

```bash
git clone https://github.com/andey0Saikiran/howitalk && cd howitalk

node src/cli.js extract        # parse your Claude Code transcripts (local, free)
node src/cli.js distill        # write ~/.howitalk/profile.md (uses your claude CLI)
node src/cli.js show           # read what it learned; edit anything wrong
node src/cli.js install-hook   # inject it into every Claude Code session
```

Not on Claude Code? Fold in a ChatGPT export and use the MCP server:

```bash
node src/cli.js import-chatgpt ~/Downloads/conversations.json
node src/cli.js mcp            # profile + decode for any MCP client
```

## The two commands worth seeing

`howitalk decode "<your messy message>"` translates a quick, compressed
message into an explicit prompt: every chained ask enumerated, implied
context spelled out, real ambiguities rendered as bracketed questions. It
shows you the translation. It never rewrites you silently, because intent
inference is wrong too often for silent substitution to be safe.

`howitalk bench` is the built-in experiment: it generates paired responses to
your own past prompts, with and without your profile, and you judge them
blinded. `bench autojudge` runs the attention-free variant (a model judges
each pair twice with the order swapped; only consistent verdicts count).
Every adopter can reproduce the study on their own history.

## Everything else

```
howitalk refresh               learn from yesterday (2 model calls); auto-refresh <on|off> for mornings
howitalk pace                  correction-rate over time, against your frozen baseline
howitalk validate              check any profile against SPEC.md
howitalk export --to claude-md interop blocks for CLAUDE.md or OpenClaw USER.md
howitalk install-decode        /decode as a Claude Code slash command
```

## Design commitments

1. Local-first: transcripts, profile, and benchmark data never leave your
   machine. Model calls go through your own claude CLI, under your account.
2. The profile is a file. You can read it, edit it, version it, delete it.
   Every automatic update archives the outgoing version for diffing.
3. Reading, not writing: the profile interprets your input. It contains no
   guidance for imitating your voice. See SPEC.md for the format contract.
4. Measured, or it did not happen: see PRIOR-ART.md for the verified
   landscape, including the neighbors that do adjacent things well.

## Status

Working, used daily by its author, benchmarked honestly, pre 1.0. The name
"idiolect" appears inside profiles as the linguistic term (the speech habits
peculiar to one person), which is exactly what the file describes.

MIT.