Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.airglow.cc/llms.txt

Use this file to discover all available pages before exploring further.

A one-shot app is the simplest way to build with Airglow: write a single short brief in your coding agent, and the agent creates a working app for the page you’re on. No scaffolding, no boilerplate — one prompt in, one app out.
Done means your coding agent has written a new app under airglow-apps/<your-app>, the local server has picked it up, and the app appears on the page you described.

​
What “one-shot” means

You write a single prompt to your coding agent that names three things:
  1. The page the app should run on (news.ycombinator.com, mail.google.com, etc.).
  2. The action the app should perform when the user opens that page.
  3. The result the app should return in the same tab.
The agent writes the manifest, the userscript, and the server module under airglow-apps/<your-app>/, the Airglow Chrome extension loads them, and the app appears on the matching page when you open it. You will need:
  • Airglow installed and running (see Quick start).
  • A coding agent attached to the airglow-sdk workspace (Claude Code, Codex, Cursor, or similar).
  • 5–10 minutes to iterate on the result.

​
Steps

​
1. Open the SDK in your coding agent

Open airglow-sdk as the workspace in your agent of choice. Let the agent inspect the repo so it knows the existing app layout.

​
2. Write a single short brief

A good first brief names the page, the action, and the result in two to three lines. No project layout, no method signatures, no implementation details. 
Airglow app for news.ycombinator.com.
Pill opens a panel. Server picks 5 stories using top HN comments,
summarized by Claude. Key from .env.
The brief above is ~150 characters and includes only the things the agent would otherwise guess wrong:
  • pill opens a panel — two states, not all-at-once.
  • picks 5 — bounded output, not a full feed mirror.
  • using top HN comments — grounded summaries, not title rewrites.
  • Claude … key from .env — chosen model + secret source.

​
3. Let the agent write the app

The agent should create three files under airglow-apps/<your-app>/:
FileJob
manifest.jsonDeclare the page match, the app name, and required permissions.
userscripts/main.tsThe in-browser code that renders the pill and the panel.
server/<name>.tsThe local function the userscript calls for model work.
The exact filenames may vary; the shape does not.

​
4. Open the target page and check the result

Open the page your app targets. The Airglow pill or panel should appear. Click it, watch the result render in the same tab, and decide whether it matches what you asked for.
The app appears only on the matching page and uses the current page content as input.

​
5. Iterate in short rounds

The first version rarely lands. Take one observation at a time and turn it into a one-line follow-up prompt. 
The summaries repeat the title. Use the top three comments per
story and write one new sentence per summary that adds something
the title doesn't already say.
Three or four rounds is normal. Stop when the page does what the brief asked for.

​
Best practices

  • One page, one action, one result. If your first brief covers two pages or two outputs, split it into two apps.
  • Be specific where the agent will guess wrong. Page, model, secret source, output shape, bounded count. Be brief everywhere else.
  • Iterate against the page, not the chat. The agent’s summary of what it did is not the result. Open the target site and inspect the UI.
  • Don’t pre-design the implementation. Avoid prescribing file structure, function names, or libraries unless you have a real reason. The agent picks reasonable defaults; over-specifying kills the “one prompt in, one app out” feel.

​
If it does not work

CaseFix
The agent asked clarifying questions instead of writing codeThe brief is too vague. Add the page, the model, the secret source.
The app does not appear on the pageRestart pnpm airglow dev, reload the extension, refresh the target page.
The app runs but the result is emptyOpen the browser console and the server terminal; ask the agent to read both and fix.
The agent wrote code outside airglow-apps/Ask it to scope changes to airglow-apps/<your-app>/ and re-run.
For more cases, open Troubleshooting.

​
Next

  • Quick start — install Airglow if you haven’t.
  • Customize existing — start from a showcase instead of from scratch.
  • Showcases — see five one-shot apps and the briefs that built them.