Kachilu Browser

kachilu-browser is an anti-bot-aware browser automation CLI for AI agents such as Codex and Claude.

CAPTCHA in the way? The LLM detects it through the SKILL and hands off completion automatically. Nothing complicated.

Human-like interaction is the default. When reCAPTCHA v2/v3 or Cloudflare Turnstile appears, kachilu-browser detects the challenge and routes completion through the local CLI/browser flow.

WSL2 is first-class: agents running in Linux can control the Windows-side browser profile you actually use, instead of a separate WSL-only browser.

Free to use. Local by design. No hosted relay, no telemetry, no external control plane between the agent and your browser.

Install

npm install -g kachilu-browser
kachilu-browser onboard

When this page appears, tick the checkbox so the agent can connect to your browser:

OpenClaw

openclaw plugins install kachilu-browser
openclaw gateway restart

OpenClaw uses the same npm package bundle, so no separate package name or extra install script is needed.

Onboarding targets

• If --target is omitted in an interactive terminal, kachilu-browser onboard prompts for the host target
• In non-interactive runs, pass --target codex, --target claudecode, or --target claudedesktop
• Use --skill-only or --no-mcp for desktop hosts that already provide a browser session and only need the Codex or Claude Code skill
• For Codex and Claude Code on WSL2, full MCP onboarding persists KACHILU_BROWSER_AUTO_CONNECT_TARGET=windows and auto-detected KACHILU_BROWSER_WINDOWS_LOCALAPPDATA unless you override them
• When targeting Windows browsers from WSL2 through MCP, onboard also ensures %USERPROFILE%\.wslconfig has [wsl2] networkingMode=mirrored and reports when wsl --shutdown is required
• codex: writes ~/.codex/config.toml and links ~/.codex/skills/kachilu-browser
• claudecode: writes ~/.claude.json and links ~/.claude/skills/kachilu-browser
• claudedesktop: writes the Claude Desktop local MCP config. Use claude-desktop as an equivalent alias.
• Claude Desktop Skills are distributed as kachilu-browser-skill.zip on GitHub Releases and must be uploaded through Claude Desktop's Skills UI.

kachilu-browser onboard --target codex --codex-home <desktop-codex-home> --skill-only

MCP control plane

Agents should keep using a host-provided browser session when one is explicit. Otherwise, they should keep using the MCP prepare/exec workflow whenever the tools are available, including after context compaction or resume. For MCP-managed sessions, this preserves the session, profile, and WSL2 Windows-browser target from the MCP env block.

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.

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.

Release model

• Native binaries are built from the private source repo.
• The npm package bundles available native binaries so npm install -g kachilu-browser works without exposing the private source tree.
• The source repo must provide KACHILU_BROWSER_RELEASE_TOKEN so it can create this repo's GitHub Release and push synced tags.
• This public repo publishes the npm package via npm Trusted Publishing after the package already exists on npm.
• The very first npm publish for kachilu-browser must be done manually with npm publish --access public.
• If the package was unpublished, npm blocks republishing the same package name for 24 hours.
• This repo's publish workflow also refuses to publish if the package does not yet exist on npm.
• The npm package downloads matching native binaries from GitHub Releases only when the current platform binary was not bundled in the package.

Commands

kachilu-browser --help
kachilu-browser onboard --help
node scripts/mcp-server.mjs