jelly

<div id="top"></div> <div align="center"> <img src="./assets/full-logo.png" alt="Jelly" width="760">

Browser instrumentation for agents.

✨ Quickstart　•　⭐ Architecture　•　⚡ MCP　•　💡 Documentation　•　🍯 Tool Index

📒 Visit the project website

</div>

1. About

Jelly is a small Rust toolkit that gives AI agents a practical way to observe and control a real Chromium browser.

It turns browser operations such as reading pages, finding interactive elements, clicking, typing, navigating, switching tabs, uploading files, inspecting network traffic, and taking screenshots into reusable primitives that agents can discover and compose.

You do not need to know Chrome DevTools Protocol to use it. Jelly's MCP server now defaults to the small-surface Agent API: browser-schema discovers semantic operations, browser-call executes ordered semantic batches, and browser-events handles retained CDP notifications. The expanded individual-tool API is available as large-surface, and raw CDP stays separately opt-in.

[!CAUTION] Jelly controls a real browser and can perform real actions on websites. Review routines before running them against accounts or systems you care about.

<p align="right">_{<a href="#top">⭐ Back to top</a>}</p>

2. Quickstart

Interactive setup:

git clone https://github.com/FabioFlorey/jelly.git
cd jelly
./quickstart.sh

The wizard checks dependencies, configures OAuth + hosting, and can install/start Jelly. See MCP for hosting modes and advanced setup.

Use ./quickstart.sh --dry-run to preview setup, or ./quickstart.sh --check for prerequisites only.

Or build the tools directly:

cargo build --bins

Open a browser and inspect a page:

cargo run --quiet --bin agent-run -- \
  open-browser https://example.com

cargo run --quiet --bin agent-run -- read-page
cargo run --quiet --bin agent-run -- snapshot-interactive

Act on a discovered element using the ref returned by snapshot-interactive:

cargo run --quiet --bin agent-run -- click '<ref>'

Runtime refs are document-scoped tokens such as @eabc123-7; legacy rollback mode uses numeric refs such as @e7.

Close the browser:

cargo run --quiet --bin agent-run -- close-browser

Discover tools without loading the full catalog:

cargo run --quiet --bin agent-discover -- capabilities
cargo run --quiet --bin agent-discover -- search "find form inputs"
cargo run --quiet --bin agent-discover -- schema type-text

<p align="right">_{<a href="#top">⭐ Back to top</a>}</p>

3. Documentation

<div align="center">

| Document | Description | | :--- | :--- | | 📒 Documentation Index | Main entry point for the documentation | | ⚠️ Requirements | What must be installed before running Jelly | | 💡 Glossary | Definitions for technical and project-specific terminology | | ⭐ Architecture | Browser session, primitives, registry, and execution model | | 🔑 Tool Discovery | Capability discovery, search, and schema loading | | 🔆 Routines | Guarded workflow graphs, branching, loops, and HITL continuation | | 🍯 Reliability | Verification, typed failures, artifacts, timeouts, and cleanup | | ⚙️ Configuration | Versioned technical configuration, secrets/deployment environment, and runtime roots | | 📂 Runtime Layout | Runtime state, build output, logs, screenshots, and cleanup | | 🧈 Development | Project conventions, tests, and contribution rules | | 🧪 Test Index | Test-suite layout, coverage groups, batches, and executable catalog | | ⚡ MCP Server | Small-surface Agent API, large-surface mode, authentication, tool mapping, and deployment boundary | | 🍯 Tool Index | Generated reference for browser primitives and system tools | | 🌟 Changelog | Development history |

</div> <p align="right">_{<a href="#top">⭐ Back to top</a>}</p>

4. Live demo

<div align="center"> <a href="https://fabioflorey.github.io/jelly/"> <img src="./assets/jelly-demo.gif" alt="Jelly controlling a real Chromium browser" width="880"> </a>

_{<strong>Jelly documenting Jelly.</strong> This video was generated by Jelly itself from a real Chromium session. After each browser action, Jelly waits for the page to settle, captures the resulting state, labels what happened, and assembles the steps into this self-documenting trace.}

</div> <p align="right">_{<a href="#top">⭐ Back to top</a>}</p>

5. Status

Jelly is under active development. Interfaces may change while the execution, discovery, and routine layers settle.

Jelly is currently distributed under a proprietary All Rights Reserved license. See LICENSE for the applicable terms.

Project contact: jelly@fabioflorey.com.

<p align="right">_{<a href="#top">⭐ Back to top</a>}</p>