io.github.teabagkim/interview-mode
Structured interviewer for Claude Code — probing questions, decision tracking, evolving checkpoints.
Open source Open in the app JSON README (API)
About
Structured interviewer for Claude Code — probing questions, decision tracking, evolving checkpoints.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- teabagkim
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.5.1
- Last push
- 2026-02-06T12:27:29Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:31
- Updated
- 2026-08-29 04:01:31
- Origin id
io.github.teabagkim/interview-mode
README
# claude-interview-mode
An MCP server that turns Claude into a structured interviewer — and **gets smarter with every conversation**. Each interview feeds a shared evolution system where checkpoints are scored, ranked, and recommended based on real usage patterns across all users.
## The Evolution System
This isn't just an interview tool. It's a **collectively evolving knowledge system**.
Every time anyone runs an interview in a category (e.g., "saas-pricing"), the system learns:
```
Session 1: You explore freely → decisions become new checkpoints
Session 2: Checkpoints load → Claude prioritizes what matters
Session 5: Bayesian scores stabilize → the interview path optimizes itself
Session 20: Community patterns emerge → everyone benefits from collective experience
```
### How evolution works
**1. Checkpoint Discovery** — When a decision is made during an interview, its topic is automatically registered as a new checkpoint. After just a few sessions, the system knows what topics matter for each category.
**2. Bayesian Scoring** — Each checkpoint tracks how often it's covered and how often it leads to a decision. The score uses Bayesian smoothing to handle sparse data:
```
decision_rate = (decisions + 0.6) / (times_covered + 2)
```
The prior (0.6/2 = 30% base rate) ensures new checkpoints start with a reasonable score. After ~5 sessions, real data dominates.
**3. Composite Ranking** — Checkpoints are ranked by a composite score combining decision-leading effectiveness (70%) and usage frequency (30%):
```
composite = decision_rate × 0.7 + normalized_usage × 0.3
```
High-scoring checkpoints are the ones that consistently lead to concrete decisions — not just topics that get discussed.
**4. Recommended Path** — The system computes an optimal interview path: checkpoints with `decision_rate > 0.2`, sorted by their average position in past sessions. This tells Claude not just *what* to ask, but *when* to ask it.
**5. Community Evolution** — All metadata flows to a shared database. When you interview about "api-design", you benefit from every other user who interviewed about "api-design" before you. The checkpoints, scores, and paths evolve collectively.
### What gets shared (and what doesn't)
| Shared (metadata only) | Never shared |
|------------------------|--------------|
| Category names (e.g., "saas-pricing") | Your actual questions and answers |
| Checkpoint names (e.g., "pricing-model") | Decision details and reasoning |
| Usage counts, scores, positions | Any personal or project-specific content |
## What it does
- **Claude drives the interview** — asks questions, proposes options with reasoning, challenges assumptions
- **Tracks Q&As and decisions** — structured records with timestamps
- **Evolving checkpoints** — learns what topics matter per category, ranked by Bayesian effectiveness scores
- **Recommended paths** — suggests the optimal order to explore topics based on past interview patterns
- **Concurrent sessions** — supports multiple interviews running in parallel
- **Privacy-first** — only anonymous metadata (categories, checkpoint names, counts) goes to the shared database
## Install
```bash
npx claude-interview-mode
```
Or install globally:
```bash
npm install -g claude-interview-mode
```
## Setup with Claude Code
Add to your project's `.mcp.json`:
```json
{
"mcpServers": {
"interview-mode": {
"type": "stdio",
"command": "npx",
"args": ["-y", "claude-interview-mode"]
}
}
}
```
Restart your Claude Code session to load the MCP server. That's it — the evolution system starts working immediately via a shared community database.
### Optional: Your own Supabase
By default, checkpoint data is stored in a shared community Supabase instance. If you want your own private database:
```json
{
"mcpServers": {
"interview-mode": {
"type": "stdio",
"command": "npx",
"args": ["-y", "claude-interview-mode"],
"env": {
"SUPABASE_URL": "https://your-project.supabase.co",
"SUPABASE_ANON_KEY": "your-anon-key"
}
}
}
}
```
Then run `supabase/schema.sql` in your Supabase SQL Editor to create the tables.
## Usage
Start an interview with Claude Code:
```
> Let's do an interview about my SaaS pricing strategy
```
Claude will lead the conversation. As the interview progresses:
- Each Q&A and decision is recorded with checkpoint coverage
- At the end, metadata is uploaded to evolve the system
- Next time anyone interviews in the same category, the improved checkpoints are loaded
### Tools
| Tool | Description |
|------|-------------|
| `start_interview` | Begin a session — loads scored checkpoints and recommended path |
| `record` | Record a Q&A or decision, with checkpoint coverage tracking |
| `get_context` | Review progress, see uncovered checkpoints ranked by score |
| `end_interview` | End session, upload metadata, evolve the checkpoint system |
## Architecture
```
You ←→ Claude ←→ MCP Server (interview-mode)
│
├─ read (anon key, read-only)
│ └→ checkpoints, scores, patterns
│
└─ write (Edge Function, validated)
└→ metadata, checkpoint updates, score recalculation
│
Supabase (shared community DB)
```
**4 database tables power the evolution:**
| Table | Purpose |
|-------|---------|
| `checkpoints` | Checkpoint dictionary per category (name, usage count, decision count) |
| `checkpoint_scores` | Bayesian scores per checkpoint (decision rate, avg position, samples) |
| `interview_patterns` | Coverage sequences per session (which checkpoints, in what order) |
| `interview_metadata` | Session summaries (category, counts, duration) |
**Security:**
- Anon key is read-only (SELECT only via RLS)
- All writes go through an Edge Function with input validation and spam defense
- Empty interviews, implausible rates, and oversized payloads are rejected
## Development
```bash
git clone https://github.com/teabagkim/claude-interview-mode.git
cd claude-interview-mode
npm install
npm run build # TypeScript → dist/index.js
npm run dev # Watch mode
```
## License
MIT