boss-agent-cli

boss-agent-cli is a local command-line tool (CLI) for the BOSS Zhipin recruitment platform, aimed at both humans and AI Agents, unifying job discovery, welfare filtering, local resumes and AI, application communication, recruiter candidate handling, and resumable collection into a single CLI.

Purpose and Positioning Humans can directly run boss to enter a pure terminal wizard; Agents use JSON, schema, MCP, or the Python API to call the same set of workflows and state. boss schema is always the source of truth for capabilities. The historical configuration operating_mode=assisted|research remains compatible; both modes can call all implemented capabilities, and no longer produce mode-level COMPLIANCE_BLOCKED; capabilities not yet implemented by the platform still accurately return NOT_SUPPORTED, and authentication failures, account risks, and network errors retain structured errors and recovery actions. Long-running processes are still controlled by timeout, retry, budget, checkpoint, and stop.

Main Capabilities

• Job discovery: keyword search + 8-dimensional filtering, review cached results by number (search show detail).
• Welfare filtering (core differentiator): --welfare "双休,五险一金" automatically paginates to fetch more, performs real matching with AND logic, and can sort by local match score with --sort score (search --welfare).
• HR activity filtering: --active 3d keeps only recently active HRs, avoiding wasting applications on positions whose HRs have not been online for a long time; online only looks at the list, with the same request volume as ordinary search, while other tiers may require checking job details one by one, which is slower and carries higher risk-control risk; for low-risk scenarios, it is recommended to use --active online (search --active).
• Pure terminal wizard: directly run boss or boss wizard, and choose role, platform, and goal; the same workflow can also be advanced and resumed with --input-json, run ID, or MCP.
• Local candidate pool and statistics: after viewing details, save locally, read web job favorites with valid status and sync only valid items, use tags and notes to review candidate positions, compare offline, and view funnel statistics (shortlist stats watch preset favorites).
• AI job-seeking enhancement + local models: JD analysis, resume polishing, targeted optimization, candidate pool matching, mock interviews, communication guidance; local model weights are externalized, supporting Ollama/vLLM's OpenAI-compatible interface (ai analyze-jd, ai local configure, ai local smoke).
• Schema-driven + JSON envelope: stdout only outputs the {ok, data, pagination, error, hints} envelope, and boss schema is the source of truth for capabilities, suitable for CLI orchestration / Shell Agent / MCP / Python SDK.
• Complete recruiter workflow: candidate search, recommended talents, first greeting, attachment resume receipt and download, resumes, chat/recent messages, replies, and job management (hr candidates/recommendations/greet/applications/resume/chat/last-messages/reply/request-resume/accept-resume/download-resume/jobs).
• Platform abstraction: Platform / RecruiterPlatform dual registry + --platform global option; the currently registered platform is zhipin (BOSS Zhipin).

Usage All commands output structured JSON (ok determines success or failure, exit 0/1). For complete onboarding, see the quick start document in the project. boss hr ... and recruiter-side agent automation currently only support zhipin-recruiter. It is recommended to first read Agent Quickstart, Capability Matrix, and Host Examples. If you do not want to set up a Python toolchain on your local machine, you can use the container included in the repository: BOSS_UID=$(id -u) BOSS_GID=$(id -g) docker compose run --rm boss-mcp. The image intentionally does not include a browser kernel—first run boss login on the host machine, then mount ~/.boss-agent into it; see Docker integration for details. The OpenCode source project can directly use the repository example:portable / after global installation, use examples/opencode.json in any OpenCode project; it will start boss-mcp --data-dir ./.boss-agent, isolating review, pending, and logs per project. boss schema exposes 39 top-level commands + 13 first-level recruiter subcommands, grouped by workflow:

• Authentication: login · logout · status · doctor
• Job discovery: search · detail · show · cities · history
• Local organization: watch · preset · shortlist · stats · favorites
• Resumable collection: 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
• System / workflow: wizard · schema · platforms · export · config · clean
• Candidate actions: greet · batch-greet · apply · exchange · chat* · pipeline · digest
• Recruiter: hr applications/candidates/recommendations/greet/resume/chat/chatmsg/last-messages/reply/request-resume/accept-resume/download-resume/jobs For the complete command table, parameters, and benefit filtering principles, see the command reference; the source of truth for capabilities is boss schema (supports --format openai-tools / anthropic-tools to export tool definitions).

Collection and risk control Batch collection requires an additional installation: uv sync --extra crawl. It uses a separate <data-dir>/crawl/chrome-profile and will not take over the daily Chrome profile. By default, no Hook is injected; if you need to use a local script, you must explicitly provide both the Hook tier and a directory containing SHA256SUMS. crawl run executes sequentially and saves SQLite checkpoints and incremental JSON / CSV / XLSX artifacts; the number of requests, number of details, wall-clock time, and retries are all constrained by a fixed budget, and boss crawl stop can stop at the next safe point. Export and crawl results do not expose security_id, job ID, or recruiter fields by default; running boss clean --privacy deletes crawl state, budget, and exports. Fine-grained MCP crawl tools read or import an existing run_id; boss_wizard can start, resume, and stop tasks through a shared workflow. When a platform risk code or security page appears, stop and return the recovery command.

Configuration and data Configuration is located at ~/.boss-agent/config.json: operating mode (operating_mode=assisted|research), request interval, batch greeting interval, log level, CDP address, export directory, platform / role. All state is in ~/.boss-agent/: encrypted login state, search cache, candidate pool, local resume, AI configuration, and external model registration. Model weights do not enter the Python package; except for explicitly initiated API calls or local model downloads, data does not leave the local machine. Invariants: stdout is only the JSON envelope, stderr is only logs, exit 0/1, errors contain code/recoverable/recovery_action, and boss schema is the source of truth for capabilities. Dual-audience hint: hints.next_actions are follow-up commands for the Agent to execute, and hints.operator_actions are natural-language guidance for the human operator; under TTY, only the latter is rendered to stderr, the Agent should relay it to the operator.

Tech stack and migration Technology choices: Python ≥ 3.10 · Click · httpx · patchright / CDP (login, export, and the declared browser adapter) · cryptography (Fernet) · sqlite3 (WAL) · pytest (1600+ items). v3.0.0 migration: the Browser Bridge daemon, the Chrome extension, and the [bridge] install extra have been removed. Upgrading the CLI will not stop the old daemon, nor will it uninstall the browser extension; please manually stop the old daemon, disable or remove the old extension, and remove [bridge] from the install command. The default browser fallback chain is CDP → headless; if you want to reuse only an existing session, first log in manually on the official page of the local CDP browser and then run. This source does not create new pages, does not navigate, does not inject cookies, and does not launch a browser. The CDP debugging port is only for trusted local environments; do not expose it to the public internet or use it to bypass platform risk controls.

Applicable scenarios and limitations Suitable for scenarios such as job seekers' job search and benefits filtering, local candidate pool management and statistics, AI resume optimization and interview preparation, and recruiters' candidate processing. Limitations: the recruiter side only supports zhipin-recruiter; batch collection requires additional dependencies; the error envelope uniformly carries code + recoverable + recovery_action for programmatic recovery; boss doctor checks CDP reachability and summarizes browser_channel status; chat / chatmsg use httpx with local credentials under the default auto source, and only when --browser-source existing-browser is explicitly selected will they reuse an existing target page via CDP and not read the Cookie saved by the CLI; when existing browser candidates are exhausted, it returns BROWSER_SESSION_NOT_FOUND + boss doctor, while the ordinary not-logged-in path still returns AUTH_REQUIRED + boss login. When any source hits platform risk controls, stop the current workflow and save a checkpoint; the adapter must run in a bounded manner, be desensitized, be stoppable, and only after the risk state is liftedexplicitly resume. When using it, please comply with applicable laws, platform agreements, and privacy requirements, set clear input, quantity, timeout, and stop conditions for batch outreach, candidate personal data, and browser adaptation, and properly protect local credentials and export artifacts. Consequences arising from improper use are borne by the user and are unrelated to the project author. The project uses the MIT license.