kata-code / rules

---
description: kata code browser rules
alwaysApply: true
---
<!-- begin integrated browser rules -->
## Integrated browser (Kata Code)

NOTE: this section only applies when running in the Kata Code environment.

The integrated browser is the Kata Code preview browser. Agents reach it through the `t3-code` MCP server, whose tools are named `mcp__t3-code__preview_*`. The tools are deferred. Load them with ToolSearch before the first call, for example `select:mcp__t3-code__preview_open,mcp__t3-code__preview_navigate,mcp__t3-code__preview_snapshot,mcp__t3-code__preview_click,mcp__t3-code__preview_evaluate,mcp__t3-code__preview_recording_start,mcp__t3-code__preview_recording_stop`.

- `preview_open` opens a tab and returns a `tabId`. Pass `reuseExistingTab: false` for a second tab. Pass `tabId` to every later call.
- `preview_navigate`, `preview_click`, `preview_press`, `preview_type`, `preview_wait_for`, `preview_evaluate`, `preview_resize`, and `preview_scroll` drive the page.
- `preview_snapshot` returns page text, the accessibility tree, and a screenshot. Pass `includeImage: false` and `save: true`, then read `screenshotPath` from the result. Full snapshots are often too large to read inline. Use `preview_evaluate` for targeted reads.
- `preview_recording_start` and `preview_recording_stop` record one tab. The stop call returns an MP4 path under `~/.katacode/userdata/attachments/`. Convert it with ffmpeg if a script expects another format.
- `preview_status` reports whether a tab is still usable.

### Reaching a local server

The browser runs on the Kata Code client, which can be a different machine from the agent's host. It cannot load `localhost` or `127.0.0.1` on the agent's host, and the `environment-port` navigation target currently fails. Reach local servers over Tailscale:

1. Get the host's Tailscale address with `tailscale ip -4`. Do not hardcode it.
2. Bind the server the browser loads to that address, for example `vite --host "$(tailscale ip -4)" --port <port>`. Do not bind to `0.0.0.0`.
3. Open `http://<tailscale-ip>:<port>` in the integrated browser.
4. If the app checks the `Origin` or `Host` header, add `http://<tailscale-ip>:<port>` to its allowed origins or hosts for the run. Keep backend services the page reaches through the dev server's proxy bound to `127.0.0.1`.
5. Stop the Tailscale-bound server when the run ends.

### Known limits

- `about:blank` is refused. To leave a page, navigate to a neutral public URL.
- Playwright role locators may not match canvas elements. Get the element's position with `preview_evaluate` and click with `x` and `y`.
- The client can disconnect mid-run and lose a recording in progress. Keep each recording to one action and stop it right after. If `preview_status` reports `available: false`, open a new tab and repeat the step.
<!-- end integrated browser rules -->