Openings

Openings

A job crawler, archive and application tracker you run yourself, operable byyou and by your AI agents through the same API.

Why

Job boards forget what you saw, spreadsheets forget what you sent, and theCV you tailored for a role ends up in a folder nobody opens again. Openingskeeps all of it in one local database: every posting it collected, everystatus change with its date, every note, form answer, CV and cover letterattached to the job it belongs to. It is built for one person, runs in twocontainers on your own machine, and never sends your data anywhere.

• Collect from job boards (through JobSpy),company career pages on Greenhouse, Lever, Ashby and SmartRecruiters, RSSfeeds and the Adzuna API. Anything the crawler cannot see, you or an agentadd by hand.
• Rank with keyword categories and signed weights you write yourself;every job shows which categories matched and why it scored what it did.
• Track one status per job from new to offer, with a timeline. A jobis the opening, not the advert: the same role seen on two boards is one jobwith two postings. Blacklisting hides, never deletes, and can be undone.
• Archive the application itself next to the posting, and take it outagain as one zip.
• Search by meaning with a small sentence model that runs locally.
• Automate through a REST API and an MCP server with the same tools thedashboard uses, so an agent can triage the inbox, attach a tailored CV andrecord an application while you watch the pipeline.

The YAML owns intake and scoring; the database owns state. A job's statusis never derived from configuration.

Quick start

cp config/settings.example.yaml settings.yaml   # edit locations, queries, scoring
docker compose up -d
open http://127.0.0.1:8501

One process serves the dashboard at /, the REST API at /api and the MCPendpoint at /mcp. Ports bind to 127.0.0.1 by default.

A look around

The Pipeline: one column per status, cards move with the keyboard, by dragging or from a menu.	The application: files with inline previews, form answers, notes, one zip for everything.

The dashboard works on a phone as well as a desk, in light and dark. Morein Dashboard.

Agents

Point an MCP client at http://127.0.0.1:8501/mcp (streamable HTTP):

{ "mcpServers": { "openings": { "type": "http", "url": "http://127.0.0.1:8501/mcp" } } }

A typical session: list_jobs(statuses=["new"], min_score=40) to triage,blacklist_jobs for the noise, get_job for the posting and its scorebreakdown, add_attachment with the tailored CV, add_note with the formanswers, set_status(..., "applied", note="sent through the careers page").For a posting the crawler never saw, add_job with the digested fields. Thefull tool list is in MCP server.

Configuration

Everything about what to collect and how to rank it lives insettings.yaml. The annotated example is thereference; unknown keys fail at boot and secrets can be written as$ENV_VAR.

sources:
  jobspy:
    sites: [linkedin]
    locations: ["Berlin, Germany", "Remote"]
    queries:
      core: ["backend engineer", "platform engineer"]
  companies:
    - { name: Example, ats: greenhouse, slug: example, titles: [engineer] }
scoring:
  save_threshold: 20
  notify_threshold: 60
  weights: { role: 25, stack: 15, language_required: -60 }
  keywords:
    role: ["backend engineer", "platform engineer"]
    stack: ["python", "go", "postgresql"]
    language_required: ["fluent german", "deutsch erforderlich"]

See Configuration andSources.

Commands

Documentation

• Docker deployment
• Configuration
• Sources
• Dashboard
• REST API
• MCP server
• Operations
• Architecture
• Testing
• Release process

Development

uv sync
npm --prefix frontend install
cp config/settings.example.yaml settings.yaml
OPENINGS_DATA_DIR=./data OPENINGS_CONFIG=./settings.yaml uv run openings web
uv run pytest
npm --prefix frontend run quality
npm --prefix frontend run test:e2e

See CONTRIBUTING. Openings is a personal tool that grewinto a small product; issues and pull requests are welcome.

License

MIT.