buttercup.sh is open source: an agent harness that lives in your browser

Meet the little machine

Coding agents such as Claude Code, Codex, Cursor, and Antigravity all run a small loop: send the model a conversation and a list of tools, run the tools it requests, then return the results. Everything else supports that loop.

buttercup.sh runs the loop in a browser tab. The program is static HTML, CSS, and JavaScript loaded with classic <script> tags. It has no modules or dependencies and needs no bundler. Run it with:

git clone https://github.com/stephenlb/buttercup.sh && open buttercup.sh/index.html

The page you open is the program. There is no production build hidden elsewhere. The loop is in js/agent.js, the tools are in js/tools.js, and the wire protocols are in js/llm.js. Those files contain the whole harness.

A whole toolbox in one tab

On each turn, the model can read, search, write, move, and delete files. It can scaffold projects, run JavaScript, spawn sub-agents, fetch pages and documentation, preview its work, and export a ZIP:

read  list  glob  grep  todo  set_mode  export_zip  playground_url
write  edit  delete  move  scaffold  compile
run_js  run_agent  preview  screenshot  navigate
http_get  npm_info  npm_file  framework_docs

The TOOLS panel can withhold any tool, and small-context WebLLM models receive a reduced core set.

A virtual filesystem stores your files in localStorage. A 25-step undo stack saves the conversation and files in the same snapshot, so /undo rewinds both. You can drag in files or folders and paste screenshots. Before sending screenshots, Buttercup scales them down. It also queues requests, compacts long sessions, and resolves preview imports with a hand-written ES-module linker.

Code the agent writes runs in a sandbox="allow-scripts" iframe on an opaque origin, so it cannot reach the page, the DOM, or your keys. allow-same-origin is never granted.

Take it with you

The tab calls model endpoints over HTTPS, so it works in laptop and phone browsers. On a narrow screen, the interface becomes one column: transcript and prompt first, then the file rack, diffs, and settings.

Open buttercup.sh on your phone, paste a key, and use it on the train. The files stay in that browser's storage until you export a ZIP.

Free, with no account

The program is free. It has no account system.

Your tab connects to the model you choose. Buttercup has no proxy, telemetry, analytics, or update check. Your keys, conversation, and files stay in your browser's localStorage. Model requests go to the vendor you select. You can verify that in your browser's network tab.

The code is on GitHub. A fork will keep working if buttercup.sh goes offline.

Prefer local? Nothing has to leave your machine

Connect the harness to Ollama or vLLM to keep every request on your machine. Buttercup hides the API-key field for both providers and sends no Authorization header. Each server needs CORS permission to accept calls from the tab:

OLLAMA_ORIGINS='https://buttercup.sh' ollama serve
vllm serve <model> --allowed-origins '["https://buttercup.sh"]'

If you serve the harness yourself, replace the origin with your own. Chrome and Firefox exempt http://localhost from mixed-content blocking on an HTTPS page; Safari does not, so on Safari serve the harness over local HTTP (python3 -m http.server).

The harness also supports eight cloud and local providers:

Buttercup speaks three wire formats: Anthropic Messages, Google generateContent, and OpenAI-style /chat/completions, which six providers share. A base url field appears for chat-completions vendors. Any gateway that accepts that format works without a code change.

Keys live in your browser's localStorage. Anything that can run script on that origin can read them. Use a scoped, revocable key.

Why it is worth opening up

Most agent harnesses tuck a small loop inside a large application. Buttercup leaves the loop where you can read it. If you know JavaScript, you can inspect the code in an afternoon, change its prompts, add a tool, or connect it to a model on your own hardware.

You choose the model, keep control of your keys, and can change every part of the program beneath the old-terminal interface.

open the harness and make it yours