|
| 1 | +# Kachilu Browser |
| 2 | + |
| 3 | +`kachilu-browser` is an anti-bot-aware browser automation CLI for AI agents such |
| 4 | +as Codex and Claude. |
| 5 | + |
| 6 | +<p align="center"> |
| 7 | + <img src="docs/reCAPTCHA.gif" alt="Kachilu Browser detecting a reCAPTCHA challenge" width="100%"> |
| 8 | +</p> |
| 9 | + |
| 10 | +> CAPTCHA in the way? The LLM detects it through the SKILL and hands off |
| 11 | +> completion automatically. Nothing complicated. |
| 12 | +
|
| 13 | +Human-like interaction is the default. When reCAPTCHA v2/v3 or Cloudflare |
| 14 | +Turnstile appears, `kachilu-browser` detects the challenge and routes completion |
| 15 | +through the local CLI/browser flow. |
| 16 | + |
| 17 | +WSL2 is first-class: agents running in Linux can control the Windows-side |
| 18 | +browser profile you actually use, instead of a separate WSL-only browser. |
| 19 | + |
| 20 | +Free to use. Local by design. No hosted relay, no telemetry, no external control |
| 21 | +plane between the agent and your browser. |
| 22 | + |
| 23 | +## Install |
| 24 | + |
| 25 | +```bash |
| 26 | +npm install -g kachilu-browser |
| 27 | +kachilu-browser onboard |
| 28 | +``` |
| 29 | + |
| 30 | +When this page appears, tick the checkbox so the agent can connect to your browser: |
| 31 | + |
| 32 | + |
| 33 | + |
| 34 | +## OpenClaw |
| 35 | + |
| 36 | +```bash |
| 37 | +openclaw plugins install kachilu-browser |
| 38 | +openclaw gateway restart |
| 39 | +``` |
| 40 | + |
| 41 | +OpenClaw uses the same npm package bundle, so no separate package name or extra |
| 42 | +install script is needed. |
| 43 | + |
| 44 | +## Onboarding targets |
| 45 | + |
| 46 | +- If `--target` is omitted in an interactive terminal, `kachilu-browser onboard` prompts for the host target |
| 47 | +- In non-interactive runs, pass `--target codex`, `--target claudecode`, or `--target claudedesktop` |
| 48 | +- For Codex and Claude Code on WSL2, `onboard` persists `KACHILU_BROWSER_AUTO_CONNECT_TARGET=windows` and auto-detected `KACHILU_BROWSER_WINDOWS_LOCALAPPDATA` unless you override them |
| 49 | +- When targeting Windows browsers from WSL2, `onboard` also ensures `%USERPROFILE%\.wslconfig` has `[wsl2] networkingMode=mirrored` and reports when `wsl --shutdown` is required |
| 50 | +- `codex`: writes `~/.codex/config.toml` and links `~/.codex/skills/kachilu-browser` |
| 51 | +- `claudecode`: writes `~/.claude.json` and links `~/.claude/skills/kachilu-browser` |
| 52 | +- `claudedesktop`: writes the Claude Desktop local MCP config. Use `claude-desktop` as an equivalent alias. |
| 53 | +- Claude Desktop Skills are distributed as `kachilu-browser-skill.zip` on GitHub Releases and must be uploaded through Claude Desktop's Skills UI. |
| 54 | + |
| 55 | +## MCP control plane |
| 56 | + |
| 57 | +Agents should keep using the MCP prepare/exec workflow whenever the tools are available, including after context compaction or resume. This preserves the host-managed session, profile, and WSL2 Windows-browser target from the MCP env block. |
| 58 | + |
| 59 | +Raw `kachilu-browser` shell commands are a fallback for environments without MCP, explicit CLI requests, or intentional local WSL/Linux browser work. On WSL2, a raw shell command can miss `KACHILU_BROWSER_AUTO_CONNECT_TARGET=windows` and launch or control a WSL2-local browser instead of the intended Windows browser. |
| 60 | + |
| 61 | +Successful prepare and exec responses include `controlPlane: "mcp"` and `followUpTool: "kachilu_browser_exec"` so agents can preserve the MCP route across context compaction and long-running resumes. |
| 62 | + |
| 63 | +## Release model |
| 64 | + |
| 65 | +- Native binaries are built from the private source repo. |
| 66 | +- The npm package bundles available native binaries so `npm install -g kachilu-browser` works without exposing the private source tree. |
| 67 | +- The source repo must provide `KACHILU_BROWSER_RELEASE_TOKEN` so it can create this repo's GitHub Release and push synced tags. |
| 68 | +- This public repo publishes the npm package via npm Trusted Publishing after the package already exists on npm. |
| 69 | +- The very first npm publish for `kachilu-browser` must be done manually with `npm publish --access public`. |
| 70 | +- If the package was unpublished, npm blocks republishing the same package name for 24 hours. |
| 71 | +- This repo's publish workflow also refuses to publish if the package does not yet exist on npm. |
| 72 | +- The npm package downloads matching native binaries from GitHub Releases only when the current platform binary was not bundled in the package. |
| 73 | + |
| 74 | +## Commands |
| 75 | + |
| 76 | +```bash |
| 77 | +kachilu-browser --help |
| 78 | +kachilu-browser onboard --help |
| 79 | +node scripts/mcp-server.mjs |
| 80 | +``` |
0 commit comments