Coach Archie

A local AI architecture coach that rides along during your coding sessions.

Coach Archie watches your repo, notices when you're making architectural decisions, and asks sharp questions at the right moment. It does not lecture. It does not generate code. It helps you think.

What it does

• Watches your repo for file changes and analyzes diffs
• Detects decision moments: new modules, new abstractions, duplication, large functions/classes, boundary shifts, complexity increases, coupling
• Retrieves relevant architecture principles from a curated knowledge base of 28 structured principles
• Asks one Socratic question when something matters
• Lets you go deeper with why, expand, show principle, show alternative
• Learns your taste over time — which principles you engage with, which you skip
• Reflects at session end with a summary of what it noticed

Setup

cd coach-archie
npm install
cp .env.example .env
# Add your ANTHROPIC_API_KEY to .env
npm run build
npm link   # makes 'coach-archie' available globally

Or run directly in development:

npm run dev -- start /path/to/your/repo

First user path (CLI + hosted dashboard)

1. Install — npm install and npm run build in this repo, then npm link (or run via npx tsx src/index.ts).
2. API key — Set ANTHROPIC_API_KEY. Coach Archie loads a .env file from the current working directory (process.cwd()), not only from the coach-archie repo. If you run coach-archie start inside another project, put the key in that project’s .env or export it in your shell.
3. Hosted app — Deploy the web/ app (Vercel) or run it locally (cd web && npm run dev), with Postgres and npm run db:push.
4. Pair once — coach-archie live pair --base-url https://your-app.vercel.app (or http://localhost:3000). Sign in, approve in the browser; tokens are saved to ~/.coach-archie-live.json.
5. Coach — coach-archie start /path/to/repo. Live relay turns on automatically after pairing (no COACH_ARCHIE_LIVE_SYNC_ENABLED=true needed). Check Dashboard on the same base URL.
6. Diagnostics — coach-archie doctor summarizes API key, pairing file, and relay status.
7. Disable relay — COACH_ARCHIE_LIVE_SYNC_ENABLED=false coach-archie start ... (local-only coaching).

Optional browser UI + local project picker (no Vercel): from the repo root, npx tsx app.ts, then open http://localhost:3000 (use another PORT if Next.js already uses 3000).

Usage

# Watch a repo (defaults to current directory)
coach-archie start /path/to/your/repo

# Check API key, pairing, and live relay readiness
coach-archie doctor

# Show nudge history
coach-archie history
coach-archie history -n 50

# End session — press Ctrl+C while watching
# Coach Archie will generate a reflection before exiting

Interactive commands during a session

When a nudge appears, type:

| Command | Effect | |---|---| | why | 3-4 sentences on why this was flagged | | expand | Deep tradeoff exploration for this specific change | | show principle | Print the raw architecture principle | | show alternative | Sketch an alternative design approach | | skip | Dismiss — suppresses this type for 90 seconds | | history | Show nudges from this session | | ? | Show help |

Example session

  Coach Archie — Architecture thinking partner
  Type "why", "expand", "show principle", "show alternative", "skip"

  Watching: /path/to/your-project
  Low noise mode — only nudging on meaningful architectural moments

>

[archie]  Is this abstraction pulling its weight with the use cases that exist right now? (src/services/paymentService.ts)
> why

When you introduced PaymentProcessor as an abstract class with a registration
system, there was only one concrete implementation. Abstractions built on a
single use case often encode the wrong interface — you're paying the cost of
indirection without the benefit of variation. The pattern to watch for here
is speculative generality: building generics before the second case arrives
to reveal what the interface actually needs to be.

> expand

The tradeoff here is real. On one hand, the PaymentProcessor abstraction does
give you a clean seam for testing — you can swap in a mock. That's genuinely
useful. On the other hand, the abstract class locks in a particular interface
contract before you've seen a second payment type. When Stripe and Braintree
both exist, the interface will reveal itself naturally. Right now you're
carrying the cost of maintenance and cognitive overhead for a pattern that
serves one case.

The YAGNI bet is that the cost of a future refactor — extracting the right
abstraction from two real implementations — is lower than the ongoing cost
of maintaining the wrong one. This is usually true.

What specific change in the next sprint would require this abstraction to
have existed beforehand?

>

Configuration

Create a .coacharchierc file in your project root (or any ancestor directory):

{
  "minConfidence": 0.6,
  "cooldownSeconds": 90,
  "nudgesPerWindow": 3,
  "windowMinutes": 5,
  "largeFunctionLines": 40,
  "ignoredGlobs": ["**/*.generated.ts", "**/migrations/**"]
}

Optional extra key liveSyncEnabled: set to false to turn off cloud relay for this working directory even if you have run live pair. Omit the field to follow the default (relay on when paired).

Or set in your environment:

ANTHROPIC_API_KEY=...
COACH_ARCHIE_MODEL=claude-sonnet-4-6
COACH_ARCHIE_LIVE_SYNC_ENABLED=false   # optional: force relay off (even after `live pair`)
COACH_ARCHIE_LIVE_SYNC_ENDPOINT=
COACH_ARCHIE_LIVE_SYNC_TOKEN=

After coach-archie live pair (or live connect), relay is on by default; you only need the variables above for manual endpoints/tokens or to disable relay with COACH_ARCHIE_LIVE_SYNC_ENABLED=false.

Live sync to hosted web app (hybrid mode)

To keep the same "watch while I code locally" experience for web users, run Archie locally and relay events to your backend:

COACH_ARCHIE_LIVE_SYNC_ENABLED=true
COACH_ARCHIE_LIVE_SYNC_ENDPOINT=https://your-app.vercel.app/api/live-events
COACH_ARCHIE_LIVE_SYNC_TOKEN=your_agent_token

When enabled, Archie sends best-effort JSON events (session_started, file_changed, nudge_generated, session_reflection, session_ended) to your endpoint while still coaching locally in the terminal/Electron UI.

You can also save these once with CLI onboarding:

coach-archie live connect --endpoint https://your-app.vercel.app/api/live-events --token your_agent_token
coach-archie live status
coach-archie start /path/to/repo

Or use browser pairing (recommended):

coach-archie live pair --base-url https://your-app.vercel.app
coach-archie live status
coach-archie start /path/to/repo

Pairing expects your web backend to expose:

• POST /api/live/pair/start → { deviceCode, verificationUrl, intervalSeconds?, expiresInSeconds? }
• POST /api/live/pair/poll with { deviceCode } → pending/approved payload with { endpoint, accessToken, refreshToken?, expiresAt? }
• POST /api/live/pair/refresh with { refreshToken } → refreshed { accessToken, refreshToken?, expiresAt?, endpoint? }

For local end-to-end testing, server.mjs now includes scaffold endpoints for this contract plus:

• GET /live/pair/approve?deviceCode=... to approve a pending pairing in browser
• GET /api/live-events to inspect last received relay events

The production Vercel backend lives in web/ — see Deploying to Vercel below.

Deploying to Vercel

The web/ directory is a Next.js 15 app that provides the production backend for live sync. It replaces server.mjs (the local demo scaffold) with:

• GitHub OAuth via NextAuth v5
• Neon / Vercel Postgres (Drizzle ORM) — pairing sessions, tokens, event log
• Metadata-only event storage — diffs and nudge text are never persisted

1. Create a GitHub OAuth app

Go to Settings → Developer settings → OAuth Apps → New OAuth App:

| Field | Value | |---|---| | Homepage URL | https://your-app.vercel.app | | Callback URL | https://your-app.vercel.app/api/auth/callback/github |

Copy Client ID and Client Secret.

2. Deploy to Vercel

cd web
npx vercel deploy

Or connect the repo in the Vercel dashboard and set Root Directory to web.

3. Set environment variables in Vercel

| Variable | Value | |---|---| | AUTH_SECRET | openssl rand -base64 32 | | AUTH_GITHUB_ID | GitHub OAuth Client ID | | AUTH_GITHUB_SECRET | GitHub OAuth Client Secret | | NEXT_PUBLIC_BASE_URL | https://your-app.vercel.app | | DEMO_PROFESSOR_EMAIL | Demo login email for grading (e.g. [email protected]) | | DEMO_PROFESSOR_PASSWORD | Demo login password for grading | | DEMO_PROFESSOR_NAME | Display name shown when using demo login | | NEXT_PUBLIC_BEAT_MAKER_URL | Optional external URL for the Beat-maker project button | | DATABASE_URL | Auto-injected when you provision Vercel Postgres |

4. Provision Vercel Postgres

In the Vercel dashboard → Storage → Create → Postgres. DATABASE_URL is injected automatically.

5. Push the database schema

cd web
DATABASE_URL=<your-neon-url> npm run db:push

6. Pair the CLI

npx coach-archie@latest live pair --base-url https://your-app.vercel.app

Sign in with GitHub when the browser opens, approve the pairing, and credentials are saved automatically to ~/.coach-archie-live.json. Then:

coach-archie start /path/to/repo

Live relay is enabled automatically once pairing (or live connect) has saved credentials. Set COACH_ARCHIE_LIVE_SYNC_ENABLED=false if you want local-only mode. Events appear in real time on your dashboard at https://your-app.vercel.app/dashboard.

Demo login for grading

If you want your professor to grade without GitHub OAuth, configure:

• DEMO_PROFESSOR_EMAIL
• DEMO_PROFESSOR_PASSWORD
• (optional) DEMO_PROFESSOR_NAME

They can then sign in on /auth/signin using those demo credentials and access the dashboard in-browser with no local install.

Local development of the web app

cd web
cp .env.local.example .env.local
# Fill in AUTH_SECRET, AUTH_GITHUB_ID, AUTH_GITHUB_SECRET, DATABASE_URL
npm install
npm run dev   # starts on :3000

Test the pairing flow against the local Next.js server:

npx tsx src/index.ts live pair --base-url http://localhost:3000

Architecture

src/
├── cloud/          # Optional relay client for live sync to hosted backends
├── watcher/        # File watching (chokidar) + git diff extraction
├── analyzer/       # Heuristics that detect architectural signals in diffs
├── detector/       # Gating logic: confidence threshold, cooldown, rate limit
├── knowledge/      # 28 curated architecture principles (structured JSON)
├── retrieval/      # Signal-to-principle mapping via affinity + keyword scoring
├── coach/          # Claude API integration + prompt variants
├── memory/         # SQLite (node:sqlite) — sessions, nudges, taste profile
└── cli/            # Commander CLI + readline REPL + display

Signals detected

| Signal | What it means | |---|---| | new_module | New file created — is this boundary needed? | | new_abstraction | New class/interface/type introduced | | duplication | Similar block already exists in the file | | large_function | Function grew past threshold (default: 40 lines) | | large_class | Class has too many methods or lines | | boundary_shift | Import crosses layer boundary (domain ← infrastructure) | | complexity_increase | Deep nesting added (depth > 4) | | structural_change | Substantial rewrite of an existing file | | coupling_signal | Direct new ConcreteType() instantiation | | dependency_added | New import added |

Knowledge base

28 principles covering:

• YAGNI, DRY, SRP
• Coupling/cohesion, stable dependencies, separation of concerns
• Encapsulation of volatility, domain clarity, premature abstraction
• Local reasoning, accidental complexity, boundary design
• Dependency direction, Tell Don't Ask, Law of Demeter
• Hexagonal architecture, OCP, ISP, composition over inheritance
• CQS, feature envy, shotgun surgery, god object, leaky abstraction
• Connascence of meaning, strangler fig, context mapping, bounded context

Taste tracking

Coach Archie remembers which principles you engage with and which you skip. Over sessions, it weights its retrieval toward principles you find valuable and suppresses ones you repeatedly dismiss.

Data

All data is stored locally in data/coach-archie.db (SQLite, never leaves your machine):

• Session records
• Nudge history with your responses
• Taste profile (tag weights, engaged/skipped principles)

Requirements

• Node.js v22.5+ (uses built-in node:sqlite)
• An Anthropic API key
• A git repository to watch (diffs are extracted via git diff)