crackmate
Reads public GitHub repositories to attach real project code to a profile, generate project lessons, check resume claims against code, scan for secrets, and analyze code hotspots and git history.
Uses Google AI Studio/Gemini as an optional backup AI provider for generating lessons and grading answers when the primary Groq provider is rate-limited.
Connects CrackMate as an MCP server to OpenAI Codex, allowing Codex to create profiles, prepare and save lessons and grading, and coach mock interview preparation using the local CrackMate data store.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
✨ Why CrackMate
🆓 Free | 🔒 Private | 🎯 Honest |
Runs on your computer. You bring a free Groq key. No paid plan, no local AI model. | Your resume and data never leave your machine, except the text you approve for the AI. | Answers cite their sources. Guesses are labelled. Scores are coaching estimates. |
CrackMate is forpreparation and mock practice only. Never use it during a real, live interview.
Related MCP server: InterviewDojo
🧭 How it works
flowchart LR
A[Resume + GitHub repos] --> B[Your profile]
B --> C[Lessons and claim check]
C --> D[Practice and voice interview]
D --> E[Readiness and risk scores]
E --> F[Study plan]
F --> CYou prepare, practise, see your weak spots, then study exactly those. Repeat until ready.
🚀 Features
What it does | |
📄 Setup | Read your resume, review it, and fix details before anything is sent to the AI. |
📚 Learn | Project deep-dives, skill lessons, 2-minute pitch, architecture diagrams, company DSA mode. |
🛡️ Claim Checker | Finds resume claims an interviewer will test, and checks them against your real code. |
🎤 Practice | Flip cards with spaced repetition, written feedback, and a spoken mock interview. |
🕸️ Analyse | Skill graph, interview-risk scores, hotspots in your code, engineering decisions from git history. |
🗓️ Plan | A time-boxed study plan that adapts to what you get wrong. |
💬 Ask CrackMate | Questions answered only from your own material, with numbered sources. |
🔌 Claude and Codex | Run as an MCP server: your own AI assistant does the writing, no API key. |
🧰 Terminal | Study from the command line. |
Dark purple theme with a light option, works from phone to wide screens
Shared lesson cache: one generated lesson serves every profile
Automatic fallback to a second free AI provider when Groq is rate limited
Secret scan of your repos (values are masked and never stored)
Interview Brief: your pitches, top risks and key answers in one Markdown file
Usage page showing AI calls and free-tier headroom
⚡ Quick start: pick your path
flowchart TD
A{{"Do you use Claude, Codex<br>or another MCP tool?"}}
A -- "No, or I just want the website" --> B["🛠️ Way 1: Manual"]
A -- "Yes" --> C["🔌 Way 2: Connect your tool"]
B --> D["Free Groq key"] --> F
C --> E["One config line"] --> G["Chat with your assistant"] --> F
F(["🌐 CrackMate website<br>127.0.0.1:8000"])🛠️ Way 1: Manual | 🔌 Way 2: Claude, Codex or any MCP tool | |
You need | A free Groq key | A Claude or Codex subscription you already pay for |
Who writes lessons | A free AI service (Groq, optional Gemini backup) | Your own AI assistant |
API key | Yes, free | None |
Where you work | The CrackMate website | Chat with your assistant, plus the website |
Setup time | About 5 minutes | About 3 minutes |
Both ways give you the same app and the same data. Start with Way 1 and add Way 2 later, or the other way round.
🛠️ Way 1: Manual setup (free, no Claude or Codex needed)
You need: Python 3.13, Node.js 20+, git, and a free Groq key.
Step | Do this |
1 | Download |
2 | Install |
3 | Add your key (kept in a file git ignores, never uploaded) |
4 | Run |
5 | Open http://127.0.0.1:8000. Press |
✅ You are done when the sidebar shows a green dot and Groq connected.
Hit rate limits? Add a free backup AI. SeeAPI keys for Way 1.
Setup: upload a PDF or paste text. Review the extracted text. Nothing is sent until you press Extract.
Learn → Projects: paste a public GitHub URL for each project.
Generate a project lesson or a skill lesson.
Claim Checker: tick the claims you can defend out loud.
Practice: answer cards, get feedback, try the voice interview.
Plan: enter your interview time and build a study plan.
Track: watch readiness and risk change as you practise.
Update later with git pull, then ./run.sh.
🔌 Way 2: Connect Claude, Codex or any MCP tool (no API key)
CrackMate runs as an MCP server (a local "connector"). Your assistant writes the lessons and scores your answers using your own subscription, and CrackMate stores everything on your computer. Works on macOS and Linux (on Windows, use WSL).
sequenceDiagram
participant You
participant AI as Your assistant (Claude, Codex...)
participant CM as CrackMate (local)
You->>AI: "Prepare me for my interview"
AI->>CM: prepare_lesson / prepare_grading
CM-->>AI: instructions + your context
AI->>CM: save_lesson / save_grading
CM-->>You: progress on the websiteStep 1. Get the code and let it set itself up (once):
git clone https://github.com/deekshith-b48/Crackmate.git
cd Crackmate
./scripts/mcp.sh # first run installs what it needs (about a minute). Press Ctrl+C when it waits.
pwd # copy this path: you need it below as /full/path/to/CrackmateStep 2. Connect your tool. Pick yours:
Claude Code
claude mcp add crackmate -- /full/path/to/Crackmate/scripts/mcp.shOr install it as a plugin (adds a coaching skill too):
/plugin marketplace add deekshith-b48/Crackmate
/plugin install crackmate@crackmate✅ Check with /mcp: crackmate shows as connected.
Claude Desktop
Open the config file, add the mcpServers block, then quit and reopen Claude Desktop.
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"crackmate": { "command": "/full/path/to/Crackmate/scripts/mcp.sh" }
}
}If the file already has other settings, keep them and just add mcpServers.
✅ Check: CrackMate appears in the tools list of a new chat.
Codex
codex mcp add crackmate -- /full/path/to/Crackmate/scripts/mcp.shOr add this to ~/.codex/config.toml:
[mcp_servers.crackmate]
command = "/full/path/to/Crackmate/scripts/mcp.sh"Optional, in your project's AGENTS.md:
## CrackMate
Use the crackmate MCP tools for interview preparation. Preparation and mock practice only, never during a live interview.
Write lessons and scores yourself: call prepare_lesson / prepare_grading, follow `instructions` and `schema`, then call save_lesson / save_grading.
Never invent facts about the candidate's code. Ask one question at a time.Codex uses the same MCP standard, but we have not tested it in the Codex app yet.
Other MCP tools and connectors
Any app that can run a local (stdio) MCP server works. Give it this command and no arguments:
/full/path/to/Crackmate/scripts/mcp.shCrackMate is a local connector. Web-only connectors that need a public URL (for example Claude.ai custom connectors) are not supported, because your data stays on your computer.
Step 3. Start talking. For example:
Use CrackMate to prepare me for my interview. Here is my resume: …
Your assistant creates your profile, reads your public GitHub repos, tells you what to study, teaches it and quizzes you.
Step 4. See it on the website (optional but recommended). Run ./run.sh from the same folder and open http://127.0.0.1:8000. Profiles, lessons, scores and risks appear on every page, labelled "written by your AI assistant". With no Groq key the sidebar says Using your AI assistant (MCP).
crackmateshows "connection closed" or does not appear: run./scripts/mcp.shin a terminal first and wait for the install to finish. Check the path in your config is the full path with no typos. Restart the tool.Folder name has a space: that is fine in the JSON and TOML above; keep the path exactly as it is.
Website shows no profile: the assistant and the website must use the same folder, so run
./run.shfrom the folder in your MCP config.Quality: a stronger assistant model writes better lessons and scores.
Full tool list and details: docs/connect-ai-assistants.md.
🔑 API keys for Way 1: which one should I use?
CrackMate needs an AI provider to write lessons and grade answers. It uses a main key (Groq) and an optional backup key (any other provider) that takes over automatically when the main one is busy.
Our suggestion
Your situation | Use this | Cost |
Just trying it, or a short prep | Groq (main) + Google AI Studio (backup) | Free |
Preparing seriously for weeks | Same free setup, plus a paid backup key if you keep hitting limits | Pay as you go |
You need the fastest, most reliable runs | A paid plan on Groq, or a paid OpenAI-compatible provider as backup | Paid |
Best free setup: Groq as the main key and Google AI Studio as the backup. Both give keys with no payment, and we tested this pairing.
Free vs paid
🆓 Free keys | 💳 Paid keys | |
Good for | Learning, one or two projects, a few lessons a day | Heavy daily use, "generate everything" runs, no waiting |
Limits | Low per-minute and per-day token caps. You may see "wait about 1 minute". | Much higher limits, so far fewer waits |
Quality | Same models as paid on Groq ( | Can use larger models |
Risk | Limits change without notice | A bill, so set a spending cap in the provider's dashboard |
CrackMate never turns on billing for you. Whatever your key's plan allows is what you get.
Providers at a glance
Limits and signup rules change often. Check each provider's page before you rely on them.
Provider | Role | Free key? | Notes |
Main (required) | Yes, no payment | Fast. Free tier is capped per minute and per day, shared by your whole Groq organization. Also does voice transcription. | |
Google AI Studio (Gemini) | Backup | Yes, no payment | Works well as a backup. Some models get busy, so pick one that answers. |
Backup | Limited | Free models have a small daily request cap. Fine only as an emergency backup. | |
Backup | Not for us | When we tried, signup asked for a payment. Fast and generous once paid. | |
Backup | Not for us | When we tried, a key needed a pay-as-you-go plan. | |
Backup | No | Paid. Good quality, any OpenAI-compatible tool can use it. |
Only Groq and Google AI Studio have been tested with CrackMate. Others use the same standard, but are untested.
How to add your keys (3 minutes)
Create a Groq key at console.groq.com/keys. Copy it once; you cannot see it again.
Create a backup key (optional) at aistudio.google.com/apikey.
Put both in one private file,
.streamlit/secrets.toml. Git ignores this file, so it is never uploaded:# Main key (required) GROQ_API_KEY = "paste-your-groq-key" # Optional: use a second quota on the same Groq key GROQ_FALLBACK_MODEL = "openai/gpt-oss-120b" # Optional: backup provider, used automatically when Groq is busy ALT_LLM_API_KEY = "paste-your-backup-key" ALT_LLM_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/" ALT_LLM_MODEL = "gemini-3.5-flash"Restart CrackMate (
Ctrl+C, then./run.sh).Check it worked: the bottom of the sidebar shows a green dot and Groq connected.
Change the three ALT_LLM_* lines. Model names change, so pick one from the provider's model list.
Provider |
| Example |
Google AI Studio |
|
|
OpenRouter |
| a model ending in |
Cerebras |
|
|
Mistral |
|
|
OpenAI |
|
|
Prefer environment variables? Copy .env.example to .env and fill the same names.
"wait about 1 minute" or rate limit: you hit the free cap. Wait, or add a backup key.
"model unavailable": the model name is wrong or retired. Pick a current one from the provider.
"rejected access": the key is wrong or revoked. Create a new one.
Voice not working: voice always uses your Groq key.
Treat keys like passwords. Never paste them into chats, issues or commits. If one leaks, delete it in the provider's dashboard and create a new one.
🐳 Run with Docker
Prefer not to install Python and Node? Use the ready-made image from GitHub Packages:
docker run --rm -p 127.0.0.1:8000:8000 \
-e GROQ_API_KEY="paste-your-key" \
-v crackmate-data:/app/.crackmate \
ghcr.io/deekshith-b48/crackmate:latestThen open http://127.0.0.1:8000. Your data is kept in the crackmate-data volume. Add -e ALT_LLM_API_KEY=... -e ALT_LLM_BASE_URL=... -e ALT_LLM_MODEL=... for a backup provider. Keep 127.0.0.1: in the port flag so only your own computer can reach the app.
🧰 Terminal
./crackmate_cli next # the one best thing to study right now
./crackmate_cli risk # your top interview-risk topics
./crackmate_cli quiz # flashcards in the terminal
./crackmate_cli brief -o brief.mdFull command list in docs/reference.md.
🔒 Your data stays yours
Your resume, profile and progress live in
.crackmate/on your machine.Your keys live in
.streamlit/secrets.tomlonly.Both are in
.gitignore, along with.env, PDFs and Word files, so they cannot be committed by mistake.The app listens on
127.0.0.1only and never sends your key to the browser.
Never paste API keys into chats, issues or commits. If you do, delete the key and create a new one.
🗂️ Project layout
core/ engine: AI calls, lessons, spaced repetition, career intelligence, search
api/ FastAPI backend (local only, streamed generation)
web/ Next.js interface (responsive, dark and light)
crackmate/ command line and MCP server
ui/ original Streamlit interface (still works)
prompts/ prompt templates
tests/ Python tests (146)
docs/ detailed reference🧪 Development
.venv/bin/python -m unittest discover -s tests # Python tests
cd web && npm test # web testsRun the API and web app separately for live reload: .venv/bin/python -m uvicorn api.main:app --port 8000 and, in web/, npm run dev.
🤝 Contributing
Issues and pull requests are welcome. Please keep it free to run, keep private data out of the repo, and add a test with your change.
📄 License
MIT. Third-party dependencies keep their own licenses. Any bundled or imported learning content must be used under its own license and credited.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
AI interview practice and career preparation with user-controlled guidance.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Grow your skills with AI: per-skill coaching inside Claude, ChatGPT, Cursor and Codex
Review candidates and run hiring actions in InterviewFlowAI from Claude, ChatGPT, Codex and more.
Related MCP Servers
- AlicenseAqualityDmaintenanceA technical interviewer that ingests GitHub repos, teaches you your own code, and conducts mock interviews with persistent memory of your weak spots.847 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables Alexa+ to run spoken mock technical interviews by parsing a candidate's resume and target job description, generating tailored questions, and scoring each answer against Bar Raiser rubrics via Amazon Bedrock. It also produces a session report with score breakdowns, weak topics, and a concrete practice plan.MIT
- FlicenseNot gradedqualityBmaintenanceEnables Claude Code and Cowork to act as a personal coach grounded in a locally indexed library of YouTube talks, websites and PDF books, answering with exact-second, paragraph or page citations and recalling the user's goals and decisions per Project. Search, memory and the usage log run on the user's own machine, and changing Sources rebuilds the knowledge base without any fine-tuning.-
- AlicenseAqualityBmaintenanceTurns Claude or ChatGPT into a live system design interviewer that watches a hand-drawn whiteboard, reads the diagram as structured data or an image, hears spoken answers, pins questions on components, and grades the session. Everything runs locally, so users can practice mock interviews on their own machine without API keys.1363 npm1MIT