🧭 Why

boss-agent-cli unifies job discovery, welfare filtering, local resumes and AI, application and messaging, recruiter candidate workflows, and resumable crawling in one CLI. People run boss for a terminal wizard; agents use JSON, schema, MCP, or the Python API against the same workflow state. boss schema remains the capability source of truth.

⚠️ Runtime Boundary

Historical operating_mode=assisted|research configuration remains compatible, but both modes can call every implemented capability and no longer produce mode-level COMPLIANCE_BLOCKED errors. Missing platform implementations still return NOT_SUPPORTED; authentication, account-risk, and network failures keep structured recovery metadata. Long-running workflows remain bounded by timeout, retry, budget, checkpoint, and stop controls.

✨ Features

• Job discovery: keyword search + layered filters, with cached show navigation — search show detail
• Welfare filtering (the differentiator): --welfare "双休,五险一金" pages, fetches details, runs real AND matching, and can --sort score by local match score — search --welfare
• HR activity filter: --active 3d keeps only jobs whose recruiter was active recently, so you don't spend applications on recruiters who never log in; online is list-only with the same request volume as a plain search, while other levels may fetch per-job details and are slower and riskier — prefer --active online for low-risk use — search --active
• Terminal wizard: run boss or boss wizard, select a role, platform, and goal, then resume the same workflow through JSON, run IDs, or MCP
• Local shortlist & stats: inspect details, read web favorited jobs with validity status and sync only active entries, organize candidates with local tags and notes, compare jobs offline, and see funnel stats — shortlist stats watch preset favorites
• AI job-hunting assist + local models: JD analysis, resume polish, role-targeted optimization, keyword suggestions, resume optimization, shortlist fit reports, interview prep, chat coaching; local weights stay outside the Python package via Ollama/vLLM OpenAI-compatible endpoints — ai analyze-jd ai suggest-keywords ai resume-optimize ai interview-prep ai chat-coach ai local configure ai local smoke
• Schema-first + JSON envelope: stdout is a JSON-only {ok, data, pagination, error, hints} envelope, boss schema is the capability source of truth, and an MCP server with 78 tools exposes every implemented capability
• Recruiter workflow: confirm recruiter identity, then candidate search, recommendations, first contact with built-in read-state cleanup, resumes, chats, replies, and job management — hr whoami/candidates/recommendations/greet/applications/resume/chat/last-messages/reply/request-resume/jobs
• Platform layer: live Platform / RecruiterPlatform registries behind the global --platform option; zhipin (BOSS Zhipin) is the only registered platform

🚀 Quickstart

# Install (uv recommended; the browser core is only for user-triggered login / local export)
uv tool install boss-agent-cli
patchright install chromium

# Human entrypoint: choose role, platform, and goal in the wizard
boss

# Agents and advanced users can still call commands directly
boss doctor                                                   # environment check
boss login                                                    # platform-aware login
boss status                                                   # verify login
boss search "Golang" --city 广州 --welfare "双休,五险一金"     # search + welfare filtering
boss search "Golang" --city 广州 --active 3d                  # only recruiters active in the last 3 days
boss detail <security_id>                                     # view detail
boss shortlist add <security_id> <job_id> --tags backend,remote  # add to local shortlist with local tags
boss shortlist compare --tag remote                           # compare shortlisted jobs offline
boss stats                                                    # local stats

# Recruiter mode
boss hr candidates "Python" --city 101010100
boss hr recommendations --job-id <encJobId>
boss hr jobs list

Every command outputs structured JSON (ok for success, exit 0/1 by default; the optional --exit-codes sysexits returns semantic exit codes per error class). Full walk-through: Getting Started.

🎭 Roles & Platforms

Platform	Candidate	Recruiter	Status
BOSS Zhipin (zhipin)	✅	✅	default

boss platforms                             # list registered platforms and capability status (currently zhipin only)
boss --platform zhipin search "Python"     # zhipin is the default, so --platform can be omitted

boss hr ... and recruiter-side agent automation currently support only zhipin-recruiter. Architecture notes: docs/platform-abstraction.en.md.

🤖 Agent Integration

Start here: Agent Quickstart · Capability Matrix · Host Examples

// Option 1: MCP (recommended) — Claude Desktop / Cursor and other MCP hosts; MCP server with 78 tools
{ "mcpServers": { "boss-agent": { "command": "uvx", "args": ["--from", "boss-agent-cli[mcp]", "boss-mcp"] } } }

Prefer not to set up a local Python toolchain? Use the bundled container: BOSS_UID=$(id -u) BOSS_GID=$(id -g) docker compose run --rm boss-mcp. The image deliberately ships no browser kernel — run boss login on the host first, then mount ~/.boss-agent. See Docker integration.

OpenCode can use the checked-in example directly:

cp examples/opencode/opencode.json ./opencode.json
uv sync --all-extras
uv run boss-mcp --data-dir ./.boss-agent --help

After portable/global install, copy the bundle's examples/opencode.json into any OpenCode project. It starts boss-mcp --data-dir ./.boss-agent, keeping review, pending, and logs project-local.

# Option 2: subprocess — let the Agent read the self-description, then parse stdout JSON
boss schema

# Option 3: embed in Python (ships with py.typed)
from boss_agent_cli import AuthManager, BossClient, AuthRequired
with BossClient(AuthManager(...)) as client:
    result = client.search_jobs("Golang", city="北京")

📚 Commands

boss schema exposes 39 top-level commands + 14 first-level recruiter subcommands, grouped by workflow:

• Auth: login · logout · status · doctor
• Discover: search · detail · show · cities · history
• Organize: watch · preset · shortlist · stats · favorites
• Resumable crawl: crawl configure/run/start/status/results/resume/stop/shortlist
• Resume / AI: resume · me · ai analyze-jd · ai polish · ai optimize · ai fit · ai suggest-keywords · ai resume-optimize · ai cover-letter · ai interview-prep · ai chat-coach · ai local
• Utility / workflow: wizard · schema · platforms · export · config · clean
• Candidate actions: greet · batch-greet · apply · exchange · chat* · pipeline · digest
• Recruiter: hr whoami/applications/candidates/recommendations/greet/resume/chat/chatmsg/last-messages/reply/request-resume/accept-resume/download-resume/jobs

Full command tables, parameters, and welfare-matching internals: Command Reference. The capability source of truth is boss schema (with --format openai-tools / anthropic-tools exports).

Bulk crawl requires uv sync --extra crawl. It uses its own <data-dir>/crawl/chrome-profile and never attaches to a daily Chrome profile. Hooks are disabled by default; local scripts require both an explicit profile and a directory containing SHA256SUMS:

boss crawl configure --max-requests 20 --max-details 50 --max-seconds 600 --max-retries 1
boss crawl run "AI" --city 杭州 --pages 3 --with-detail `
  --hook-profile screenshot-full --hook-dir E:\boss-agent-cli-local-hooks\AntiDebug_Breaker
boss crawl resume <run_id>
boss crawl stop <run_id>
boss agent crawl --run-id <run_id> --resume <resume-name>

crawl run is sequential, checkpoints SQLite state, and incrementally writes JSON / CSV / XLSX artifacts. Request, detail, wall-clock, and retry budgets are fixed; boss crawl stop stops at the next safe point. Exports and crawl results redact security_id, selectors, and recruiter fields; boss clean --privacy removes crawl state, budgets, and exports. Fine-grained MCP crawl tools read or import an existing run_id; boss_wizard can start, resume, and stop the shared workflow. A platform risk code or security page stops the task and returns a resume command.

🩺 Troubleshooting

boss doctor             # environment check
boss status --live      # optional low-frequency read-only probe
boss doctor --live-probe

Every error envelope carries code + recoverable + recovery_action, so agents can react programmatically. boss doctor checks CDP reachability and reports the browser_channel summary. With the default auto source, chat and chatmsg use httpx with stored credentials; explicitly selecting --browser-source existing-browser reuses an existing target-site tab through CDP without reading CLI-stored cookies. Exhausted existing-browser candidates return BROWSER_SESSION_NOT_FOUND plus boss doctor, while the ordinary unauthenticated path still returns AUTH_REQUIRED plus boss login. Every source stops on platform risk-control blocks and checkpoints the workflow; declared adapters must remain bounded, redacted, stoppable, and explicitly resumed only after the risk condition is resolved.

v3.0.0 migration: the Browser Bridge daemon, Chrome extension, and [bridge] installation extra have been removed. Upgrading the CLI does not stop an old daemon or uninstall the browser extension. Manually stop the old daemon, disable or remove the old extension, and drop [bridge] from installation commands. The default browser fallback chain is CDP → headless. To reuse an existing session only, first log in manually on the official site in a local CDP browser, then run:

boss --browser-source existing-browser --cdp-url http://localhost:9222 chat

This source does not create pages, navigate, inject cookies, or launch a browser. Keep the CDP debugging port within a trusted local environment; never expose it publicly or use it to bypass platform risk controls.

Full checks, CDP launch examples, and error codes: Troubleshooting. For Cookie / CDP / patchright / request-rate / drift issues, read Platform Risk Boundaries first.

⚙️ Configuration

boss config list                      # view all settings
boss config set log_level debug       # set the log level
boss config reset                     # restore defaults

Settings live in ~/.boss-agent/config.json: request delays, batch-greet delay, log level, CDP URL, export dir, platform / role.

🏗️ Architecture

CLI (Click)
  └─ Wizard / WorkflowRunner (TTY + headless JSON + persisted run state)
       └─ Capability metadata (assisted / research compatibility; no mode gate)
       └─ AuthManager ── user-triggered login state (Fernet + PBKDF2 machine-bound encryption)
       └─ Platform registries ── zhipin / zhipin-recruiter
       └─ BossClient ── httpx + throttle; CDP / patchright compatible for login & export
       └─ CacheStore (SQLite WAL) · AIService (OpenAI-compatible / Ollama / vLLM)
            └─ output.py → JSON envelope → stdout

Invariants: stdout is JSON-only · stderr holds logs · exit 0/1 (optional --exit-codes sysexits for semantic codes) · errors carry code/recoverable/recovery_action · boss schema is the authoritative capability source. Two audiences, one envelope: hints.next_actions holds follow-up commands for the Agent to run; hints.operator_actions holds natural-language guidance for the human operator (scan a QR code, adjust filters in the browser — anything done away from the terminal). TTY renders only the latter, to stderr; an Agent should relay it to the operator. Command or wizard: single-shot, stateless capability calls go through top-level commands; anything needing cross-step state, resumability, or handing guidance to a human goes through boss wizard (goals listed under wizard_catalog in boss schema). Stack: Python ≥ 3.11 · Click · httpx · patchright / CDP (login, export, and declared browser adapters) · cryptography · sqlite3 (WAL) · pytest (2900+).

🔌 Local Storage

All state lives under ~/.boss-agent/ — encrypted tokens, cached searches, shortlist, local resumes, AI config, and external model registry. Model weights are not bundled into the Python package; nothing leaves your machine except explicit API calls or user-confirmed model downloads.

🤝 Contributing

See CONTRIBUTING.en.md and Getting Started. TL;DR: fork → feat/xxx branch → write tests → python scripts/quality_baseline.py (on Chinese Windows, set $env:PYTHONUTF8='1' first) → PR.

Thanks to everyone who has made boss-agent-cli better — go follow them! ❤️

❤️ Support

• If this project helps you, the most direct support is a Star ⭐, or sharing it with someone who is job hunting.
• Hit a problem or have an idea? Open an Issue — or go straight to a PR.
• Curious about the rest of the fleet? Drop anchor at the home port bobochang.cn 🧭.

This project benefits from geekgeekrun · boss-cli · opencli — thanks to all of them.

⭐ Star History

A static SVG generated locally with mystarhistory — served from this repo, with no third-party dependency.

⚠️ Disclaimer

Follow applicable law, platform terms, and privacy requirements. Set explicit input, volume, timeout, and stop limits for bulk outreach, candidate data, and browser-adaptation workflows, and protect local credentials and exported artifacts.

📑 License & Communities

MIT © can4hou6joeng4 · LINUX DO