🚀 Job Search Copilot

Your private, agent-powered job-search command center

Find better roles. Build truthful applications. Prepare with evidence.

Keep your personal data on your own computer.

Job Search Copilot gives your preferred coding agent a guided career strategy, application, interview, and customizable local-tracker workflow. GitHub Copilot CLI is fully configured out of the box, while the core works with any MCP-capable agent.

✨ Example dashboard using only the repository's fictional demonstration data.

✨ More than an application spreadsheet

This workspace helps you understand what you have actually accomplished, discover roles that fit that evidence, and move each opportunity forward without losing the details that matter.

The important difference

• Evidence first: it separates direct experience, transferable evidence, genuine gaps, and unknowns instead of inventing qualifications.

• Human controlled: it can prepare applications and messages, but it stops before submitting, uploading, or contacting anyone.

• Built to evolve: each user can customize the product while broadly useful improvements flow back through reviewed pull requests.

Related MCP server: jobfinder-mcp

⚡ Go from clone to dashboard

Current setup target: Windows, Python 3.10+, Node.js LTS with npx, and an MCP-capable coding agent. GitHub Copilot CLI is the preconfigured default.

1. Clone and set up

git clone https://github.com/diegoruv20/job-search-copilot.git
cd job-search-copilot
.\scripts\setup.ps1

The guided setup creates .venv, installs dependencies, initializes a blank SQLite tracker, creates private profile templates, runs tests, and checks MCP readiness. Existing profiles and tracker data are never overwritten.

2. Choose your agent

For GitHub Copilot CLI, run copilot from the repository, trust the folder, and open /mcp. You should see:

• job-search-copilot — manages your local tracker

• playwright — researches job sites and checks the dashboard

For another MCP-capable agent, follow Use your preferred agent and copy the portable Windows or POSIX server definitions into that client's project configuration.

3. Let it learn your real experience

Skip the giant questionnaire. Start a short, guided interview:

Use the career-discovery agent. Interview me to build my job-search profile and experience inventory. Ask three to five simple questions at a time, update the files after each round, and help me identify realistic role families and positioning.

Your agent maps your systems, projects, personal ownership, metrics, preferences, constraints, and transferable experience before recommending roles.

4. Open your command center

Ask:

Start my dashboard and show my highest-priority next actions.

Or launch it directly:

.\.venv\Scripts\python.exe app.py

Then visit http://127.0.0.1:5050.

💬 Things you can ask

🔒 Your data stays yours

Personal state is stored locally and excluded from Git:

The dashboard and tracker MCP run on your computer. Playwright accesses external sites only when you request job research or browser verification.

Job Search Copilot never submits applications, uploads documents, or sends outreach without explicit approval.

🧰 Useful commands

# Check setup and profile readiness
.\.venv\Scripts\python.exe tracker_cli.py doctor

# Explore the dashboard with fictional jobs
.\.venv\Scripts\python.exe tracker_cli.py demo

# Protect or move your local data
.\.venv\Scripts\python.exe tracker_cli.py backup
.\.venv\Scripts\python.exe tracker_cli.py export

# Validate a development change
.\.venv\Scripts\python.exe scripts\release_check.py

Import and restore operations validate their source and require deliberate replacement flags. Restore creates a safety backup before changing the database.

🧠 How it works

Coding agent --> tracker MCP ----\
                                  > services.py --> SQLAlchemy --> local SQLite
Dashboard -----> Flask REST -----/
Playwright ----> job sites and dashboard

services.py owns the business rules. The browser REST API and MCP server are thin adapters over the same validated lifecycle, keeping interactive and agent workflows consistent.

🌱 Make it your own—and share the good parts

The repository is designed to become a custom solution for each user.

• A universal fix corrects behavior for everyone.

• A shared feature generalizes a useful idea through configurable, opt-in, or default-neutral behavior.

• A personal customization contains one person's data, preferences, paths, or one-off workflow and stays local or in a fork.

Agents and contributors use feature branches, the privacy-focused pull-request template, GitHub review, and the full release gate. main is protected from direct pushes, force-pushes, and unvalidated changes.

Read CONTRIBUTING.md before proposing a fix or feature.

📚 Explore the docs

• 🧭 Guided profile onboarding

• 🛠️ Safe customization

• 🤝 Contributing fixes and shared features

• 🤖 Agent setup and MCP configuration

• 🧩 Portable workflows

• 🏗️ Architecture

• 🔐 Data ownership and recovery

• 🩺 Troubleshooting

• 🛡️ Security and privacy

📄 License

Job Search Copilot is available under the MIT License. Fork it, adapt the local workflows, and make it yours—just keep personal tracker data outside Git.

🐧 macOS and Linux

GitHub Copilot CLI's committed MCP configuration currently targets Windows. Other clients and operating systems can use the portable examples in config/mcp.windows.json and config/mcp.posix.json.