Skip to content

README.md

Latest commit

Β 

History

History
448 lines (321 loc) Β· 15.3 KB

README.md

File metadata and controls

448 lines (321 loc) Β· 15.3 KB
Raw

�️ STARCoach

AI-Powered STAR Interview Practice Bot for Discord

Features β€’ Quick Start β€’ Commands β€’ Customization β€’ Troubleshooting

What is STARCoach?

STARCoach is a free, open-source Discord bot that conducts live voice-based behavioral interview practice sessions using the STAR method (Situation, Task, Action, Result). It listens to you speak in a Discord voice channel, responds with realistic follow-up questions in real time using text-to-speech, and β€” when the session ends β€” generates a detailed coaching report grading each of your answers on STAR structure, clarity, and depth.

Think of it as a personal interview coach that's available 24/7 in your Discord server.

✨ Features

  • 🎀 Live Voice Interviews β€” Join a voice channel, and STARCoach asks you behavioral questions out loud and listens to your answers in real time. No typing required.
  • 🧠 AI-Powered Conversation β€” Powered by Claude (via OpenRouter), the bot asks contextual follow-up questions, probes for details, and keeps the conversation natural.
  • πŸ“ Real-Time Transcription β€” Your speech is transcribed on-the-fly using Deepgram Nova-2, so you can review exactly what was said.
  • πŸ—£οΈ Text-to-Speech Responses β€” The bot speaks its questions and feedback aloud using natural-sounding TTS (Microsoft Edge TTS).
  • πŸ“Š Detailed Coaching Reports β€” After each session, STARCoach analyzes your entire interview and posts a rich embed report covering:
    • Per-answer STAR breakdown (Situation / Task / Action / Result)
    • Strengths and areas for improvement
    • An overall Readiness Score (0–100)
    • Specific, actionable coaching tips
  • 🎯 Customizable Focus Areas β€” Edit a simple config file to target specific roles, focus areas, and coaching styles.
  • πŸ“‚ Session History β€” All sessions are saved to a local SQLite database. Review past transcripts, re-analyze old sessions, and track improvement over time.
  • πŸ”’ Self-Hosted & Private β€” Runs entirely on your own machine. Your data never leaves your control.

Quick Start

Total setup time: ~15 minutes if you already have Python installed.

Prerequisites

You need the following installed on your machine before you begin:

Requirement Version How to Check Install Link
Python 3.10+ python --version python.org/downloads
FFmpeg Any recent ffmpeg -version See below
Git Any recent git --version git-scm.com

Installing FFmpeg

FFmpeg is required for voice audio processing. The bot will not work without it.

πŸͺŸ Windows

Option A β€” winget (recommended):

winget install FFmpeg

Option B β€” Manual install:

  1. Download from ffmpeg.org/download.html (click "Windows builds" β†’ gyan.dev or BtbN)
  2. Extract the ZIP to a folder like C:\ffmpeg
  3. Add C:\ffmpeg\bin to your system PATH:
    • Search "Environment Variables" in Start Menu
    • Under "System variables", find Path, click Edit
    • Add C:\ffmpeg\bin
    • Click OK, close all windows
  4. Open a new terminal and verify: ffmpeg -version
🍎 macOS 
brew install ffmpeg

If you don't have Homebrew: brew.sh

🐧 Linux (Debian/Ubuntu) 
sudo apt update && sudo apt install ffmpeg

Step 1 β€” Clone the Repository

git clone https://github.com/chchchadzilla/STARCoach.git
cd STARCoach

Step 2 β€” Create a Virtual Environment

python -m venv venv

Activate it:

  • Windows (cmd): venv\Scripts\activate
  • Windows (PowerShell): .\venv\Scripts\Activate.ps1
  • macOS / Linux: source venv/bin/activate

You should see (venv) at the beginning of your terminal prompt.

Step 3 β€” Install Dependencies

pip install -r requirements.txt

Step 4 β€” Create a Discord Bot

  1. Go to the Discord Developer Portal
  2. Click "New Application" β†’ Name it whatever you want (e.g., "STARCoach") β†’ Create
  3. Go to the Bot tab on the left sidebar
  4. Click "Reset Token" β†’ Copy the token (you'll need this in Step 5)
  5. Scroll down and enable these Privileged Gateway Intents:
    • βœ… Server Members Intent
    • βœ… Message Content Intent
  6. Go to the OAuth2 tab on the left sidebar
  7. Under OAuth2 URL Generator:
    • Scopes: check bot
    • Bot Permissions: check these:
      • Send Messages
      • Embed Links
      • Connect (voice)
      • Speak (voice)
      • Use Voice Activity
  8. Copy the generated URL at the bottom and open it in your browser to invite the bot to your server

Step 5 β€” Configure Environment Variables

cp .env.example .env

Windows (cmd): copy .env.example .env

Open .env in any text editor and fill in your values:

# REQUIRED β€” paste your Discord bot token from Step 4
DISCORD_TOKEN=your_discord_bot_token_here

# REQUIRED β€” right-click a text channel in Discord β†’ "Copy Channel ID"
# (You need Developer Mode on: User Settings β†’ Advanced β†’ Developer Mode)
REPORT_CHANNEL_ID=1234567890123456789

# REQUIRED β€” sign up at https://console.deepgram.com (free tier available)
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# REQUIRED β€” sign up at https://openrouter.ai/keys (pay-as-you-go)
OPENROUTER_API_KEY=your_openrouter_api_key_here

The rest of the .env values have sensible defaults. See .env.example for all options.

Getting Your API Keys

Deepgram API Key (for speech-to-text)
  1. Go to console.deepgram.com
  2. Sign up for a free account (includes $200 in free credits)
  3. Go to API Keys in the left sidebar
  4. Click Create a New API Key
  5. Copy the key and paste it into your .env as DEEPGRAM_API_KEY
OpenRouter API Key (for AI conversation & analysis)
  1. Go to openrouter.ai
  2. Sign up / log in
  3. Go to openrouter.ai/keys
  4. Click Create Key
  5. Copy the key and paste it into your .env as OPENROUTER_API_KEY
  6. Add credits at openrouter.ai/credits (pay-as-you-go, typically pennies per session)

Step 6 β€” Create the Practice Role in Discord

  1. In your Discord server, go to Server Settings β†’ Roles
  2. Create a new role called Practice (or whatever you set PRACTICE_ROLE_NAME to in .env)
  3. Assign this role to anyone who wants to practice

How it works: When a user with the Practice role joins a voice channel where the bot is present, STARCoach automatically starts a practice session. When they leave the channel, the session ends and a coaching report is generated.

Step 7 β€” Run the Bot

python bot.py

You should see output like:

2025-01-01 12:00:00 | INFO     | starcoach | Loaded cog: src.cogs.voice
2025-01-01 12:00:00 | INFO     | starcoach | Loaded cog: src.cogs.admin
2025-01-01 12:00:00 | INFO     | starcoach | Logged in as STARCoach#1234 (ID: ...)
2025-01-01 12:00:00 | INFO     | starcoach | Connected to 1 guild(s)

πŸŽ‰ You're done! Assign yourself the Practice role, join a voice channel, and start practicing.

How a Session Works

  1. Join a voice channel β€” The bot must already be in the channel (or it joins when you do, if configured). Make sure you have the Practice role.
  2. The bot greets you β€” It introduces itself and asks the first behavioral question out loud.
  3. Speak your answer β€” Talk naturally. The bot transcribes your speech in real time.
  4. Follow-up questions β€” The bot asks clarifying questions, probes for STAR details, and keeps the conversation going.
  5. Leave the channel β€” When you disconnect, the session ends automatically.
  6. Coaching report β€” Within seconds, a detailed coaching report embed is posted to your configured report channel.

Commands

All commands use the ! prefix by default (configurable via COMMAND_PREFIX in .env).

Practice Commands

Command Description
!endpractice Manually end your current practice session (instead of leaving the voice channel)
!sessions List all active practice sessions in the server
!testvoice Test TTS playback in your current voice channel

History & Review Commands

Command Description
!history [@user] Show recent practice sessions for yourself or another user
!session <id> View the full coaching report for a specific session
!transcript <id> View the raw transcript for a specific session
!reanalyze <id> Re-run the AI analysis on a past session (useful if you change models)

Admin Commands

Command Description
!setrole <role_name> Change which role triggers practice sessions
!setthreshold <0-100> Set the readiness score threshold
!status Show bot configuration and status

Customization

Interview Focus & Coaching Style

Edit interview-config.md in the project root to customize:

  • Practitioner Name β€” Your name (used in the coaching conversation)
  • Target Role β€” The job you're preparing for
  • Focus Areas β€” Specific topics the interviewer should focus on
  • Known Weaknesses β€” Areas where you need extra practice
  • Special Instructions β€” Adjust the coaching style (e.g., "be more aggressive with follow-ups")

The bot reads this file at the start of every session, so changes take effect immediately β€” no restart needed.

AI Models

You can change the AI models in your .env:

# Fast model for real-time conversation (needs to be quick)
OPENROUTER_MODEL=anthropic/claude-haiku-4.5:nitro

# Deeper model for post-session analysis (can be slower, higher quality)
ANALYSIS_MODEL=anthropic/claude-sonnet-4.5

Browse available models at openrouter.ai/models. The :nitro suffix on the interview model routes to faster infrastructure β€” recommended for real-time voice conversations.

Other Settings

.env Variable Default Description
PRACTICE_ROLE_NAME Practice Discord role name that triggers sessions
READINESS_THRESHOLD 70 Score (0–100) to be considered "Interview Ready"
COMMAND_PREFIX ! Bot command prefix
DATABASE_PATH data/starcoach.db SQLite database location

Project Structure

STARCoach/
β”œβ”€β”€ bot.py                      # Main entry point
β”œβ”€β”€ interview-config.md         # Customize interview focus & style
β”œβ”€β”€ requirements.txt            # Python dependencies
β”œβ”€β”€ .env.example                # Environment variable template
β”œβ”€β”€ LICENSE                     # MIT License
β”‚
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ cogs/
β”‚   β”‚   β”œβ”€β”€ voice.py            # Voice channel handling, live interview loop
β”‚   β”‚   └── admin.py            # Admin & history commands
β”‚   β”‚
β”‚   β”œβ”€β”€ services/
β”‚   β”‚   β”œβ”€β”€ analysis.py         # Post-session STAR analysis (LLM)
β”‚   β”‚   β”œβ”€β”€ database.py         # SQLite database operations
β”‚   β”‚   β”œβ”€β”€ transcription.py    # Deepgram speech-to-text
β”‚   β”‚   └── tts.py              # Text-to-speech (edge-tts)
β”‚   β”‚
β”‚   └── utils/
β”‚       └── embeds.py           # Discord embed formatting for reports
β”‚
└── data/
    └── starcoach.db            # SQLite database (auto-created)

Troubleshooting

Bot starts but doesn't respond to voice

  • βœ… Make sure you have the Practice role (or whatever PRACTICE_ROLE_NAME is set to)
  • βœ… Make sure the bot has Connect and Speak permissions in the voice channel
  • βœ… Make sure ffmpeg is installed and on your PATH: ffmpeg -version
  • βœ… Check the terminal for error messages

"DISCORD_TOKEN not found"

You forgot to create the .env file. Run:

cp .env.example .env

Then fill in your values.

OpenRouter 401 error / "User not found"

Your OpenRouter API key is invalid or expired.

  1. Go to openrouter.ai/keys
  2. Generate a new key
  3. Update OPENROUTER_API_KEY in your .env
  4. Restart the bot

No coaching report appears after a session

  • βœ… Make sure REPORT_CHANNEL_ID in .env is set to the correct channel ID
  • βœ… Make sure the bot has Send Messages and Embed Links permissions in that channel
  • βœ… The session needs at least a few exchanges before a report is generated

"Chunk too big" error in logs

This is handled automatically in the current version. If you see it, make sure you're on the latest code (git pull).

Bot can hear me but I can't hear the bot

  • βœ… Make sure FFmpeg is installed: ffmpeg -version
  • βœ… Try !testvoice to test TTS playback
  • βœ… Check your Discord voice settings (output device, volume)

Database errors

The database is auto-created on first run. If it gets corrupted:

del data\starcoach.db

(or rm data/starcoach.db on Mac/Linux), then restart the bot. Session history will be lost.

Tech Stack

Component Technology
Bot Framework Py-cord 2.7.0
Speech-to-Text Deepgram Nova-2
AI (Conversation) Claude Haiku 4.5 via OpenRouter
AI (Analysis) Claude Sonnet 4.5 via OpenRouter
Text-to-Speech edge-tts (Microsoft Edge TTS)
Database SQLite via aiosqlite
Audio Processing FFmpeg

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License β€” see the LICENSE file for details.

Built by Chad Keith

Usage

1 β€” Run a practice session

  1. Make sure you have the Practice role in your Discord server.
  2. Join any voice channel β€” STARCoach greets you and asks a behavioral question out loud.
  3. Speak your answer naturally; the bot follows up with probing STAR-method questions.
  4. Leave the voice channel when finished. A coaching report is posted to your report channel within seconds.

To end a session early without leaving the voice channel:

!endpractice

2 β€” Review your session history

!history          # list your recent sessions
!session <id>     # view the full coaching report for a session
!transcript <id>  # read the raw transcript for a session

3 β€” Re-run the AI analysis on a past session

Useful after changing the AI model in your .env:

!reanalyze <id>

Support

If this project helps you, consider: