# 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 logo # boss-agent-cli *🤖 A recruiting-platform CLI for people and AI agents — terminal wizard · welfare filtering · dual-role workflows · JSON envelopes.* [![Python](https://img.shields.io/badge/Python-≥3.11-3776AB?logo=python&logoColor=white&style=flat-square)](https://python.org) [![License](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE) [![GitHub Release](https://img.shields.io/github/v/release/can4hou6joeng4/boss-agent-cli?style=flat-square)](https://github.com/can4hou6joeng4/boss-agent-cli/releases) [![PyPI Downloads](https://img.shields.io/pypi/dm/boss-agent-cli?style=flat-square)](https://pypi.org/project/boss-agent-cli/) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](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** boss-agent-cli Aurora Keynote: welfare filtering, dual-role workflows and agent integration **[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! ❤️ contributors ## ❤️ 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 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/)