Rudder

Rudder records the prompts you give your AI coding assistants and turns a day's worth of them into a readable summary of what you actually worked on.

Rudder is a tool for understanding what you actually do when you code with AI. AI coding tools make it easy to generate, edit, review, and ship code quickly, but they can also make your work hard to see. You can spend hours prompting, reading, accepting, rejecting, rewriting, testing, and steering the tool without actually feeling like you truly produced the eventual code output.

The goal of rudder is to give the person doing the work a truthful record of their own AI-assisted coding process so they can understand their decisions, improve their workflow, and build better software.

It installs lightweight hooks into Claude Code and Codex that quietly log every prompt you send to a local SQLite database.

Quickstart

npm install -g @vivekyy/rudder    # puts `rudder` on your PATH
rudder init                       # create the database and install the hooks

Then just use Claude Code and/or Codex as you normally would — every prompt is logged automatically. Whenever you want to see what you've been doing:

rudder start      # live dashboard: correction rate + category breakdown, updated as you work
rudder stats      # the same numbers, printed to the terminal
rudder digest     # write a readable Markdown summary of the day to ./digest.md

Requires Node.js ≥ 23.6 and at least one of claude / codex on your PATH. See Install and Commands for the full details.

Why

Rudder starts from a simple problem: When I code with AI, I feel like I haven't done anything except watch my agent code for me.

The final diff tells only part of the story. It does not show how I got there, where I changed direction, what I trusted, what I rewrote, or what I tested.

Rudder exists to make that path visible.

The important question is not "Did AI write this?" It is "What did the human do?"

How it works

┌──────────────┐   UserPromptSubmit hook   ┌─────────────────┐
│  Claude Code  │ ────────────────────────▶ │                 │
└──────────────┘                            │  ~/.rudder/      │
┌──────────────┐   notify program          │   rudder.db      │
│    Codex      │ ────────────────────────▶ │  (SQLite)       │
└──────────────┘                            └────────┬────────┘
                                                      │ rudder digest
                                                      ▼
                                            reads the day's prompts,
                                            pipes them to `claude -p`
                                            (or `codex exec`) and writes
                                                  ./digest.md

• Local only. Everything lives in ~/.rudder/rudder.db. Nothing is uploaded; the digest is generated by the LLM CLI you already use. Your data stays yours.
• Non-intrusive. The hooks are fail-safe — if rudder ever errors, it logs to stderr and exits 0 so it never blocks or breaks Claude Code or Codex.

Requirements

• Node.js ≥ 23.6
• Claude Code (claude) and/or Codex (codex) on your PATH. You only need one of them; rudder records whichever is installed and uses whichever is available to generate the digest.

Install

npm install -g @vivekyy/rudder    # puts `rudder` on your PATH
rudder init                       # creates the database and installs the hooks

rudder init:

1. Creates ~/.rudder/rudder.db.
2. Adds a UserPromptSubmit hook to ~/.claude/settings.json.
3. Adds a top-level notify program to ~/.codex/config.toml.

Existing config files are backed up to *.rudder-bak before being modified, and the command is idempotent — running it twice won't duplicate the hooks.

From source

git clone https://github.com/Vivekyy/Rudder.git rudder && cd rudder
npm install        # install dependencies
npm run build      # compile to dist/ (npm link's `rudder` bin points here)
npm link           # puts `rudder` on your PATH
rudder init

If you don't want to npm link, you can run rudder directly with node /path/to/rudder/bin/rudder.ts <command>. rudder init always wires the hooks to an absolute path, so they keep working regardless of your PATH.

Upgrade

npm update -g @vivekyy/rudder    # or: npm install -g @vivekyy/rudder@latest

The hooks point at the global install's absolute path, which is stable across upgrades, so there's nothing to re-wire. Re-run rudder init only after an upgrade whose notes say the hook format changed (it's idempotent and safe to re-run). If you installed from source, upgrade with git pull && npm install instead — the npm link symlink picks up the new code with no rebuild.

Commands

| Command | Description | | --- | --- | | rudder init | Create the database and install the Claude Code + Codex hooks. | | rudder start [options] | Open the live dashboard app; updates as you work. | | rudder stats [options] | Print today's correction rate and category breakdown. | | rudder digest [options] | Summarize a day's prompts into a Markdown digest. | | rudder tag [options] | Classify untagged prompts and print the day's stats. | | rudder help | Show usage. | | rudder hook claude | (internal) Record a Claude Code prompt — invoked by the hook. | | rudder hook codex | (internal) Record a Codex turn — invoked by notify. |

rudder start

Starts a small local server (on 127.0.0.1, port 41789 — override with RUDDER_PORT). While it runs, each new prompt is classified out-of-band by your claude/codex CLI and the dashboard updates live with your correction rate and category breakdown for today.

The dashboard is a standalone app (a PWA):

• The first time, rudder start opens a small installer page — click Install app (or, in Safari, File → Add to Dock) to add rudder to your dock with its own icon and no browser chrome. The installed window auto-sizes to its content.
• After it's installed, rudder start launches the app directly (no browser tab). The app loads from the running daemon, so keep rudder start running.

If you'd rather not install anything, open http://127.0.0.1:41789/ in a browser.

rudder stats

Prints the same correction rate and category breakdown as the dashboard, on the command line:

$ rudder stats
rudder — 2026-06-18
26 prompts · 3 git chores skipped · 23 counted
You said no to your AI 12% of the time  (3 of 25 yes/no reactions)

  Architecting   30%  █████░░░░░░░░░░░  7
  Tuning         17%  ███░░░░░░░░░░░░░  4
  Bugfixing       9%  █░░░░░░░░░░░░░░░  2
  Housekeeping   43%  ███████░░░░░░░░░  10

It classifies any not-yet-tagged prompts first (pass --no-tag for an instant read of only what's already classified, and --date YYYY-MM-DD for another day).

| Option | Default | Description | | --- | --- | --- | | --agent claude\|codex | claude, else codex | Which LLM classifies prompts. | | --no-tag | off | Show only already-classified prompts; skip the tagging pass. | | --date YYYY-MM-DD | today (local) | Day to report. |

It's safe to leave running and safe to run twice (a second rudder start just re-opens the window). Nothing is required for the digest to work — if the daemon isn't running, prompts are simply classified the next time you run rudder start, rudder tag, or rudder digest.

rudder digest

| Option | Default | Description | | --- | --- | --- | | --date YYYY-MM-DD | today (local time) | Which day to summarize. | | --agent claude\|codex | claude, else codex | Which LLM CLI generates the digest. | | --out PATH | ./digest.md | Where to write the digest. |

Examples:

rudder digest                          # today → ./digest.md
rudder digest --date 2026-06-16        # a specific day
rudder digest --agent codex --out ~/digests/today.md

The digest produces a Summary (with your "said no to your AI" rate); Architecting, Tuning, Bugfixing, and Housekeeping breakdowns (each with the share of prompts and the top things you worked on); Highlights; and Open threads. The percentages are computed from the per-prompt tags rudder stores (see below), so they match the rudder start dashboard exactly — the LLM only writes the prose around them.

Data & privacy

All prompts are stored in plaintext in ~/.rudder/rudder.db (schema: timestamp, local day, source, session id, working directory, project, prompt text, model, and the raw hook payload). A companion prompt_tags table holds each prompt's computed category and reaction (the data behind the dashboard and digest stats). Classification uses the same local claude/codex CLI as the digest — nothing is sent anywhere else. To wipe everything, delete ~/.rudder/. To stop recording, remove the hook from ~/.claude/settings.json and the notify line from ~/.codex/config.toml.

Set RUDDER_HOME to override the storage location (used by the test suite). The hooks honor RUDDER_DISABLE — rudder sets it on the agent it spawns for rudder digest, so the digest's own prompt is never recorded.

Uninstall

1. Remove the UserPromptSubmit entry from ~/.claude/settings.json.
2. Remove the notify = [...] line from ~/.codex/config.toml.
3. rm -rf ~/.rudder.

Development

npm install
npm run typecheck    # tsc --noEmit
npm test             # node --test
npm run build        # compile to dist/ (the only code published to npm)

Source lives in src/ and the CLI entry point is bin/rudder.ts. In development these .ts files run directly via Node's native type stripping; npm run build compiles them to dist/, which is what gets published and what the installed rudder bin runs.