buttercup.sh

come build something curious — lessons · github · feedback · blocks.ai ·

NOT READY 
 ┌────────────────────────────────────────────────┐
 │  B U T T E R C U P                             │
 │  a friendly agent lesson every week            │
 └────────────────────────────────────────────────┘

Welcome to buttercup.sh. This is a free, hands-on place to learn how AI agents work by building one right here in the page. Each lesson adds a capability, from a first completion call to tools, browser control, vision, and evals. You can begin anywhere, and every past lesson is waiting in the archive.

You do not need to sign up. When you’re ready, open , choose a provider, and paste an API key. Your browser keeps the key in localStorage and sends requests directly to the provider.

A lovely first prompt is “scaffold a blocks.ai research agent, then run it”. The agent's files will appear in the . If you wander down an interesting wrong path, /undo rolls back the latest file and conversation changes. /help is always nearby.

workspace /

Drop text files or a folder anywhere on the page and they’ll join your workspace. /undo removes the last import.

  • empty workspace

tool definitions

Every turn includes the enabled tool definitions. The tools are JavaScript functions in js/tools.js and run in your browser.

    agent preview

    sandboxed iframe

    Your preview will appear here. preview opens a workspace file. run_agent executes it. The model can take screenshots or use navigate to interact with the page. SEND TO MODEL attaches the current view to your next prompt. All preview actions run inside the sandboxed frame.

    completion backend

    provider
    harness

    compile turns JSX, Vue, Svelte, Sass, TypeScript, Python, and more than 80 other formats into a page you can preview and photograph. It runs in the browser and loads the SDK from a CDN and the playground from livecodes.io. Before running the SDK, the harness verifies its pinned version and SHA-256 hash. Disable this option to block those third-party requests and hide the tool. /livecodes toggles it too.

    playground_url needs no SDK and stays available. It builds the livecodes.io link offline and compresses the project into the URL's #fragment. Browsers do not send that fragment to the server. The transcript puts the link in an OPEN / COPY row and keeps its contents out of later context.

    SAVE checks the key against the provider's model list without spending tokens. The lamp turns READY when the provider accepts the key. OpenAI-compatible backends also show a base url field for gateways that support /chat/completions.

    At compact at, the harness replaces the conversation with a handover summary. It leaves workspace files alone, and /undo restores the full context. Set the threshold low enough to leave room for another turn.

    Scripts on this origin can read keys in localStorage. Use a scoped, revocable key.