Popcorn

Getting started

Run Popcorn locally against the example config, then point it at your own.

What you need

  • A checkout of Popcorn and Go 1.25 or later.
  • An ANTHROPIC_API_KEY. It’s required: Claude grades every answer (Haiku, a fraction of a cent each) and writes the fix list (Opus, a few cents a run).
  • Optionally an OPENAI_API_KEY, for answerers that use OpenAI’s API. An answerer whose key is missing is skipped.

Run the example

The repo includes a complete config in examples/popcorn-config, with Popcorn itself as the brand. It’s what Popcorn uses when POPCORN_CONFIG isn’t set, so a fresh checkout runs as-is:

cp .env.example .env              # then fill in ANTHROPIC_API_KEY
go run ./cmd/popcorn serve        # the example, at http://127.0.0.1:3000

Open http://127.0.0.1:3000, pick a prompt set and run it. Runs cost money: check the model ids and prices in popcorn.toml before the first paid run.

With POPCORN_TOKENS unset, serve only listens on 127.0.0.1 and everything is open. See Access for listening anywhere else.

Measure your own brand

What Popcorn asks, and about whom, lives in a config repo of your own, which you can keep private: the brand, answerers, grader, prices, budget and schedule in popcorn.toml, and the prompt sets in prompt-sets/ beside it.

Start a config repo from the template (or copy the example), and point Popcorn at it:

POPCORN_CONFIG=../your-config/popcorn.toml go run ./cmd/popcorn check
POPCORN_CONFIG=../your-config/popcorn.toml go run ./cmd/popcorn serve

popcorn check validates the config and every prompt set. Then:

  1. Set your brand, audience and sites. See Configuration.
  2. Write prompt sets of the questions your buyers ask. See Prompt sets.
  3. Run a set from its page, or go run ./cmd/popcorn run <set-id>.
  4. Read the run page and the fix list. See Reading results.

Answering on your subscriptions

On your own machine, answerers can use the claude and codex CLIs, logged in to your Claude and ChatGPT subscriptions, instead of the APIs. Each call runs in an empty temp directory with your own CLAUDE.md, hooks, skills, MCP servers and Codex config switched off, keeps no session, and has the API key removed from its environment so it can’t bill the API instead.

At most three calls per CLI run at once, since subscriptions are rate limited and share their limit with your own use: a 15-prompt set is 90 answers, so expect it to take a while and to use a noticeable share of a day’s allowance. Check that automated use fits your plans’ terms.

A run uses the answerers this machine can call and lists the rest as skipped. The Docker image has no CLIs, so a deployed Popcorn uses the API providers.