A controlled browser runtime for automation, agents, and programmable web execution. Lightweight, CDP-native, MCP-ready — programmable web infrastructure without the Chromium monolith.
// RUNTIME
Koko treats the browser as a controlled execution runtime — observable, embeddable, and automation-native. Built for AI agents, crawling, and scalable web interaction.
GET /api
────────►
◄────────
{ data }Connect over Chrome DevTools Protocol — use the Koko SDK, existing CDP clients, or raw WebSocket automation without Chromium internals.
┌───────┐ │ ◉ ◎ ○ │ │ ◎ ◉ ◎ │ │ ○ ◎ ◉ │ └───────┘
Native Model Context Protocol tools: goto, markdown, links, evaluate, and semantic_tree for token-efficient agent browsing.
┌─┐ ┌─┐
│A├──►│B│
└─┘ └┬┘
┌▼┐
│C│
└─┘Choose the navigation contract that fits the page — DOMContentLoaded, load, domstable, networkidle, or done — with explicit timeouts and lifecycle state.
╔═══╗ ║ ◈ ║ ┌╨───╨┐ │░░░░░│ └─────┘
Inspect network, DOM, runtime, and browser signals as a live journey. Use timelines and structured events to explain slow or incomplete pages.
│ ▄ │▁ ▄ █ ▄ │█ █ █ █ └────────
Export the page you actually observed as HTML, Markdown, or JSON — including progressive results for long-running crawls and SPA navigation.
.--.
/ \
| ( ) |
\ /
'--'Reuse browser profiles, cookies, headers, storage state, and fingerprint settings across runs without coupling your workflow to a desktop browser.
// HOW IT WORKS
// ARCHITECTURE
Koko separates browser execution into explicit runtime layers — keeping engine internals isolated, protocols modular, and public APIs stable for embeddable automation.
⚡
Low-level control over lifecycle, memory, and protocol behavior
🔗
Automation scripts and AI agents connect through standard protocols
📦
Multi-session model for crawling, testing, and cloud browser runtimes
DOM, parser, V8 bindings, Web APIs
Lifecycle, network, storage, telemetry
CDP and MCP implementations
CLI and server entry points
Koko SDK and CDP surface
koko-fetch, koko-sdk client
// BENCHMARKS
// PROTOCOLS & TOOLING
Koko speaks the protocols automation systems already use — CDP for scripts, MCP for agents, and a first-party SDK for programmatic control.
┌─┐ │C│ └─┘
Protocol
╔═╗ ║M║ ╚═╝
Agents
┌▶┐ └─┘
Client
[TS] [TS]
Language
◈◈ ◈◈
Engine
≋≋ ≋≋
JS runtime
{f}
---CLI
▲ ─
Tooling
Token-efficient page state for LLM workflows — markdown, semantic trees, structured data, and stable backendNodeId handles.
SDK documentation// ENGINEERING
Reliable automation depends on browser lifecycle behavior. Koko engineers correctness into navigation, realms, and teardown — not as an afterthought.
╔═══╗ ║ ◈ ║ ╚═══╝
Frames, workers, and execution contexts stay isolated — no cross-realm leaks in automation
┌───┐ │ ✓ │ └───┘
Deterministic domcontentloaded and lifecycle events for anti-flake scripts
╭───╮ │ ★ │ ╰───╯
Correct proxy behavior across frames — critical for protocol integrations
[===] [===]
Clean session close without zombie processes or leaked handles
◉─◉─◉ │ │ │
Predictable event ordering and microtask scheduling for stable automation
▪ ▪ ▪ ▪ ▪ ▪
Regression suites under code-check/lifecycle for continuous correctness
Under active development — automation reliability, CDP consistency, and AI-agent integration
📋
Koko is AGPL-3.0 licensed. Benchmarks, lifecycle tests, and engineering notes are published in-repo.Read engineering notes →
// SDK
Connect over CDP, automate pages, and extract agent-friendly state — without pulling in a full Chromium stack.
Browser, Context, Page, Locator, and wait strategies for scripts and test suites.
markdown(), semanticTree(), detectForms(), searchGoogle(), and backendNodeId handles.
Lightweight WebSocket CDP client — no third-party browser driver stack.
koko-fetch and CDP probes for quick extraction and regression testing.
1"text-primary">import { Browser } "text-primary">from "koko-sdk";23"text-primary">const browser = "text-primary">await Browser.connect(4 "http://127.0.0.1:9222"5);6"text-primary">const page = "text-primary">await browser.newPage();// DEV STORY
Real debugging stories — right or wrong at the time. Each published once from knowledge/.
For months, Koko Google Search behaved like a fingerprint problem: CreepJS sections were green, wire headers were tuned, encode was patched — yet the same query on the same IP still returned a 91 KB bootstrap shell instead of Chrome’s 270–600 KB SERP on hop 1. The breakthrough was not another JS s
The Koko microbench harness—, shared , HTML fixtures in , and —was accidentally deleted in commit during a cleanup and restored from parent on 20260629. A fresh baseline on git with shows dramatic improvement versus the last published run (20260623, git ). On microbench fixtures Koko now beats P
Between 20260629 and 20260630, Koko shipped endtoend verification and two reference workflows for : 1. — a bounded, CIfriendly probe of Kokospecific APIs over the LP CDP domain, plus session persistence and actions. 2. — Workflow B: multiworker Wikipedia crawl shaped like the benchmark harness (
Koko is under active development — focused on automation reliability, lifecycle correctness, and AI-agent integration. Clone the repo and run your first session today.
AGPL-3.0 · Zig + TypeScript · CDP + MCP