# boss-agent-cli
**Repository Path**: oneconding/boss-agent-cli
## Basic Information
- **Project Name**: boss-agent-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-15
- **Last Updated**: 2026-11-15
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README

# boss-agent-cli
*🤖 A recruiting-platform CLI for people and AI agents — terminal wizard · welfare filtering · dual-role workflows · JSON envelopes.*
[](https://python.org)
[](LICENSE)
[](https://github.com/can4hou6joeng4/boss-agent-cli/releases)
[](https://pypi.org/project/boss-agent-cli/)
[](https://github.com/can4hou6joeng4/boss-agent-cli/pulls)
[Getting Started](docs/getting-started.en.md) · [Architecture](docs/architecture.en.md) · [Agent Integration](#-agent-integration) · [Commands](#-commands) · [Troubleshooting](docs/troubleshooting.en.md) · [Roadmap](ROADMAP.en.md) · [中文](README.md) | **English**
**[Watch the 48-second keynote](demo/showcase/boss-agent-cli-showcase.mp4)** · [interactive edition](https://can4hou6joeng4.github.io/boss-agent-cli/keynote-animation/) · [terminal demo](demo/demo-en.gif) · welfare filtering · dual-role workflows · agent integration
## 🧭 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, schema_version, command, data, pagination, error, hints}` seven-key envelope, `boss schema` is the capability source of truth, and an **MCP server with 79 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/location/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
```bash
# Install (uv recommended; the browser core is only for user-triggered login / local export)
uv tool install boss-agent-cli
boss doctor # prints a runnable browser-kernel install command when missing
# 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 # view detail
boss shortlist add --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
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](docs/getting-started.en.md).
## 🎭 Roles & Platforms
| Platform | Candidate | Recruiter | Status |
|----------|:--:|:--:|--------|
| BOSS Zhipin (`zhipin`) | ✅ | ✅ | default |
```bash
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](docs/platform-abstraction.en.md).
## 🤖 Agent Integration
Start here: [Agent Quickstart](docs/agent-quickstart.en.md) · [Capability Matrix](docs/capability-matrix.en.md) · [Host Examples](docs/agent-hosts.en.md)
```json
// Option 1: MCP (recommended) — Claude Desktop / Cursor and other MCP hosts; MCP server with 79 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](docs/integrations/docker.md).
OpenCode can use the checked-in example directly:
```bash
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.
```bash
# Option 2: subprocess — let the Agent read the self-description, then parse stdout JSON
boss schema
```
```python
# 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 + 15 first-level recruiter subcommands, grouped by workflow:
- **Auth**: `login` · `logout` · `status` · `doctor`
- **Discover**: `search` · `recommend` · `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` · `chatmsg` · `chat-summary` · `mark` · `interviews` · `pipeline` · `digest` · `follow-up`
- **Recruiter**: `hr whoami/applications/candidates/recommendations/greet/location/resume/chat/chatmsg/last-messages/reply/request-resume/accept-resume/download-resume/jobs`
Full command tables, parameters, and welfare-matching internals: **[Command Reference](docs/commands.en.md)**. The capability source of truth is `boss schema` (with `--format openai-tools` / `anthropic-tools` / `mcp-tools` exports).
Bulk crawl requires `pip install "boss-agent-cli[crawl]"` (or `uv tool install "boss-agent-cli[crawl]"`; `uv sync --extra crawl` inside a source checkout). It uses its own `/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`:
```powershell
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
boss crawl stop
boss agent crawl --run-id --resume
```
`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
```bash
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:
```bash
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](docs/troubleshooting.en.md)**. For Cookie / CDP / patchright / request-rate / drift issues, read [Platform Risk Boundaries](docs/platform-risk.en.md) first.
## ⚙️ Configuration
```bash
boss config list # view all settings
boss config set log_level debug # set the log level
boss config reset log_level # restore one setting to its default
```
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](CONTRIBUTING.en.md) and [Getting Started](docs/getting-started.en.md). TL;DR: fork → `feat/xxx` branch → write tests → `python scripts/quality_baseline.py` (on Chinese Windows, set `$env:PYTHONUTF8='1'` first) → PR. Reproducible offline MCP evals live in [`evals/README.md`](evals/README.md). By participating you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
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 ⭐](https://github.com/can4hou6joeng4/boss-agent-cli), or sharing it with someone who is job hunting.
- Hit a problem or have an idea? Open an [Issue](https://github.com/can4hou6joeng4/boss-agent-cli/issues) — or go straight to a PR. For security vulnerabilities, report privately via [SECURITY.md](SECURITY.md) — do not open a public issue.
- Need help? Start with [Getting Support](SUPPORT.en.md): docs entry points, Discussions, Issues, and private security reporting.
- Curious about the rest of the fleet? Drop anchor at the home port [bobochang.cn](https://bobochang.cn) 🧭.
This project benefits from [geekgeekrun](https://github.com/geekgeekrun/geekgeekrun) · [boss-cli](https://github.com/jackwener/boss-cli) · [opencli](https://github.com/jackwener/opencli) — thanks to all of them.
## ⭐ Star History
A static SVG generated locally with [mystarhistory](https://github.com/carsteneu/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](LICENSE) © [can4hou6joeng4](https://github.com/can4hou6joeng4) · [LINUX DO](https://linux.do/)