Skip to main content
Glama

✨ 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.

IMPORTANT

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 --> C

You 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

NOTE

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

Downloadgit clone https://github.com/deekshith-b48/Crackmate.gitcd Crackmate

2

Installpython3.13 -m venv .venv.venv/bin/python -m pip install -r requirements.txt -r requirements-api.txt

3

Add your key (kept in a file git ignores, never uploaded)mkdir -p .streamlitprintf 'GROQ_API_KEY = "paste-your-key"\n' > .streamlit/secrets.toml

4

Run./run.sh (the first run builds the interface, a few minutes)

5

Open http://127.0.0.1:8000. Press Ctrl+C in the terminal to stop.

✅ You are done when the sidebar shows a green dot and Groq connected.

TIP

Hit rate limits? Add a free backup AI. SeeAPI keys for Way 1.

  1. Setup: upload a PDF or paste text. Review the extracted text. Nothing is sent until you press Extract.

  2. Learn → Projects: paste a public GitHub URL for each project.

  3. Generate a project lesson or a skill lesson.

  4. Claim Checker: tick the claims you can defend out loud.

  5. Practice: answer cards, get feedback, try the voice interview.

  6. Plan: enter your interview time and build a study plan.

  7. 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 website

Step 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/Crackmate

Step 2. Connect your tool. Pick yours:

Claude Code

claude mcp add crackmate -- /full/path/to/Crackmate/scripts/mcp.sh

Or 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.sh

Or 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.
NOTE

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.sh
NOTE

CrackMate 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).

  • crackmate shows "connection closed" or does not appear: run ./scripts/mcp.sh in 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.sh from 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

TIP

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 (gpt-oss)

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

Groq

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.

OpenRouter

Backup

Limited

Free models have a small daily request cap. Fine only as an emergency backup.

Cerebras

Backup

Not for us

When we tried, signup asked for a payment. Fast and generous once paid.

Mistral

Backup

Not for us

When we tried, a key needed a pay-as-you-go plan.

OpenAI

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)

  1. Create a Groq key at console.groq.com/keys. Copy it once; you cannot see it again.

  2. Create a backup key (optional) at aistudio.google.com/apikey.

  3. 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"
  4. Restart CrackMate (Ctrl+C, then ./run.sh).

  5. 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

ALT_LLM_BASE_URL

Example ALT_LLM_MODEL

Google AI Studio

https://generativelanguage.googleapis.com/v1beta/openai/

gemini-3.5-flash

OpenRouter

https://openrouter.ai/api/v1

a model ending in :free

Cerebras

https://api.cerebras.ai/v1

gpt-oss-120b

Mistral

https://api.mistral.ai/v1

mistral-small-latest

OpenAI

https://api.openai.com/v1

gpt-4o-mini

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.

WARNING

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:latest

Then 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.md

Full 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.toml only.

  • 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.1 only and never sends your key to the browser.

WARNING

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 tests

Run 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Turns 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.
      13
      63 npm
      1
      MIT