JobRouteAI

A portable multi-agent workflow for finding suitable jobs, tailoring application material, applying with controlled automation, and keeping application state without a database.

JobRouteAI is built to run inside the coding agent you already use. It ships native agent definitions for OpenAI Codex, Claude Code, and GitHub Copilot and keeps candidate/job state in readable YAML, Markdown, and CSV files.

It is intentionally not a monolithic auto-apply bot. Each specialist has a narrow responsibility, evidence rules are strict, and required personal or legal facts are never guessed.

JobRouteAI is an early open-source project. Job sites, MCP servers, ATS pages, and AI-client capabilities change over time. Review provider terms and your generated application data before relying on automation.

What it does

JobRouteAI can:

• ingest a master resume from PDF, DOCX, TXT, or Markdown;
• turn the resume into persistent, agent-readable candidate knowledge so agents do not keep rereading the source document;
• ask a small, bounded set of high-value profile questions when important information is missing;
• search enabled job sources and public web/ATS pages according to free-form preferences;
• score and shortlist jobs before spending effort on tailoring;
• create a country- and JD-aware resume, cover letter, and application-answer draft without inventing experience;
• use an optional browser MCP for form filling;
• pause only when a required answer cannot safely be inferred;
• remember confirmed answers such as work authorization and reuse them until the profile agent changes them;
• track discovered, shortlisted, prepared, blocked, and applied jobs in CSV/Markdown files.

The agent team

The jobroute-orchestrator-agent is the entry point. It owns the workflow and delegates to specialists. This matters for portability: some clients support direct agent handoffs while others require the parent session to invoke the next specialist.

Agent	Responsibility
jobroute-orchestrator-agent	Runs the workflow, follows handoffs, handles pauses, and continues batches.
jobroute-profile-agent	Resume ingestion, candidate profile, preferences, and persistent application facts.
jobroute-enrichment-agent	Asks only high-impact missing questions within a strict question budget.
jobroute-discovery-agent	Finds jobs from configured MCP/API sources, public ATS pages, web search, or supplied URLs.
jobroute-qualification-agent	Scores fit, detects country/location, sponsorship signals, duplicates, and hard blockers.
jobroute-materials-agent	Produces tailored resume, 6–10 line cover letter, and grounded application answers.
jobroute-qa-agent	Verifies evidence, consistency, country/JD relevance, and application readiness.
jobroute-application-agent	Uses browser tooling when available, fills forms, uploads files, and respects review mode.
jobroute-tracking-agent	Updates file-based state and advances to the next queued job.

Every specialist returns a standard handoff. The orchestrator either invokes the next agent automatically or tells the user exactly which agent to invoke if the current client cannot do it.

Safety and evidence rules

JobRouteAI follows four non-negotiable rules:

1. Never fabricate candidate evidence. Technologies, dates, titles, metrics, certifications, visa status, salary, achievements, and leadership scope must come from saved evidence or a user answer.
2. Reuse confirmed facts. If the user has already answered a factual application question, the saved answer is reused until the profile agent changes it.
3. Automated mode does not ask JD-specific clarification questions. Missing optional evidence is marked unknown/unsupported. Missing required personal/legal facts move only that application to USER_INTERVENTION_REQUIRED while the rest of the queue continues.
4. Submission policy is explicit. Manual, assisted, and automated modes are defined in the candidate preferences rather than in the installer.

Example: if an application asks “Are you legally authorized to work in Australia?” and no verified answer exists, JobRouteAI must ask. Once answered, the country-scoped fact is persisted and reused for future Australian applications.

Repository layout

JobRouteAI/
├── AGENTS.md
├── CLAUDE.md
├── agents/                         # canonical agent specifications
├── .github/
│   ├── agents/                     # GitHub Copilot custom agents
│   ├── copilot-instructions.md
│   ├── CODEOWNERS
│   └── workflows/validate.yml
├── .claude/
│   └── agents/                     # Claude Code project subagents
├── .codex/
│   ├── config.toml
│   └── agents/                     # Codex project custom-agent roles
├── config/
│   ├── sources.default.yaml
│   ├── policies.yaml
│   └── integrations.example.yaml
├── data/
│   └── README.md
├── templates/
│   ├── candidate/
│   └── state/
├── scripts/
│   ├── install.ps1
│   ├── install.sh
│   ├── doctor.ps1
│   ├── doctor.sh
│   └── validate_repo.py
└── docs/
    ├── ARCHITECTURE.md
    ├── INTEGRATIONS.md
    ├── MAIN_BRANCH_PROTECTION.md
    └── TESTING.md

Installation

The installer configures integrations only. It does not ask for role, country, salary, visa, location, or application preferences. Those belong to the profile agent so preferences remain free-form and easy to change later.

Windows

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\install.ps1

macOS / Linux / WSL

chmod +x scripts/install.sh scripts/doctor.sh
./scripts/install.sh

The installer detects supported local clients and lets you configure any combination of:

• Playwright MCP for browser automation (optional; currently requires Node.js 20+);
• LinkedIn-compatible MCP endpoint/command supplied by the user;
• Indeed-compatible MCP endpoint/command supplied by the user;
• any custom MCP endpoint/command;
• Adzuna API credentials;
• Jooble API credentials.

LinkedIn and Indeed are intentionally treated as bring-your-own compatible connectors rather than hard-coded unofficial scrapers. JobRouteAI remains usable when they are skipped.

Secrets are written only to .env.local, which is ignored by Git. Integration metadata is written to config/integrations.local.yaml, which is also ignored.

After installation:

./scripts/doctor.sh

or on Windows:

.\scripts\doctor.ps1

First run

Start your preferred AI coding client from the repository root and invoke the orchestrator or profile agent.

Codex

Use jobroute-orchestrator-agent and initialize my JobRouteAI profile.

Claude Code

Use jobroute-orchestrator-agent and initialize my JobRouteAI profile.

GitHub Copilot

Select jobroute-orchestrator-agent from the agent picker, or ask Copilot to use it.

The profile agent will offer resume input choices:

1. Use a resume attached/uploaded in the current AI client
2. Use a resume already placed under ./resume/
3. Use an explicit local file path

Supported source formats are .pdf, .docx, .txt, and .md.

The first successful import creates private local state under data/candidate/. That directory is ignored by Git.

Candidate knowledge, not repeated resume parsing

The original resume is a source artifact, not the long-term memory format. After ingestion, JobRouteAI maintains:

data/candidate/
├── profile.yaml
├── evidence.md
├── preferences.yaml
├── application-facts.yaml
└── source.yaml

• profile.yaml holds structured career facts: experience, skills, education, projects, certifications, dates, and roles.
• evidence.md holds richer examples useful for tailoring and application questions.
• preferences.yaml holds free-form search/application preferences.
• application-facts.yaml holds user-confirmed factual answers, including country-scoped work authorization.
• source.yaml records resume source/fingerprint metadata so an unchanged resume does not need to be re-imported.

When a new resume is imported, saved user-confirmed enrichment is merged rather than silently discarded.

Enrichment without an interview loop

Profile enrichment is bounded:

• initial/profile enrichment: at most 5 questions in one batch;
• JD-specific enrichment in manual or assisted mode: at most 3 high-impact questions;
• JD-specific questions in automated mode: disabled;
• previously answered questions are never repeated;
• “skip” is valid and records the field as unknown;
• optional unknowns do not block the workflow.

Application modes

Application mode lives in data/candidate/preferences.yaml and can be changed through jobroute-profile-agent.

Mode	JD clarification	Browser filling	Final submission
manual	Allowed, bounded	Optional	User-controlled
assisted	Allowed, bounded	Yes	Stops before submit by default
automated	No JD-specific questions	Yes	May submit when policy allows; unknown required facts pause that job only

A required fact is different from a missing skill. If a job prefers Kubernetes and there is no evidence, JobRouteAI simply does not claim Kubernetes. If an application requires a legal work-authorization answer and none is saved, the application is marked USER_INTERVENTION_REQUIRED.

Job discovery without LinkedIn MCP

LinkedIn is not the foundation of discovery. The discovery agent can combine:

• selected MCP connectors;
• Adzuna/Jooble when API credentials are configured;
• public job/ATS pages and public ATS endpoints where available;
• the coding client's own web/search capabilities when available;
• manually supplied job URLs.

This means JobRouteAI still works if every optional MCP is skipped. Coverage will depend on the capabilities available in the user's AI client and configured sources.

File-based application state

No database is required. Runtime state is deliberately human-readable:

data/jobs/jobs.csv
data/jobs/applications.csv
data/jobs/review-queue.md
data/jobs/history/

The state machine is:

DISCOVERED
  -> SCORED
  -> SHORTLISTED
  -> MATERIALS_READY
  -> QA_PASSED
  -> READY_TO_APPLY
  -> AWAITING_REVIEW | APPLYING
  -> APPLIED

Other states include REJECTED, DUPLICATE, EXPIRED, BLOCKED, FAILED, SKIPPED, and USER_INTERVENTION_REQUIRED.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a PR.

The project is designed so contributors work through pull requests while main remains owner-controlled. See docs/MAIN_BRANCH_PROTECTION.md for the recommended GitHub ruleset.

Good first contribution areas include job-source adapters/instructions, country resume guidance, installer improvements, agent tests, and ATS/browser fixtures.

Privacy

Never commit:

• a real resume;
• candidate profile/evidence;
• job-application history;
• API keys or OAuth tokens;
• browser cookies/session storage;
• generated applications containing personal data.

The included .gitignore excludes the standard private paths, but always inspect git status before committing.

License

JobRouteAI is released under the MIT License.

Disclaimer

JobRouteAI is an automation and drafting project, not a recruiting, immigration, legal, or employment service. Job availability, visa sponsorship, work authorization, application requirements, and website terms can change. Users remain responsible for the accuracy of submitted information and for complying with the terms of each source and application site.