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.

Requirements

• Python 3.11+
• A container runtime for the web UI — podman (recommended) or docker.
• Optional ranker tooling, depending on the backend you choose: Claude Code, opencode, ollama, or an Anthropic API key. See the in-app Help page for the full per-backend setup.

Install

pipx install karyab

After installing, register the MCP server with your coding agent and read the in-app Help page (/help, linked in the nav) for full ranker-backend and email/LinkedIn-alert setup:

karyab mcp-setup --target claude|opencode|both

Quickstart

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

Tip — let an LLM fill your config. The trickiest part is writing good filters (target roles, must-have keywords, source tokens, the ranker profile). Paste config.example.toml into Claude (or any LLM), describe the jobs you want, and have it generate your ~/.config/karyab/config.toml filters and [profile]. With the MCP server registered (karyab mcp register), Claude can also read your unranked jobs and tune the filters as you go.

Commands

Run karyab <command> --help for per-command options. For grouped commands, run karyab <group> --help (e.g. karyab email --help) for per-group options.

Ranking

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

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 register
# 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  = "you@outlook.com"
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://github.com/m-agahi/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.