Build a Summer App with your agent

Draft. Summer Apps is in a closed test. This page goes live after the end-to-end test on production.

This page is for the agent and for the person who drives it. It has the build loop, the three mistakes that break apps, and prompts that work.

Connect your agent

The summer_app_* tools are in the Summer Engine MCP. Use one of the two forms. Or describe the app to Summer in Studio chat: Build a new app in Studio > Apps and Edit with agent on an app page open it.

On your computer (npm)
In the browser (hosted)

For Claude Code, Codex, Cursor and other agents on your computer:

npx -y summer-engine@latest setup claude-code --yes   # or: setup codex --yes
npx -y summer-engine@latest login

setup adds the MCP (npx -y summer-engine@latest mcp) to your agent and installs the Summer skills, summer-apps and summer-apps-design among them. login signs you in to your Summer account in the browser. Restart your agent. Other agents: MCP setup.The npm package adds dir to summer_app_publish: publish a local folder. Its summer_app_dock docks an app in Summer Engine; that comes with the next Summer Engine update.

For Claude and ChatGPT: add a custom connector with the address https://mcp.summerengine.com/mcp and sign in to your Summer account. Step by step: Connect your agent.

The loop

Read the guide

summer_app_guide returns Markdown. Without a section it returns overview: when to build an app, layout or code, the loop and the rules. Read it first. Then read what the app needs: examples starts with a complete working app; sdk, manifest and kit have every call, field and component; design has the look; layout the layout format; types the SDK’s TypeScript types. all returns every section except types at once, about 100 KB. Load the summer-apps and summer-apps-design skills when you have them.

Create the app

summer_app_create { name, purpose, format }. format is code (default) or layout. The app id is app.id in the answer. The person’s open Studio tab moves to the new app. If the answer has studio.reason: "no_tab", no Studio tab was open: give the person the link /studio/apps/<appId>.

Write and publish

Write index.html and app.js (and CSS if you need it), then summer_app_publish { appId, files, manifest, note }. With the npm package, pass dir instead of files. Each publish is a new, immutable version. A publish error names the file or the rule: fix it and publish again. A publish that goes through can still answer warnings: SDK calls whose permission the manifest lacks, and summer.agent.send events or summer.agent.tool tools the manifest does not declare. Those fail when the app runs. Fix the warnings and publish again.

Seed data

If the app should start with content, write it with summer_app_data and "as": "seed". Seed rows belong to the team and show no author.

Look at it

summer_app_screenshot { appId }, then again with width: 390 (a phone) and theme: "dark". To see a dialog or a second state, add steps. Fix every error, console line and refused call it reports, publish, and look again. Repeat until it is clean.

Listen

summer_app_events { appId, after, timeoutSeconds } waits up to 50 seconds for what the app sends (summer.agent.send), errors (uncaught ones and console.error lines) and the team’s feedback. Pass the returned cursor as after next time.

Change it, keep it or archive it

To change the app, summer_app_get { appId } returns the current files and manifest. Edit them and publish again. To change only data, use summer_app_data; no publish needed. When the team keeps the app, summer_app_update { appId, status: "kept" }. Archive throwaway apps when you are done: summer_app_update { appId, status: "archived" }.

Before step 2, check whether Summer already does the job: the asset library’s collections and groups, Pick one and sound choices, Grow dashboards, Team. If it does, use that. If an app needs something the SDK lacks, report it with summer_app_report_gap.

Three things that break apps

The SDK and kit load as ES modules from root paths. The app is served from its own host, apps.summerengine.app:
<script type="module" src="/summer-sdk/v1.js"></script> <script type="module" src="/summer-ui/v1/ui.js"></script> <script type="module" src="app.js"></script>
Any other path, a CDN copy or a local copy does not connect. The screenshot then shows connected: false.
await summer.ready before the first call. It resolves when Studio connects the app. Outside Summer Studio it never resolves, so opening index.html on its own shows nothing. There is no offline host; do not mock the SDK.
Shared data goes through summer.data.collection(name). Use .list(), .get(id), .put(id, data), .patch(id, partial), .remove(id) and .subscribe(fn). There is no summer.data.list(name); it rejects with invalid.

Also: the app runs in a sandbox with no cookies, no localStorage and no network. Keep state in shared data. Add the data permission to the manifest, or every data call rejects with permission_missing.

Catch mistakes before you publish

Save the SDK types from /summer-sdk/v1.d.ts (or summer_app_guide section types) as summer-sdk.d.ts in the folder above your app folder, and start app.js with:

// @ts-check
/// <reference path="../summer-sdk.d.ts" />

Your editor, or tsc --checkJs --noEmit, now reports a wrong method name, a missing argument or a wrong result field. Keep the .d.ts file out of the app folder: .ts is not an app file type, so a publish with it fails.

Look at it: summer_app_screenshot

Summer renders the published app headless, as the person and with their data, and returns the PNG plus a report.

Argument	Default
`appId`		Required.
`version`	the current one	A published version.
`width`, `height`	1280, 800	320 to 1920 and 320 to 1600 px. Use `width: 390` for a phone.
`theme`	`light`	`light` or `dark`.
`fullPage`	`false`	The whole scroll height, up to 4,000 px.
`params`		Launch params, as in `/studio/apps/<appId>?key=value`.
`steps`		Up to 5 steps, run in order before the capture: `{ "click": "<css selector>" }`, `{ "press": "<declared action id>" }` or `{ "wait": <ms> }` (up to 3,000). In a selector, `>>>` reaches inside kit components: `"summer-table >>> tbody tr"`. Writes that a step causes are refused, as always.
`out`		npm package only: also save the PNG to this local path.

The report:

Field	Tells you
`connected`	The SDK loaded and Studio’s stand-in connected it. `false`: fix how `index.html` loads `/summer-sdk/v1.js`.
`rendered`	The first SDK calls settled and the app painted within 8 seconds. The capture then waits until the app’s SDK calls settle and no kit element shows `loading`, up to 6 seconds.
`console`, `errors`	Console lines and uncaught errors, with source and line.
`calls`	Every SDK call with `ok`, and `code` for a refused one.
`declared`	The fields and buttons from `summer.page.declare`.
`agentTools`	The agent tools the app registered.
`steps`	Each step with `ok`, and `error` for one that failed.
`title`, `notices`, `hints`	`setTitle` and `notify` text, and hints on what to fix. A hint says when the page still shows loading placeholders.

To see the edit dialog of an app whose table rows open one, click the first row before the capture:

{ "appId": "<app id>", "steps": [{ "click": "summer-table >>> tbody tr" }, { "wait": 300 }] }

For a button the app declared with summer.page.declare, { "press": "<action id>" } works the same way. The screenshot is read-only. Reads run as the person (data, assets, team, projects, Grow, choices, engine status). Writes, paid calls and other engine calls are refused with invalid; events and notices are recorded, not delivered. They all work in Studio. To see data in a screenshot, seed it first with summer_app_data. A screenshot before the first publish fails with not_found. The SDK also reports an app’s console.error lines to summer_app_events as error events, so errors the app catches and logs reach you after the person uses it.

Prompts that work

Build a team tool. Your agent builds, publishes, seeds and checks a Summer App.

Change an app. Your agent edits the files and publishes a new version.

Edit the data. Your agent changes records; everyone with the app open sees it live.

Fix what the team reports. Your agent reads errors and feedback and fixes the app.

Worked examples: Apps for game teams.

Start here

Create and publish your game

Other ways to start

Essentials

Models

Using Summer

Summer Studio

Summer Apps

Other Engine Migration

Automation

Reference

Build a Summer App with your agent

Connect your agent

The loop

Three things that break apps

Catch mistakes before you publish

Look at it: summer_app_screenshot

Prompts that work

​Connect your agent

​The loop

​Three things that break apps

​Catch mistakes before you publish

​Look at it: summer_app_screenshot

​Prompts that work

Connect your agent

The loop

Three things that break apps

Catch mistakes before you publish

Look at it: summer_app_screenshot

Prompts that work