karyab 1.0.0

Personal job-finding automation: fetch, rank, track job postings.

karyab

kaaryab (Persian کاریاب, "job finder") — personal job-hunting automation for the terminal.

karyab fetches job postings from multiple sources, ranks them against your profile, builds a daily shortlist you can act on, and tracks the applications you submit — nudging you to follow up when a posting goes quiet.

Privacy by design. This repository contains code only. Your personal data — profile, CV, API keys, the application database — never lives in the repo. It lives under your XDG directories (~/.config/karyab, ~/.local/share/karyab). See AGENTS.md and docs/ARCHITECTURE.md.

Install

pipx install "karyab[rank,mcp,oauth,ui]"

Quickstart

karyab setup   # guided onboarding: config, email auth, first fetch
karyab run     # fetch → rank → digest (the daily pipeline)
karyab ui      # web UI at http://127.0.0.1:16666

Commands

Command	Description
karyab setup	Guided onboarding: init, config, email auth, first fetch
karyab config	Create config + secrets from templates; open in $EDITOR
karyab run	Fetch → rank → digest (full daily pipeline)
karyab fetch	Fetch + normalize + store postings from enabled sources
karyab rank	Score stored jobs for fit against your profile
karyab digest	Render the daily Markdown shortlist
karyab followups	List applications gone quiet (stale by configured threshold)
karyab apply <id>	Mark a job as applied
karyab ui	Manage the web-UI container (start/stop/logs)
karyab email-auth	Authenticate Microsoft/Outlook IMAP via OAuth2 device-code flow
karyab mcp	Run the MCP stdio server for Claude Code
karyab mcp-setup	Register the karyab MCP server with Claude Code
karyab schedule	Manage the systemd user timer (install/status/logs/uninstall)
karyab update	Upgrade karyab via pipx (or print manual guidance)
karyab init	Create XDG dirs, copy example config, init database
karyab --version	Print installed version

Run karyab <command> --help for per-command options.

Ranking

Configure under [ranker] in ~/.config/karyab/config.toml. Five backends:

Backend	How it works
anthropic	Anthropic API (default; requires ANTHROPIC_API_KEY or key in secrets)
ollama	Local Ollama instance — fully offline, no API key
manual	No autonomous scoring; use karyab mcp-setup + Claude Code MCP tools to score interactively
claude_cli	Shells out to the claude CLI — uses your Claude subscription, no extra key
opencode	Shells out to the opencode CLI — requires ANTHROPIC_API_KEY

Manual ranking (no API key, no subscription needed for the ranker itself):

[ranker]
backend = "manual"

Then register the MCP server and score from Claude Code:

karyab mcp-setup
# In Claude Code: use get_profile, list_unranked_jobs, set_job_rank
karyab digest      # build shortlist from scores you set

Sources

• ATS public boards: Greenhouse, Lever, Ashby, Teamtailor — direct employer feeds, best signal
• Aggregators: Adzuna, The Muse, Remotive
• Remote boards: Remote OK, Arbeitnow, We Work Remotely
• Email alerts (IMAP): LinkedIn / Indeed job-alert emails via IMAP — no scraping, no ToS risk

No LinkedIn/Indeed scraping. Against their ToS, fragile, account-ban risk. Set up email job-alerts on those sites instead; karyab reads the alert emails.

Microsoft / Outlook email (OAuth2)

[sources.email]
enabled = true
imap_host = "outlook.office365.com"
folder    = "INBOX"
username  = "[e-mail]"
auth      = "oauth"

Authenticate once:

karyab email-auth
# Prints a URL and short code. Open the URL, enter the code.
# Subsequent fetches refresh the token silently.

Scheduling

Install a systemd user timer for daily automation:

karyab schedule install    # enable daily fetch timer
karyab schedule status     # check timer state
karyab schedule logs       # tail the fetch service logs
karyab schedule uninstall  # remove timer

Update

karyab update    # upgrade via pipx, or prints manual guidance if not installed via pipx

Development

git clone https://codeberg.org/maxagahi/karyab
cd karyab
make dev       # create .venv + install dev+runtime deps + git hooks
make test      # run test suite
make lint      # ruff check
make typecheck # mypy src
make check     # pre-commit run --all-files (lint, fmt, type, secret-scan)

CI runs on Forgejo (.forgejo/workflows/). Release: bump the version in pyproject.toml, push a vX.Y.Z tag — the pipeline publishes to PyPI and builds a container image automatically.

Contributing / Agents

AGENTS.md is the contributor + AI-agent manual: project layout, the bot git/PR workflow (Codeberg/Forgejo, not gh), and the privacy rule (no personal data in the repo — gitleaks enforces it).

Any PR that touches code under src/karyab/ must bump the version in pyproject.toml and add a CHANGELOG.md (Unreleased) entry. CI enforces both (verify-version-bump); the same checks run locally at pre-push.

Architecture

 sources ──▶ normalize ──▶ store ──▶ rank ──▶ digest ──▶ you apply
                                                            │
                                                  track ◀───┘
                                                    │
                                            follow-up nudges

Local-first, SQLite-backed pipeline. Each stage has a narrow contract; stages run independently (a timer fetches; you rank and read the digest later). See docs/ARCHITECTURE.md for the full design.

License

Apache-2.0.