�️ 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:

Download from ffmpeg.org/download.html (click "Windows builds" → gyan.dev or BtbN)
Extract the ZIP to a folder like C:\ffmpeg
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
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

Go to the Discord Developer Portal
Click "New Application" → Name it whatever you want (e.g., "STARCoach") → Create
Go to the Bot tab on the left sidebar
Click "Reset Token" → Copy the token (you'll need this in Step 5)
Scroll down and enable these Privileged Gateway Intents:
- ✅ Server Members Intent
- ✅ Message Content Intent
Go to the OAuth2 tab on the left sidebar
Under OAuth2 URL Generator:
- Scopes: check bot
- Bot Permissions: check these:
  - Send Messages
  - Embed Links
  - Connect (voice)
  - Speak (voice)
  - Use Voice Activity
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)

Go to console.deepgram.com
Sign up for a free account (includes $200 in free credits)
Go to API Keys in the left sidebar
Click Create a New API Key
Copy the key and paste it into your .env as DEEPGRAM_API_KEY

OpenRouter API Key (for AI conversation & analysis)

Go to openrouter.ai
Sign up / log in
Go to openrouter.ai/keys
Click Create Key
Copy the key and paste it into your .env as OPENROUTER_API_KEY
Add credits at openrouter.ai/credits (pay-as-you-go, typically pennies per session)

Step 6 — Create the Practice Role in Discord

In your Discord server, go to Server Settings → Roles
Create a new role called Practice (or whatever you set PRACTICE_ROLE_NAME to in .env)
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

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.
The bot greets you — It introduces itself and asks the first behavioral question out loud.
Speak your answer — Talk naturally. The bot transcribes your speech in real time.
Follow-up questions — The bot asks clarifying questions, probes for STAR details, and keeps the conversation going.
Leave the channel — When you disconnect, the session ends automatically.
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.

Go to openrouter.ai/keys
Generate a new key
Update OPENROUTER_API_KEY in your .env
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

Make sure you have the Practice role in your Discord server.
Join any voice channel — STARCoach greets you and asks a behavioral question out loud.
Speak your answer naturally; the bot follows up with probing STAR-method questions.
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:

⭐ starring the repo
sharing it with someone who needs it
supporting ongoing work: https://buymeacoffee.com/chadpkeith

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github		.github
src		src
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
bot.py		bot.py
interview-config.md		interview-config.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

�️ STARCoach

What is STARCoach?

✨ Features

Quick Start

Prerequisites

Installing FFmpeg

Step 1 — Clone the Repository

Step 2 — Create a Virtual Environment

Step 3 — Install Dependencies

Step 4 — Create a Discord Bot

Step 5 — Configure Environment Variables

Getting Your API Keys

Step 6 — Create the Practice Role in Discord

Step 7 — Run the Bot

How a Session Works

Commands

Practice Commands

History & Review Commands

Admin Commands

Customization

Interview Focus & Coaching Style

AI Models

Other Settings

Project Structure

Troubleshooting

Bot starts but doesn't respond to voice

"DISCORD_TOKEN not found"

OpenRouter 401 error / "User not found"

No coaching report appears after a session

"Chunk too big" error in logs

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

Database errors

Tech Stack

Contributing

License

Usage

1 — Run a practice session

2 — Review your session history

3 — Re-run the AI analysis on a past session

Support

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages