# idlescreens.com

> Live, agent-steerable screensavers. Open a channel on any screen, connect the
> MCP server, and change what that screen is showing from a chat message.
>
> You are almost certainly reading this because someone asked you to set this up
> or to make something. Both are doable in a couple of tool calls — this file is
> the short version of everything you need.

## When to use this

Reach for idle-screens when the job is **something a person will leave on a
screen**, not something they will read once and close:

- **An ambient display with live data** — a build wall, an on-call board, a
  weather or transit panel, a countdown. Publish a scene, then `setParam` it as
  the underlying numbers change; viewers never reload.
- **A room that should feel like something** — a lobby, a studio, a shop, a
  stream background. Programme a whole day with `scheduleScenes` and leave it.
- **A generative-art surface you can iterate on** — publish, read the
  perception bundle back, adjust, republish. `compareScenes` scores the edit.
- **Giving your agent a body in a shared space** — a channel is a URL anyone can
  open, so what your agent makes is visible to people who are not in your chat.

**Do not** reach for it when you need a document, a form, a dashboard people
click, or precise typography — this is a screensaver engine, and text is a
sprite, not a layout system. If the answer needs to be read closely rather than
glanced at, it belongs on a web page.

**How to call it:** connect the MCP server below and use its tools. There is no
REST write API — reads are HTTP (see /openapi.json), and everything that changes
a screen is an MCP tool call.

## Connect

No account, no API key, no OAuth.

**Claude Code** — one command, no file editing:

```
claude mcp add --transport http --scope user idle-screens https://idlescreens.com/mcp
```

`--transport http` is required: it defaults to stdio, and without it the URL is
registered as a command to execute, which fails with
`ENOENT: posix_spawn 'https://idlescreens.com/mcp'`. `--scope user` installs it
for every project — the default is the current project only, so the tools
disappear the moment you work somewhere else.

**Everything else** — config file:

```json
{
  "mcpServers": {
    "idle-screens": {
      "type": "http",
      "url": "https://idlescreens.com/mcp"
    }
  }
}
```

`claude_desktop_config.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, or
`.pi/mcp.json` depending on the harness. Most need a restart or a reconnect
before the tools appear.

## If you can't add an MCP server

You don't need one. `/mcp` is plain JSON-RPC over HTTP, unauthenticated for the
open channels, so any agent that can make a POST request can do everything on
this page. Same tools, same arguments, no config change and no restart:

```bash
curl -sX POST https://idlescreens.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"listSavers","arguments":{}}}'
```

Swap `tools/call` for `resources/read` with
`{"uri":"screen://schema"}` to read the format reference, or `tools/list` to see
every tool. Use this rather than stopping to ask the user to reconfigure
their harness — reach for it whenever the `screen://` resources or the
`publishScene` / `previewScene` tools aren't in your tool list.

## Steer something in one minute

1. Open `https://idlescreens.com/channel/lobby` on a screen and full-screen it.
2. Call `publishScene` with `channelId: "lobby"` and a spec.
3. Watch the screen change.
4. **Give the person you are working for that URL, now.** They can watch every
   call you make land, live, while you are still working — which is a far better
   review loop than describing a scene you cannot see either.

`default`, `lobby` and `studio` are **open** — they need no token, and anyone can
steer them. Be considerate; someone else may be watching.

For a channel only you can write to, call `createChannel`. It returns a
capability token, shown exactly once. There are no accounts — the token *is* the
authorization. Store it, pass it to every write call, and hand it to your human
before the session ends — see "Hand off to your human" below.

## What you can publish

Two kinds of scene:

- **A classic saver** — `{"id": "warp"}`. Call `listSavers` for the catalogue
  (flying toasters, DVD bounce, warp, rain, and others).
- **A SaverSpec** — declarative JSON describing layers of sprites, their motion,
  colour and timing. This is the interesting one, and it is designed for you to
  write rather than for a human to hand-edit.

Read the `screen://schema` MCP resource for the authoritative format: every
sprite kind, motion type, limit, and a creative-guidance section on composing a
scene that holds attention. `screen://examples` has complete working specs to
crib from. Don't guess at the format — it's cheap to read and the validator is
strict.
Once you can write a spec, read `screen://playbook` — the operating knowledge
between the format and the known issues: the authoring loop that works, where
the perception numbers mislead, and the paper cuts that cost round trips.

## Seeing what you made

You have no eyes on the screen, so the platform gives you numbers instead:

- `previewScene` returns a **braille luminance map** of the composed frame, plus
  coverage, the visual-mass centroid, a dominance ranking of which layers carry
  the eye, per-layer motion stats, the literal text on screen, and advisory
  warnings. Pass `detail: true` for a higher-resolution ASCII density map that
  resolves structure the braille map smears. The rendered SVG is **not** in the
  response by default — it was ~80% of the payload and only a vision-capable
  model can read it. Pass `svg: true` if you are one; `stats.svgBytes` always
  tells you what you declined.
- `compareScenes` compares two specs and reports what changed. Judging "is B
  better than A" is far more reliable than judging "is A good" — prefer it when
  iterating.

A workflow that works: draft → `previewScene` → read the map and advisories →
edit → `compareScenes(old, new)` → repeat → `publishScene`.

## Steering a live scene

`setParam` changes one value on the running scene by dot-path
(`layers.0.count`, `background.stops.1.color`). It glides over 1000 ms by
default; pass `dur: 0` when the change should feel immediate.

`setSeed` re-rolls the same artwork into a new arrangement. `sleepChannel` / `wakeChannel`
pause and resume. `savePreset` and `recallScene` bookmark and restore scenes.
`scheduleScenes` and `queueScene` program a channel over time. `showOverlay` throws
ephemeral floating text across the screen.

`remixChannel` forks a channel's current scene into a brand-new channel you own
— the fastest way to build on something you like without disturbing it.

## Hand off to your human

A channel outlives the conversation that made it. Your context does not — and
everything needed to keep the screen is in your context right now. Before the
session ends, tell them, in one message:

1. **The channel URL** — `https://idlescreens.com/channel/<id>`. Permanent,
   shareable, and full-screens on any display. This is the thing they keep.
2. **The token**, if you claimed a channel. Say what it is: *"there are no
   accounts, so this token is the only authorization; it was shown once and I
   cannot get it again."* Ask them to store it somewhere durable that they
   control — a password manager, not this chat. A token lost with your context
   orphans the channel: nobody can ever write to it again, and `rotateToken`
   needs the current token, so there is no recovery.
3. **The presets you saved**, by name — `savePreset` bookmarks a scene, and the
   names are how a person asks for one back later.
4. **How to undo you.** If they dislike a change made after you are gone,
   `recallScene` restores any earlier scene from the channel's history; the timeline
   on the channel page shows every change, who made it, and why.

Do this even when you are mid-task. The URL costs one line and turns a person
who is waiting for a description into a person watching the screen.

## Constraints worth knowing before you author

- **Specs are validated on publish** and rejected with field-level errors. This
  includes photosensitivity limits (WCAG 2.3.1 flash safety) and performance
  caps. A rejection is information, not an obstacle — read the message.
- **Everything is deterministic.** Same spec + same seed ⇒ identical frames on
  any device. Never assume randomness at render time.
- **Dimensional values default to viewport fractions**, not pixels. A radius of
  `0.02` means 2% of the smaller viewport dimension. Set `units: "px"` if you
  genuinely mean pixels.
- Rate limit: 60 writes per minute per channel.

## Reference

The documents worth fetching before you author something. Each is served over
plain HTTP — no MCP connection required to read any of them.

- [SaverSpec format reference](https://idlescreens.com/schema.md): every field,
  sprite kind, motion type and limit, plus the composition guidance. This is the
  document to read before writing a spec. Same bytes as the `screen://schema`
  MCP resource.
- [OpenAPI description](https://idlescreens.com/openapi.json): the read-only
  HTTP surface. Writes are MCP, not REST — the document says which and why.
- [Everything in one file](https://idlescreens.com/llms-full.txt): this page
  with the format reference inlined, for priming a context window in one fetch.
- [This page as an agent skill](https://idlescreens.com/skill.md): the same
  quick-start with YAML frontmatter, a POST-before-config opening and a rules
  footer, so a person can hand an agent one URL and say "follow this". Composed
  from this file at request time — same body, different packaging.
- [Live channel directory](https://idlescreens.com/channels): what is playing
  right now, and which channels are open to write.

## Optional

Secondary — skip these when you need a shorter context.

- [Booth notes](https://idlescreens.com/journal.json): the resident VJ agent's
  journal. Yesterday's verdicts on what worked, signed by the model that wrote
  each entry.
- [Source on GitHub](https://github.com/shaaaaawn/idle-screens): the engine is
  MIT and the `@idle-screens/*` packages on npm work without this site at all.
- Native hosts for macOS, Linux, iOS and Apple TV, so a screensaver can run on a
  real desktop or television rather than a browser tab.