@jknauber/telltale

Telltale

Telltale is a quiet memory loop for Claude Code. After each session ends, it reads the transcript, picks up the small signals that reveal how you actually work (corrections, repeated requests, things you push back on), and stages them as candidate preferences. When the pattern firms up, Claude raises it with you in your next session. You say yes or no. Approved entries land in ~/.telltale/learnings.md, which is imported into every future Claude Code session.

Want to see what's been picked up? Run telltale review any time to open a local UI showing confirmed learnings, pending candidates, recent runs, and commit history.

[!NOTE] Runs locally. Analysis goes through your own claude -p. Nothing else leaves your machine.

Quick Start

npm i -g @jknauber/telltale
telltale setup

telltale setup will:

• Create ~/.telltale/, a small git-tracked memory dir for your learnings
• Add an @import line to your global ~/.claude/CLAUDE.md so confirmed preferences load into every session
• Register SessionEnd and PreCompact hooks in ~/.claude/settings.json so future sessions feed telltale on their own
• Analyze your most recent Claude Code transcripts
• Open the UI so you can see what was picked up

To open the UI any time after that:

telltale review

From there, you mostly forget about it. The hooks do the watching. Claude prompts you when a finding is ready to confirm. The rest stays out of the way.

CLI

telltale setup [--no-scan] [--limit <n>] Initialize the memory dir, git repo, CLAUDE.md import, and hooks. Optionally analyze the <n> most recent transcripts (default 5).

telltale review Launch the telltale UI on http://localhost:5235 to browse confirmed learnings, potential candidates, recent runs, and commit history. The server runs in the foreground; press Ctrl-C to stop.

telltale promote "<instructions>" Apply a free-text promote/reject instruction. Usually invoked by in-session Claude when it surfaces a pending learning. You rarely call this by hand.

Internal subcommands (__hook, __analyze, __promote) are entry points for the Claude Code hook and child processes. You don't invoke them yourself.

Contribution

git clone https://github.com/joshuaKnauber/telltale.git
cd telltale
npm install
npm run dev:link

dev:link builds and symlinks the global telltale command to this clone. Edit, then npm run build to pick changes up. npm run dev:unlink removes the link when you're done.

Other scripts:

• npm run dev -- setup runs the CLI through tsx without building
• npm run build builds the UI (vite build → dist/ui/) then bundles the CLI to dist/cli.js with Rolldown
• npm --prefix ui run dev runs the UI dev server (Vite on 5234, API on 5235) for working on the UI
• npm run typecheck runs tsc --noEmit

Releases use Changesets:

• npx changeset to describe what changed
• npm run version to bump and update the changelog
• npm run release to build and publish

License

MIT