{
"markdown": "\n\n# Job Seek\n\n**Open-source job search built from 5,300+ company career sites and ATS feeds.**\n\nFind roles soon after employers publish them, search them through one consistent schema, and track the applications that matter to you.\n\n[**Try jseek.co →**](https://jseek.co) · [Use the MCP server](#use-job-seek-from-ai-tools-and-code) · [Add a company](#add-a-company) · [Run it yourself](#run-it-yourself)\n\n[](LICENSE) [](LICENSE-JOB-DATA) [](https://github.com/colophon-group/jobseek/actions/workflows/ci.yml) [](https://github.com/colophon-group/jobseek/actions/workflows/codeql.yml) [](https://pypi.org/project/jobseek-crawler-setup/) [](https://github.com/colophon-group/jobseek)\n\n[](https://jseek.co)\n\nTracking Stripe · Anthropic · OpenAI · Figma · Vercel · Datadog · Mistral · Hugging Face · Linear · Notion · Roche · Nestlé · UBS · Swisscom · ABB · SAP · Siemens · Klarna · N26 · Wise · Monzo — and thousands more. Browse the source-of-truth registry in [`companies.csv`](apps/crawler/data/companies.csv).\n\n
\n\n---\n\n## Why Job Seek\n\nJob Seek is for people who already have a sense of where they want to work. Instead of starting with reposted listings, it monitors employer career sites and their applicant-tracking systems, then normalizes each source into one searchable model.\n\n| | |\n|---|---|\n| **Broad direct-source coverage** | 5,300+ companies across 6,200+ configured career boards, primarily employer-hosted sites and ATS feeds, plus a small number of platform-hosted sources. |\n| **One search model** | Typesense-backed keyword search and facets for occupation, seniority, technology, location, work mode, employment type, salary, experience, and posting language. |\n| **Source-URL identity** | Postings are canonicalized and deduplicated by source URL, while every result links back to the original listing. |\n| **A complete job-search workspace** | Public watchlists, saved roles, application stages, interview notes, and pipeline statistics live alongside search. |\n| **Open interfaces** | Use the web app, the public REST API, or the hosted read-only MCP server from any compatible AI client. |\n\n## What you get on jseek.co\n\n| | |\n|---|---|\n| [](https://jseek.co/en/explore) | **Explore.** Search postings across every tracked company and combine filters without creating an account. |\n| [](https://jseek.co/en/company/stripe) | **Company pages.** See active and last-year posting counts, filter within one company, explore similar employers, and open every role at its source. |\n\nWith a free account, you can create one watchlist and use the built-in **application tracker** to move roles through `saved → applied → interviewing → offered/rejected`, record interview rounds, and review pipeline statistics.\n\n**Pro is coming soon.** The planned $10/month tier adds unlimited watchlists and email alerts for new matches.\n\n> Built by [Colophon Group](https://colophon-group.org), a small team in Switzerland — so German, French, and Italian are first-class product languages, not afterthoughts.\n\n---\n\n## Use Job Seek from AI tools and code\n\nThe hosted MCP endpoint exposes read-only tools for job search, posting details, companies, taxonomies, public watchlists, and prefilled watchlist links:\n\n```text\nhttps://jseek.co/mcp\n```\n\nIt uses Streamable HTTP and does not require authentication. Add the URL as a custom MCP connector, or run the published package locally:\n\n```bash\nnpx @jseek/mcp-server\n```\n\nSee [`packages/mcp-server/README.md`](packages/mcp-server/README.md) for client-specific setup and tool examples. For direct HTTP integrations, the public REST contract is available at [`/api/openapi.json`](https://jseek.co/api/openapi.json).\n\n---\n\n## Add a company\n\nOpen issues labelled [`company-request`](https://github.com/colophon-group/jobseek/issues?q=is%3Aopen+label%3Acompany-request) are companies waiting to be added. The production backlog is processed by an isolated, Hetzner-hosted Codex runner; contributors can resolve an issue with any capable coding agent that follows the repository instructions.\n\n> **`ws` is an agent utility.** It renders the workflow, manages isolated state, and enforces the validation gates; it is not intended as a hand-configured interactive wizard.\n\nThe environment needs `git`, an authenticated `gh` CLI, Python 3.13+, and web access. Install the workflow package:\n\n```bash\npip install jobseek-crawler-setup\n```\n\nThen give your coding agent this task:\n\n> Run `ws task --issue ` and follow the printed instructions.\n\n`ws` fetches the issue, checks for duplicates, researches the company and all relevant career boards, guides monitor and scraper selection, validates extracted data and brand assets, and opens the pull request. The registered crawler types cover common ATS APIs, sitemaps, structured data, rendered pages, PDFs, and vendor-specific formats.\n\nNo issue for the company you want? [Request it.](https://github.com/colophon-group/jobseek/issues/new?labels=company-request) Anyone can.\n\nThe maintained workflow reference is [`docs/01-agent-workflow.md`](docs/01-agent-workflow.md).\n\n---\n\n## Architecture\n\nCompany and board CSVs are the configuration source of truth. The crawler keeps operational state in its own Postgres database, uses Redis for scheduling, publishes searchable documents to Typesense, and stores full descriptions in S3-compatible object storage. The web app owns authentication, watchlists, and application-tracker data in a separate Postgres boundary.\n\n\n\n```mermaid\n%%{init: {\"flowchart\": {\"rankSpacing\": 24}}}%%\nflowchart TD\n Requests[\"Company requests\"] --> Agent[\"Coding-agent PR\"]\n Agent --> CSV[\"companies.csv + boards.csv\"]\n CSV --> Runtime[\"Crawler runtime
sync · Redis · HTTP/browser workers · crawler Postgres\"]\n Runtime --> ReadLayer[\"Published read layer
Typesense · S3-compatible descriptions\"]\n ReadLayer --> Web[\"Next.js
web app · REST API · MCP\"]\n Web <--> WebDB[\"Web Postgres\"]\n```\n\n
\n\nStart with the maintained [`documentation index`](docs/README.md), then read the [system overview](docs/00-overview.md), [crawler architecture](docs/03-crawler-architecture.md), and [Typesense reference](docs/11-typesense.md).\n\n## Run it yourself\n\nJob Seek is self-hostable, but the repository currently expects operator-managed services. The root `docker-compose.yml` is development scaffolding for Postgres and Typesense, not a complete one-command production deployment.\n\n### Prerequisites\n\n- Python 3.13+ and [`uv`](https://docs.astral.sh/uv/)\n- Node.js 22+ and pnpm 10\n- A crawler-owned Postgres database\n- A separate web-owned Postgres database; both databases may run on the same server\n- Redis\n- Typesense\n- S3-compatible object storage for job descriptions\n\nThe important environment boundaries are:\n\n| Component | Core settings |\n|---|---|\n| Crawler database | `LOCAL_DATABASE_URL` |\n| Web database | `WEB_DATABASE_URL` for crawler-side reads; `DATABASE_URL` for the web app |\n| Redis | `REDIS_URL` |\n| Typesense writes | `TYPESENSE_HOST`, `TYPESENSE_PORT`, `TYPESENSE_PROTOCOL`, `TYPESENSE_OPERATIONS_KEY` |\n| Typesense web access | `TYPESENSE_SEARCH_KEY`, `TYPESENSE_WRITE_KEY`, and optionally `TYPESENSE_BROWSER_PARENT_KEY` |\n| Description storage | `R2_ENDPOINT_URL`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET`, `R2_DOMAIN_URL` |\n| Web authentication | `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`; OAuth and email providers are optional |\n\nAfter provisioning those services, create `apps/crawler/.env.local` (using its `.env.example` as a starting point) and `apps/web/.env.local`, then initialize in this order:\n\n```bash\ngit clone https://github.com/colophon-group/jobseek\ncd jobseek\ncorepack enable\npnpm install\n\n# Web-owned database\ncd apps/web\npnpm db:migrate\n\n# Crawler-owned database and derived stores\ncd ../crawler\nuv sync\nuv run playwright install chromium-headless-shell # required by run-browser\nuv run alembic -c src/migrations/alembic.ini upgrade head\nuv run crawler setup-typesense\nuv run crawler sync\n```\n\nA complete crawler deployment keeps four process roles running:\n\n```bash\nuv run crawler run # HTTP workers\nuv run crawler run-browser # Playwright workers\nuv run crawler export # Postgres → Typesense CDC\nuv run crawler drain # descriptions → object storage\n```\n\nStart the frontend separately from `apps/web`:\n\n```bash\npnpm dev # http://localhost:3000\n```\n\nProduction operators should use scoped Typesense keys and read the deployment and recovery runbooks linked from [`docs/README.md`](docs/README.md).\n\n---\n\n## What's in the repo\n\n```text\napps/crawler/ Python ingestion, normalization, scheduling, and export\n src/core/monitors/ Career-board discovery: ATS APIs, sitemaps, DOM, feeds\n src/core/scrapers/ Posting extraction: JSON-LD, DOM, PDF, vendor formats\n src/workers/ HTTP workers, browser workers, and description drain\n src/exporter.py CDC from crawler Postgres to Typesense\n src/labeller/ Daily gold-dataset labelling and Hugging Face upload\n src/workspace/ `ws` workflow and Codex company-request runner\n data/companies.csv Company configuration source of truth\n data/boards.csv Career boards with monitor + scraper configuration\n\napps/web/ Next.js 16, Drizzle, Lingui, and Better Auth\n app/[lang]/ Localized product routes: en / de / fr / it\n app/api/v1/ Public REST API\n app/mcp/ Hosted Streamable HTTP MCP endpoint\n src/db/schema.ts Web-owned Postgres schema\n\npackages/mcp-server/ Published `@jseek/mcp-server` package\ndocs/ Architecture references, ADRs, routines, and runbooks\nscripts/ Deployment, reconciliation, backup, and maintenance tools\n```\n\n## Development\n\nCrawler checks, from `apps/crawler`:\n\n```bash\nuv run pytest tests/\nuv run ruff check .\nuv run pyright\n```\n\nWeb checks, from `apps/web`:\n\n```bash\npnpm test\npnpm lint\npnpm typecheck\npnpm build\n```\n\nRepository-wide contributor and agent instructions live in [`AGENTS.md`](AGENTS.md). Crawler-specific commands and operational cautions live in [`apps/crawler/AGENTS.md`](apps/crawler/AGENTS.md).\n\n---\n\n## License\n\n- **Code** — [MIT](LICENSE). Use, modify, and redistribute it without warranty.\n- **Job-posting data** — [CC BY-NC 4.0](LICENSE-JOB-DATA). Free for research and non-commercial reuse with attribution. It is not “open data” under the strict Open Knowledge Definition. For commercial licensing, contact [business@colophon-group.org](mailto:business@colophon-group.org).\n\n---\n\n\n",
"bytes": 11681,
"sha": "afde9a90c4da72a6fa66d2460a0dcac5c48f9080641e3a745f6b10b1943be1a1",
"repo_slug": "colophon-group/jobseek",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_colophon_group_jobseek_038798be/readme"
}