---
name: omnibot
description: Use when AI agents need to read, inspect, operate, navigate, debug, or verify browser state through the omnibot CLI and connected Chromium extension.
compatibility: Requires omnibot v2 CLI daemon and the omnibot Chromium extension connected to 127.0.0.1:18765.
allowed-tools: Bash
metadata:
  author: omnibot
  version: "2.1.0"
---

# Omnibot

Omnibot is Browser Infrastructure for AI Agents.

It connects Hermes, Claude Code, Codex, OpenCode, and other agent systems to a real Chromium browser through the local omnibot daemon and CLI.

This skill is an execution specification for agents. It is not a human command manual.

## When to Use

- Use Omnibot when browser runtime state matters: login, cookies, storage, client-side rendering, extensions, or visible user tabs.
- Use Omnibot when an agent must read rendered pages, click controls, fill forms, upload files, navigate, extract content, or collect evidence.
- Do not use Omnibot when static files or plain HTTP content already answer the task.

## Core Rules

- Reliability > Convenience.
- Explicit State > Implicit State.
- Pattern > Command.
- Observe -> Act -> Verify.
- Fallback is allowed, but never first.
- Do not use `execute-js` first.
- Prefer semantic locators and `snapshot -i` refs before selectors.
- Prefer condition-based `wait` over shell sleep.
- Parse JSON output from commands that return JSON.
- Do not claim success without verification evidence.

## Session + Tab Double Lock

Every page-state workflow must use both controls:

- `OMNIBOT_SESSION_TOKEN=<workflow-name>` for workflow isolation.
- `--tab-id <TAB_ID>` for page targeting.

They are not substitutes. Session controls which workflow owns state. Tab ID controls which page receives the command.

Do not rely on default tab, active tab, current tab, or prior targeting state. Every page command requires explicit `--tab-id`.

Use the same token inside one workflow. Use different tokens for independent workflows.

Standard form:

```bash
OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot click --tab-id <TAB_ID> @e4
OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
```

`@eN` refs are tab-scoped. never reuse `@eN` refs across tabs.

The agent dispatch pattern is token + tab-id:

1. Set a stable `OMNIBOT_SESSION_TOKEN`.
2. Discover or create the target tab.
3. Save the returned tab id.
4. Pass `--tab-id <TAB_ID>` on every command that touches page state.
5. Run observe -> act -> verify on that same tab.

Examples of tab-locked page-state commands:

```bash
OMNIBOT_SESSION_TOKEN=checkout omnibot get value "input[name=email]" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot find placeholder "Search" --action type --action-value "omnibot" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot dom dblclick n1 --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot clipboard read --tab-id <TAB_ID>
```

## Observe -> Act -> Verify

All page operations must follow this loop:

1. Observe the current page state.
2. Act once using the highest reliable pattern available.
3. Verify the expected state change.

Click example:

```bash
OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=research omnibot click --tab-id <TAB_ID> @e4
OMNIBOT_SESSION_TOKEN=research omnibot snapshot -i --tab-id <TAB_ID>
```

Read/verify example:

```bash
OMNIBOT_SESSION_TOKEN=checkout omnibot is enabled "button[type=submit]" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot find role button --name "Submit" --action click --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot wait --url "/dashboard" --tab-id <TAB_ID>
OMNIBOT_SESSION_TOKEN=checkout omnibot get url --tab-id <TAB_ID>
```

If verification fails, do not repeat blindly. Re-observe, choose the next fallback tier, and verify again.

## Pattern > Command

Start from the task, not the command name. Use operation patterns for read, click, fill, select/check, navigation, wait, extraction, upload, and batch.

Use fallback tiers only after standard patterns fail. Collect evidence separately from fallback execution. The command reference is only a lookup table; it must not decide behavior.

## Read vs Snapshot Routing

Choose by intent before choosing by command name:

| Intent | Prefer | Why |
| --- | --- | --- |
| Summarize or extract page content, article text, search results, feeds, or long/lazy pages | `read` | Returns clean text/Markdown for agent reasoning. |
| Quickly observe current visible UI structure before deciding what to do next | `snapshot -i` | Returns actionable refs and page structure for routing. |
| Find buttons, links, inputs, or refs for a later action | `find` or `snapshot -i` | Produces actionable targets; `read` does not. |
| Verify one concrete condition | `get`, `is`, or `wait` | Narrow evidence is more reliable than dumping a page. |

Do not use `read` as the first step for click/fill workflows unless the user explicitly asked for page content first.

## Quick Routing

| Need | Read |
| --- | --- |
| Runtime check | `references/runtime-and-status.md` |
| Reading pages | `references/operation-patterns.md#read` |
| Clicking | `references/operation-patterns.md#click` |
| Filling forms | `references/operation-patterns.md#fill` |
| Select / check | `references/operation-patterns.md#select--check` |
| Navigation | `references/operation-patterns.md#navigation` |
| Waiting | `references/operation-patterns.md#wait` |
| Extraction | `references/operation-patterns.md#extraction` |
| Upload | `references/operation-patterns.md#upload` |
| Batch | `references/operation-patterns.md#batch` |
| Fallback | `references/fallback-operations.md` |
| Tabs and sessions | `references/session-and-tabs.md` |
| Debug evidence | `references/debugging-and-evidence.md` |
| Commands | `references/command-reference.md` |
| Anti-patterns | `references/anti-patterns.md` |

## Runtime First

Before troubleshooting browser behavior, check runtime state:

```bash
omnibot doctor
omnibot tabs
omnibot visibility status
omnibot browser current
omnibot license status
```

If the extension is not connected, open Chrome or Edge with the omnibot extension loaded and keep an HTTP/HTTPS tab open.

## Fallback Discipline

Fallback tiers are for completing operations after better patterns fail. They are not debugging shortcuts.

Tier order:

1. Semantic `find`.
2. `snapshot -i` refs.
3. Selectors.
4. `dom` fallback.
5. `mouse` fallback.
6. `execute-js` fallback.
7. Raw `cdp` fallback.

When entering a lower tier, state why the higher tier failed. After any fallback action, verify with `snapshot`, `get`, `is`, `wait`, or equivalent evidence.

## Debug Evidence

Debugging is for evidence. Fallback is for completing operations.

Use screenshots, annotated screenshots, console logs, network logs, trace, record/replay, and CDP inspection to explain failures or prove state. Do not treat `execute-js` as ordinary debug output.

## Absolute Prohibitions

- Missing `OMNIBOT_SESSION_TOKEN` or missing `--tab-id` on page-state commands.
- Acting without verify or claiming success without evidence.
- Using `execute-js` first, raw CSS before semantic find, `@eN` across tabs, implicit tab targeting, or shell sleep instead of `omnibot wait`.
- Using removed commands: `switch-tab`, `focus-tab`, `tab switch`. These are no longer available.
- Using `tabs[0]` or the first tab as a target. The first tab is often a user tab or transport tab.
- Closing user tabs discovered during cleanup. Only close tabs created by the current workflow.

See `references/anti-patterns.md` before using shortcuts.
