Developing Sidekick

Everything a contributor needs that a user does not. Start with CONTRIBUTING.md for the rules; this is the map.

#Quick start

make setup      # uv sync, the audio helper (Xcode Command Line Tools), npm install, a .env from the example
make demo       # a scripted meeting for the HUD; the mock model when there is no key
make test       # backend tests, UI typecheck, extension tests
make dev        # live: backend (mic + meeting audio) + HUD; needs a key, or local transcription (make whisper)

Press ⌘⇧Space to show the HUD and start. Open past meetings with ⌘⇧L.

#Testing without touching your own data

The live app uses ~/Sidekick and ~/Library/Application Support/MeetingHUD/hud.db. Any uv run hud … command from the repo opens that real database (and runs migrations on it) unless you point it elsewhere:

HUD_ROOT=/tmp/sidekick-scratch uv run hud import tests/fixtures/import/zoom.vtt --me "Alex Kim" --llm mock

For UI work, run a scratch backend on another port with HUD_ROOT set, and the UI against it:

HUD_BACKEND_PORT=8799 HUD_USER_DATA=/tmp/sidekick-ui HUD_DRY_KEYS=1 npx electron-vite dev

HUD_DRY_KEYS=1 registers no global hotkeys; HUD_TEST_OFFSCREEN=1 keeps windows off screen for automated screenshots over the Chrome DevTools protocol. Never test audio by playing sound through the speakers: feed WAV files to FileAudioSource or the importer instead.

#How it works

mic ──────────────┐                    ┌─ Gemini live transcription (YOU)   ← muted in the call ⇒ marked, kept
                  ├─ 16 kHz · VAD ─────┤
macOS audio tap ──┘   (speech only)    └─ Gemini live transcription (THEM) ── names from the Meet extension
                                        │
                     transcript ──► Silence Governor (when to ask) ──► Gemini Flash (cached context) ──► card
                                        │                                         │
                                SQLite + FTS5 (local)                      HUD over every app,
                                        │                                  hidden from screen share
                           on stop: debrief + proposed profile updates (you approve)

• You vs them is exact: two audio streams. Which of them comes from Meet's captions, else the model's guess (shown with ?).
• The Silence Governor never shows a card while you are talking, waits a beat after you stop, spaces cards out, and coalesces bursts. Thresholds live in config.toml [governor].
• Living profiles: after each meeting the debrief proposes one-line updates to context/people/*.md and your profile.md. Nothing is written until you accept it in the Review window.
• Cost: roughly $1–2 per meeting hour (transcription only while someone speaks; cached context for each card). The HUD footer shows the running cost.

#Hotkeys

#Commands (cd backend && uv run hud …)

Also: hud import <file> [--me NAME] reviews a meeting from a transcript or recording and make whisper builds the on-device transcription helper (docs/LOCAL-STT.md).

#Where your data lives

Everything Sidekick knows about you and the people you meet is in one folder you can read, edit and back up:

~/Sidekick/
  profile.md          who you are (from onboarding; approved observations are added over time)
  objectives.md       your standing goals
  people/<name>.md    one file per person: role, company, notes, positions, history
  meetings/YYYY/MM/   a readable record of every meeting: brief, summary, commitments, transcript
  prep/               optional notes you write before a call (YYYY-MM-DD-<slug>.md)
  projects/<slug>.md  main and side projects: goal, milestones (with evidence rules), decisions, log
  growth/             growth.md (your ledger), calibration.md (your disputes), weeks/ (week in review)
  routes/<slug>/      routes you installed, edited or exported (route.md; .source.json for library installs)

profile.md gains three optional sections the game reads: ## Tracks (your personal skills), ## Direction (where your career is going) and ## Broken patterns. Meeting records gain a ## Review section. While you follow a route, its focus tracks end in [route:<slug>] and the front matter has route:; finished routes are listed in routes_done:.

Upcoming meetings beyond the next ~36 hours need the rebuilt audio helper (backend/native/build.sh, part of make setup). Rebuilding changes the helper's signature, so macOS may ask for its permissions again.

The meetings window shows the same data under Meetings and People, including pending updates to people that you approve or discard. The search index (and the queue of pending updates) is a local database in ~/Library/Application Support/MeetingHUD/. Change the folder in config.toml → [context] dir.

#The game layer

Sidekick turns meetings into practice without adding steps.

1. Set a goal. Upcoming meetings from your calendar sit at the top of the meetings list. Open one: the AI proposes one checkable goal and up to two side quests from your weak spots and history with those people. ↩ accepts, E edits, ⌫ skips. The goal loads into the HUD brief and the card prompt when that meeting starts.
2. Meet as usual. The HUD is unchanged.
3. Read the review. After the debrief, the meeting's Review tab grades the moments that mattered, like a chess review: Brilliant, Great, Good, Inaccuracy, Mistake, Missed, Blunder. Each stands on a line found in the transcript, said by the right person (your words for your turns, theirs for a missed opening), with the same negations, and, when it could have gone better, the stronger line. Goal, side-quest, skill and pattern verdicts are checked the same way; a claim whose quote isn't found is shown plainly, marked "Quote not found in the transcript", and earns no XP, achievement or rating. It also shows accuracy, the goal verdict, a position-vs-goal graph, skills, pattern checks and one lesson. Dispute any moment; disputes become calibration the judge reads next time. Meetings under 5 minutes, social/test calls, meetings where your voice wasn't picked up, and reviews with fewer than two of your own moves are reviewed but never scored; the review says why, and its Capture line shows what the mic and the meeting audio did (hud capture <id>).
4. Grow. Growth (sidebar) holds your level and XP, six skills plus your own tracks with uncertainty bands, streaks, achievements, drills, projects (main and side, with milestones that tick from meeting evidence), AI project recommendations from your direction, and a weekly review.

Retry any missed moment as a 3-minute drill, or warm up before a meeting from its Upcoming page.

#Routes and the community library

A route is a playbook for a situation. Write your own in the app (describe the situation; Sidekick drafts it) and share it to the community library when it opens. Eleven ship with the app: Sell the room, Hold the number, Run the account, Lead the team, Run the ops, Hold the plan, Chair the decision, Hire well, Ship the roadmap, Close the deal, Keep the customer. Each one is a Markdown file with a few focus tracks, a path, achievements and drills.

• One catalogue for everyone. Every route's achievements are evaluated for you after every review, whether or not you follow that route. Growth › Achievements shows the whole catalogue and how much of it you have.
• Following is a recommendation. Onboarding (after your profile) and Growth › Routes recommend one from your role, direction and where you slip. Following adds its focus tracks to profile.md, its lens to the judge, its path to the Path, and puts its drills first. Switch or stop any time; achievements and path ticks stay.
• Make it yours. Edit any route: a copy in ~/Sidekick/routes/<slug>/route.md wins over the included one. Growth settings › Export my Growth as a route writes one from your own practice, with every name you know replaced.
• The library is a public repo of route files (library/ here is its seed). It is fetched only when you click Browse library; nothing about you is sent. Contribute with a pull request (library/CONTRIBUTING.md).

Sidekick is free. A supporter key is optional: it marks you as a supporter and moves your app to the beta update channel. How the licence resists tampering: docs/SECURITY-LICENSING.md.

Your data stays on your Mac. Everything is stored locally. Audio and text go only to the AI provider you chose, with your own key, to transcribe and advise. Nothing is sent to us: no analytics, no telemetry.

#Layout

backend/   Python 3.12 (uv): audio, STT, governor, brain, store, server, CLI, tests
hud/       Electron + TypeScript: HUD overlay, Review window, tray, hotkeys
extension/ the Sidekick for Google Meet Chrome extension
config.toml  every tunable · .env  API keys · docs/PROTOCOL.md  backend↔HUD contract · docs/DEVELOPING.md  this guide

#Further reading

This page on GitHub