red

A personal Claude orchestrator that runs entirely on your existing Claude account — no API key, no extra billing. It drives Claude through the claude -p headless CLI (your subscription login) and remembers every run in a local SQLite brain so sessions across directories aren't disconnected.

Why

Many Claude sessions in many directories are siloed, and long histories burn tokens. red fixes both by keeping the brain external: a shared store you query (recall) instead of replaying full context. Sessions become disposable; the brain is permanent.

Install

Requirements: Python 3.9+ and the claude CLI installed and logged in (Pro/Max subscription — no API key needed).

# recommended: pipx keeps it isolated and puts `red` on your PATH
pipx install git+https://github.com/wolfigs/red

# or plain pip
pip install git+https://github.com/wolfigs/red

# with voice support (local Whisper STT + VAD)
pipx install 'red-orchestrator[voice] @ git+https://github.com/wolfigs/red'

Then just run red anywhere.

Developing locally? Clone and pip install -e . (add -e '.[voice]' for the voice extras).

Usage

Interactive UI (recommended)

Just run red with no arguments for a Claude Code–style session — a banner, a live prompt, streaming output, and slash commands. Type a task and Claude works on it in the current directory; follow-up messages continue the same Claude conversation, and every run lands in the brain.

red

  ✻ RED — personal Claude orchestrator
    on your subscription · no API key
  cwd     ~/Develop/my-api
  brain   ~/.red/red.db · 6 memories

red ~/Develop/my-api
› finish the auth migration
  ⚙ Read
  ...streams as Claude works...

red ~/Develop/my-api (continuing)
› now write tests for it          ← same session, no context lost

Type / for a live command dropdown; up-arrow recalls history. Native commands: /remember /facts /forget /recall /list /show /resume /sessions /new /model /account /usage /voice /tts /jarvis /mic /extras /awareness /thread /profile /cwd /clear /help /exit. Any other /command (/init, /code-review, /verify, /compact, /security-review, …) is forwarded to Claude.

Sessions

red keeps a persistent log of every Claude conversation. /sessions opens a full-screen TUI picker where you can browse, resume, and manage past sessions across all directories.

/sessions             # open the TUI picker
/sessions pin <p>     # pin session (stays at top of list)
/sessions unpin <p>   # unpin
/sessions show <p>    # print transcript
/sessions rm <p>      # delete session

Keyboard shortcuts inside the picker:

Key	Action
↑/↓	navigate
Enter	open / resume
/	search (keyword)
p	pin / unpin
r	rename
e	expand / collapse the cwd column
d / Delete	delete
n	new session
q	cancel

Pinned sessions float to the top so your most-used workspaces are always one keystroke away.

Voice (optional)

Talk to red and let it talk back — local STT, native TTS, no API key.

pipx inject red-orchestrator faster-whisper sounddevice numpy   # if installed via pipx
# or: pip install 'red-orchestrator[voice]'  /  pip install faster-whisper sounddevice numpy
# TTS uses macOS `say` — nothing extra to install

/jarvis           # full-screen voice TUI: wake on "red, …", speaks back
/voice            # one shot: record (Enter to stop), submit as a task
/voice on / off   # persistent voice mode in the normal REPL
/tts on / off     # toggle TTS without touching the mic
/mic              # live level meter — shows peak dB and threshold advice

/jarvis opens an alt-screen TUI with:

• Header bar — SYS:RED branding, session uptime, pulsing mode badge, rotating math constants
• Mode visualizers — FFT spectrum bars while listening, a transformer layer stack while thinking, an oscilloscope while speaking, orbital drift when idle
• Transcript panel — conversation streams in below the visualizer

Just talk — every utterance you finish becomes a command (no wake word). Say "exit" / "goodbye" or press Ctrl-C to leave.

Mute toggle

Press m at any time in Jarvis to pause mic input. A status badge appears (MIC MUTED); press m again to resume. Muting does not interrupt an in-progress TTS reply.

Interruptible TTS

While Claude is speaking you can interrupt it by speaking for ~700 ms — red stops playback and starts listening immediately. Brief room noise does not trigger this threshold.

Mic calibration

On entry, red samples ~400 ms of room noise and sets a VAD trigger ~3× above it, so it adapts to any environment. If voice never registers, run /mic outside Jarvis for a live level meter — it reports peak dB and tells you what RED_MIC_THRESHOLD=<value> would catch you. If the meter sits at zero, your terminal needs Microphone access (System Settings ▸ Privacy & Security).

Env vars

Variable	Default	Purpose
RED_MIC_DEVICE	system default	mic device index (run /mic to list)
RED_MIC_THRESHOLD	auto-calibrated	RMS threshold for VAD trigger
RED_TTS_VOICE	Daniel	macOS say voice name
RED_TTS_RATE	185	words-per-minute for TTS

While voice mode is on, red appends a "you're on a call" system prompt so Claude replies in one to three natural sentences — no markdown, no preambles, no "as an AI" disclaimers. Plain conversation.

First /voice downloads the Whisper base.en model (~150 MB) into the faster-whisper cache; subsequent runs are instant. Both halves degrade gracefully — if the STT deps aren't installed, /voice prints an install hint; off macOS, /tts is a no-op.

Facts: red as Claude's memory

Anything you teach red lives in the SQLite brain and is appended to every Claude run as a "things you know about the user" block — so Claude doesn't need its per-project memory files to remember you across projects.

/remember my name is Ada
/remember I prefer Python for new services
/facts                 # list saved facts (with ids)
/forget 3              # remove a fact by id

In /jarvis, just say it: "remember that my name is Ada" — red saves the fact, replies "Got it. I'll remember.", and doesn't ship the remember-utterance to Claude.

Local context: threads, profile, extras

red has a layer of purely local context that it optionally prepends to every Claude run. Toggle it with /extras on / /extras off.

/extras               # show what's currently appended
/extras on / off      # enable or disable the extras block

/thread               # list named threads, mark active
/thread <name>        # switch to (or create) a named thread
/thread auto          # leave named thread, go back to auto-by-cwd
/thread rm <name>     # delete a thread

/profile              # show stored fields
/profile name=Sath    # set a field
/profile rm name      # remove a field
/profile clear        # wipe everything

/awareness            # print everything red knows locally (thread, profile, facts, runs)

Multiple accounts

red can swap between Claude logins without re-authenticating each time. It snapshots each account's credential into the macOS Keychain (secrets never touch disk) and swaps the live Claude Code-credentials item on demand.

# one-time, per account: log into it in Claude Code, then
/account save personal
# log into the other account in Claude Code, then
/account save work

# from then on, switch instantly (no browser):
/account work            # switch (async token refresh runs in background)
/account                 # list accounts, current marked ←
/account rename old new  # rename a saved account
/account rm work         # forget one

Notes: macOS only. This swaps the global Claude Code login (interactive Claude Code too, not just red); new claude -p runs pick it up immediately. Switching reuses each account's stored refresh token — if an account sits unused long enough for that to expire, just log in again and /account save it.

The status bar shows your real subscription usage as live percentage bars (5 h / 7 d windows), and /usage prints the full panel. This reads the same /api/oauth/usage endpoint Claude Code uses — via your local login token, at no quota cost. It's an undocumented endpoint, so red hides usage gracefully if it ever stops responding.

One-shot commands

# run a task in a directory and remember it
red run "summarize what this project does" --cwd ~/Develop/some-repo

# resume the conversation from an earlier run
red run "now list the open TODOs" --resume 1

# recall relevant past work before starting something
red recall "auth migration"

# inspect history
red list
red show 1

The brain

State lives at ~/.red/red.db (override with RED_DB) so it's machine-wide and ready to become the shared brain across sessions and, later, devices over the LAN. Recall is plain term-overlap today (zero dependencies); vector recall slots in behind the same Store.recall() call later.

Layout

File	Purpose
red/conductor.py	core orchestration primitive (run_task → claude -p)
red/store.py	SQLite brain: runs, sessions, facts, threads, profile
red/sessions.py	session management (list, load, save, delete, rename, pin)
red/picker.py	interactive TUI item picker (arrows, search, pin, delete)
red/repl.py	interactive REPL: prompt, streaming, all slash commands
red/jarvis.py	full-screen voice TUI with mode visualizers
red/voice.py	STT (faster-whisper), TTS (macOS say), VAD, mute, interrupt
red/accounts.py	macOS Keychain account switching and token refresh
red/usage.py	subscription usage bars from the oauth endpoint
red/render.py	rich terminal render layer
red/markup.py	markdown → ANSI conversion
red/prompt.py	prompt_toolkit input with history and completion
red/ui.py	ANSI colour helpers and spinner
red/cli.py	run / recall / list / show one-shot commands

Roadmap

1. Brain + conductor ✓
2. Rich REPL + voice + Jarvis TUI ✓
3. Sessions, account management, mic controls ✓
4. Auto-distillation: condense each run into a compact handoff packet
5. Task board so multiple sessions coordinate without colliding
6. Expose the brain over Tailscale for multi-device access

Platform notes

The core (brain, REPL, sessions, one-shot commands) works on macOS and Linux. TTS, /account switching (Keychain), and usage bars are macOS-only today and degrade gracefully elsewhere.

License

MIT — see LICENSE.