can4hou6joeng4/boss-agent-cli

boss‑agent‑cli – A terminal‑first job‑search & recruiting assistant

What it is

• A Python‑based command‑line interface that lets a human user or an AI Agent interact with the Chinese job platform BOSS 直聘 (zhipin). It bundles the whole recruiting workflow – job discovery, welfare filtering, local short‑listing, AI‑enhanced resume work, and recruiter‑side actions – into a single, JSON‑output‑driven CLI.

Why it matters

• The tool abstracts the platform behind a schema‑driven JSON envelope ({ok, data, pagination, error, hints}), making it easy for downstream automation (MCP hosts, shell scripts, Python SDKs) to consume the capabilities without scraping HTML directly.
• It adds a “welfare filter” that matches benefits (e.g., 双休, 五险一金) with AND logic and can sort results by a local relevance score – a feature not offered by the native site.
• All heavy‑lifting (search, detail retrieval, chat, resume polishing) can be powered by local LLMs via Ollama/vLLM or any OpenAI‑compatible endpoint, keeping data on the user’s machine.

Key capabilities

Area	Commands (examples)	Highlights
Job discovery	boss search "Golang" --city 广州 --welfare "双休,五险一金"	Keyword search + 8‑dimensional filters, cached results, HR‑activity filter (--active 3d).
Welfare filtering	--welfare "双休,五险一金" --sort score	Automatic pagination, real‑time matching, score‑based ranking.
Local candidate pool	boss shortlist add <sec_id> <job_id> --tags 后端,远程 boss stats	SQLite‑backed short‑list with tags, notes, funnel statistics.
AI‑enhanced job‑seeker tools	boss ai analyze-jd boss ai polish boss ai local configure	JD analysis, resume polishing, interview simulation; works with external LLMs.
Recruiter workflow	boss hr candidates "Python" --city 101010100 boss hr greet boss hr download-resume	Search candidates, send greetings, manage applications, chat, download resumes – all via the same CLI.
Agent integration	boss schema (outputs OpenAI/Anthropic tool definitions) boss-mcp (MCP host)	JSON schema is the single source of truth; can be called via MCP, subprocess, or Python SDK.
Recoverable crawling	boss crawl configure … boss crawl run …	Headless Chrome (CDP) driven crawling with checkpointing, budget limits, and privacy‑safe export.

Typical human workflow

# Install (uv is recommended)
uv tool install boss-agent-cli
patchright install chromium   # needed for login via Chrome

# Start the interactive wizard
boss

# Search with welfare filter
boss search "Golang" --city 广州 --welfare "双休,五险一金"

# Add a promising posting to the local pool
boss shortlist add <security_id> <job_id> --tags 后端,远程

# Run AI‑assisted resume polishing
boss ai polish --model ollama:mistral

# View offline statistics
boss stats

Agent / programmatic usage

• MCP host – expose the 77 implemented tools via a JSON config:

  {"mcpServers": {"boss-agent": {"command": "uvx", "args": ["--from", "boss-agent-cli[mcp]", "boss-mcp"]}}}
  

• Subprocess – call boss schema to retrieve the tool definitions, then invoke commands and parse the JSON envelope.
• Python SDK – import BossClient:

  from boss_agent_cli import AuthManager, BossClient
  client = BossClient(AuthManager(...))
  result = client.search_jobs("Golang", city="广州")
  

Architecture at a glance

CLI (Click) ──> AuthManager (Fernet‑encrypted login) ──> Platform registry (zhipin, zhipin‑recruiter)
          │                     │
          │                     └─> BossClient (httpx + rate‑limiting, optional CDP bridge)
          │
          └─> CacheStore (SQLite WAL) ──> AIService (OpenAI‑compatible / Ollama / vLLM)
                │
                └─> output.py → JSON envelope (stdout)

All state lives under ~/.boss-agent/ (encrypted credentials, search cache, short‑list, AI config). No model weights are shipped; they are fetched on demand.

Installation & distribution

• Published on PyPI (boss-agent-cli).
• Also distributable via Docker (docker compose run --rm boss-mcp).
• Supports optional extras for crawling (uv sync --extra crawl).

License

• MIT License (see LICENSE).

Who should use it

• Job seekers who prefer a terminal UI and want AI‑assisted resume work.
• Recruiters on BOSS 直聘 who need a scriptable way to manage candidates.
• Automation engineers / AI agents that need a stable, JSON‑based interface to the platform (e.g., for building a personal job‑search bot or integrating into a larger RAG pipeline).

Caveats

• Requires a Chrome/Chromium installation for login and crawling (handled by patchright).
• Platform‑specific: currently only BOSS 直聘 is supported; other Chinese job boards are not.
• Users must respect platform terms, rate limits, and privacy regulations; the tool provides structured error codes (NOT_SUPPORTED, AUTH_REQUIRED, etc.) and built‑in timeout/retry controls to help stay compliant.

---

For a full command reference, quick‑start guide, and troubleshooting steps, see the repository’s docs/ folder.