GitHub - kachilu-inc/kachilu-browser

3 min read Original article ↗

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

Kachilu Browser detecting a reCAPTCHA challenge

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:

Remote debugging permission checkbox

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
  • 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
  • When targeting Windows browsers from WSL2, 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.

MCP control plane

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.

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