clank

Clank

Visually editable previews for web & mobile

Clank injects an overlay into your web or mobile apps that allows you to edit them while you're using them.

The fastest way to iterate on apps is by just pointing and explaining.

Clank is for iterating on that last 10% that AI can't solve.

How

Run clank preview to start your dev server with a new agent session, or clank preview --attach to connect an existing Claude, Codex, or OpenCode session.

The mobile app needs a Clank gateway. Pair it with your laptop using clank pair, or use a hosted gateway such as supaclank.com to build without a laptop. The browser overlay and local Expo dev servers require the Clank CLI.

Get started

For web app development, start with the laptop. For mobile Expo app development, start with the mobile app.

Laptop (Clank CLI)

The clank CLI starts its own local Clank gateway, which the browser overlay (or mobile app) connects to.

brew install supaclank/tap/clank
# cd to your project, and run
clank preview # launches your project

the CLI will onboard you the first time with agent preferences and synthesize an initial launch config for your project's dev server.

Mobile app

Connects to any Clank gateway: By default it connects to api.supaclank.com via OIDC, but you can also pair your laptop (clank pair), or just set the gateway URL/IP directly.

Mobile demo

https://github.com/user-attachments/assets/e2a9b928-d861-442d-97e1-d1a81880f014

Usage

Overlay UI

For the mobile overlay: Shake the phone to bring up the floating prompt box, shake again to see chat. The app remains usable. Just move the box around, or hide it.

CLI

Tips & tricks:

Preview any pull request instantly. It reuses your local worktree on-disk if it finds it, otherwise creates one.

clank preview https://github.com/supaclank/web/pull/18

Specify the folder and your dev-server's port for clank preview to forward to it, while getting the correct context:

clank preview . :8080

Attach to an existing agent session

clank preview --attach # opens agent session picker, any of your harnesses

Architecture

flowchart LR
    subgraph clients["Your devices"]
        browser["Browser overlay"]
        terminal["Terminal (clank)"]
        phone["Phone"]
    end

    subgraph gateway_box["Laptop or cloud"]
        gateway["<b>Gateway (clankd)</b><br/>auth · provisioning<br>proxy · previews<br>images · notifications"]
    end

    subgraph host_box["Laptop or sandbox"]
        host["<b>Host (clank-host)</b><br/>sessions · events<br/>credentials · git"]
        agent["Your agent<br/>harness"]
    end

    browser --> gateway
    terminal --> gateway
    phone --> gateway
    gateway --> host
    host --> agent

On a laptop everything runs locally, using your existing agent and git setup. The laptop is your default "sandbox" environment, more info in provisioning & sandboxes.

A multi-tenant gateway that's built to be a dumb relay with minimal user data stored. It provisions sandboxes for the user, authenticates and proxies requests, handles wake/sleep, and some coordination like notifications, images, previews.

The host handles the coding agents, git operations, credentials, keepalive, webhooks. It connects to the agent harnesses via ACP, and needs a persistent dev environment where credentials and all the work is stored, whether it be your laptop or a persistent sandbox.

Gateway

Multi-tenant

The gateway routes requests by user ID, which it acquires via a simple pkg/auth.Authenticator interface.

type Authenticator interface {
    Verify(r *http.Request) (Principal, error)
}

type Principal struct {
    UserID string
    Claims map[string]any
}

This allows the gateway to remain agnostic to your specific auth method.

The only contract is that the request context contains that auth.Principal after verification. Clank provides a simple middleware for that, calling Authenticator's Verify(r) and injecting the principal. Clank also bundles four Authenticators into the auth package: AllowAll, OIDC, StaticBearer, JWTHS256.

Bridge auth

Clank CLI itself implements a mobile<->laptop bridge auth.Authenticator, allowing you to pair your mobile app to your laptop and control your agents from the phone.

Most services today require a central server to mediate this pairing. Clank instead implemented a protocol for this.

For the implementation and spec for this, see docs/bridge-pairing.md.

Provisioning & sandboxes

Clank tries to be agnostic to the exact sandbox provider. Each sandbox provider implements a Provisioner interface. The laptop implements a local.Provisioner, and the cloud currently uses flymachine.Provisioner (you own the image, we just require clank-host to be reachable).

End-to-end encryption

TL;DR: Not implemented. Self-hosting is the solution: Users can instead pair their laptop and use something like Tailscale. Companies can self-host on their own infra.

Agent harnesses

Clank supports Claude Code, Codex, OpenCode, via ACP. We're probably adding support for Hermes, Gemini, and Pi soon. We still need small adapters for each ACP server, due to versioning, auth, and slight differences.

Previews

Expo projects are detected automatically. For web projects, your connected agent generates .clank/launch.yaml on first run.

For web, clank preview starts or attaches to a dev server and injects the Clank overlay as a <script> tag without changing your source code.

For Expo, clank preview injects a small script that hooks into various React Native APIs.

Local previews stay on your laptop, while hosted previews use an owner-only URL that securely tunnels through the gateway and can be shared or revoked. Easy public tunnel links for your local previews coming soon

The mobile app itself is similar to how Expo Go works under the hood. It loads user apps using the same pre-installed native components that Expo Go has, so Clank and Expo Go apps are compatible. Support for development builds is on the roadmap.

For Expo apps we also append a system prompt, to avoid common pitfalls that agents seem to fall into when developing mobile apps: https://github.com/supaclank/clank/tree/main/internal/agent/guidance.

Voice

Voice is push-to-talk dictation for the preview overlay. Use the browser's Web Speech API or keep audio local with clank-voice, powered by Silero VAD and NVIDIA Parakeet v3. The mobile app runs the same speech-recognition stack on-device.

brew install supaclank/tap/clank-voice # optional, macOS; builds from source (needs Xcode CLT)

Models (~670 MB) download on first use.

Images & attachments

Images and attachments are handled via a minimal blobstore interface, with S3 for cloud deployments, and a LAN one for mobile->laptop transfers.

Roadmap

• In the future we may use something like https://github.com/superfly/tokenizer (and/or an LLM proxy) for people that don't want to give up real keys, and for 3rd party connections.
• Ephemeral one-off sandboxes are also on the roadmap for workflows that need the isolation.
• Public tunnel links for your local previews
• Support for Expo development builds
• Create a feature request / suggestion!

Docs

• docs/chat-client-spec. The spec every clank client is built against (the TUI is the golden reference; the mobile app tracks it too).
• docs/bridge-pairing.md. The phone↔laptop pairing protocol
• docker/README.md. Docker stack, but mainly for testing. Supaclank currently instantiates pkg/gateway.Gateway directly.
• voice-engine/README.md. The local dictation engine.