# Oblivion IDE documentation

> Oblivion IDE Studio is a Windows desktop IDE that runs Claude Code and Grok in up to four terminals beside a live app preview with phone and tablet frames. Oblivion Mobile (Android) shows the same preview on a real phone over the internet. This file is the full documentation from https://docs.oblivionide.com/ as Markdown.

# Oblivion IDE Studio

A Windows desktop IDE that runs **Claude Code and Grok** in up to four terminals, right beside a **live preview** of the app they're building. The preview has real phone and tablet frames, and the **Oblivion Mobile** phone app opens the same preview on your own phone from anywhere.

- **Windows** 10 / 11
- **Claude Code** & Grok
- **1–4** terminals per workspace
- **17** phone & tablet frames
- **Android** companion app

**The short version.** Your agents can see what they build. Oblivion gives every agent a local control API, so it can load its work into the preview, read the console, take screenshots and check the phone layout itself, instead of waiting for you to describe what went wrong.

#### Agents side by side

Each terminal starts Claude Code or Grok on its own. Chats resume where they left off when you reopen the app.

[Terminals & agents →](https://docs.oblivionide.com/#terminals)

#### Live preview

A real browser next to the terminals, with phone and tablet frames, zoom, a console window and a pop-out window.

[Live preview →](https://docs.oblivionide.com/#preview)

#### Mark-up for AI

Draw on the preview, add a note and press Send to AI. The marked-up screenshot goes straight into the agent's terminal.

[Mark-up →](https://docs.oblivionide.com/#markup)

#### Dev servers that come back

Each workspace remembers its dev server and starts it again the next time you open the workspace.

[Dev servers →](https://docs.oblivionide.com/#dev-servers)

#### Your phone, anywhere

Oblivion Mobile connects to your PC over the internet and shows the same preview, on Wi-Fi or mobile data.

[Oblivion Mobile →](https://docs.oblivionide.com/#mobile)

#### Built for agents

An HTTP API and an `AGENTS.md` in every workspace tell any agent how to drive the preview, the dev server and the phone.

[Agent control API →](https://docs.oblivionide.com/#control-api)

## Install

Oblivion IDE Studio is in **early access**. Join the list at [oblivionide.com](https://www.oblivionide.com/#access) to get the installer when it's available.

#### Requirements

-   **Windows 10 or 11** (64-bit).
-   **A Google account** to sign in to Oblivion.
-   **Claude Code** (the `claude` command) and/or the **Grok CLI** (the `grok` command), installed and signed in with your own accounts. Oblivion runs them; it doesn't include them.
-   **Git for Windows**, which Claude Code needs on Windows.
-   Optional: an Android phone for [Oblivion Mobile](https://docs.oblivionide.com/#mobile).

#### Running the installer

1.  Run `Oblivion-IDE-Studio-Setup-<version>.exe`.
2.  If Windows shows _"Windows protected your PC"_, click **More info → Run anyway**. Early-access builds aren't code-signed yet.
3.  Choose an install folder (per-user install, no admin rights needed) and finish.

**Updating closes the running IDE.** Installing a new version over an old one closes Oblivion and its terminals. Claude chats resume when it reopens.

## Sign in & first run

1.  **Sign in with Google.** The IDE stays locked until you do. Your browser opens the Google sign-in, then sends you back to Oblivion.
2.  **Pick a working folder.** This becomes your first [workspace](https://docs.oblivionide.com/#workspaces).
3.  **Terminals open.** Two by default, each starting Claude Code (change this in [Settings](https://docs.oblivionide.com/#settings)).
4.  **Start your app.** Ask the agent to start the dev server. It hands the server to Oblivion, which loads it into the preview.

**Signing out locks the IDE.** Sign out from the profile menu (top right). Every terminal and its agent closes, and phones connected through your account are removed from this PC.

## Workspaces

A workspace is a project folder. Switch between them from the folder menu at the top left. **Set new workspace…** adds a folder, and the eight most recent stay in the list.

-   **Everything keeps running when you switch.** Each workspace has its own terminals, its own preview and its own dev server, all alive in the background.
-   **Everything comes back when you reopen the app.** Each workspace saves its terminal layout, Claude session ids, maximized terminal and preview URL in `.oblivion/session.json`, and restores them the first time you open it.
-   **Every workspace gets an `AGENTS.md`**, which tells agents how to use the preview and dev server. See [workspace files](https://docs.oblivionide.com/#workspace-files).

## Terminals & agents

The left side of the window holds 1 to 4 terminals per workspace, laid out automatically (one, side by side, or a 2×2 grid). Add one with **\+ Terminal** in the top bar. Each is a real PowerShell terminal, so interactive tools render correctly.

#### Agents

-   With _Launch the agent automatically_ on (the default), each new terminal starts its agent right away.
-   Choose **Claude**, **Grok** or both under _Open new terminals with_. With both, new terminals alternate so each agent gets an equal share.
-   **Claude chats resume.** Every Claude terminal gets its own session id, so closing and reopening the app picks up the same conversation (`claude --resume`). Grok starts fresh.
-   Claude starts with `--dangerously-skip-permissions` unless you turn off _Bypass permission prompts_.

#### Terminal controls

Hover over a terminal to show its controls in the top-right corner:

| Control | What it does |
| --- | --- |
| **Refresh** | Restarts the terminal and its agent. A Claude chat resumes its conversation if it was saved. |
| **Maximize** | Fills the terminal area with this terminal; click again to restore the grid. |
| **Close** | Ends the terminal and its agent. |

When an agent exits, the terminal says so. Use **Refresh** to start it again.

## Live preview

The right side is a real browser showing your app. Each workspace has its own preview. Logins to sites in the preview are kept between sessions; _Sign out of all sites_ in Settings clears them.

#### Toolbar, left to right

| Control | What it does |
| --- | --- |
| **Back / Forward / Reload** | Browser navigation. Reload also reloads connected phones. |
| **Dev server** | Shown once the workspace has a server. A dot shows its state; click for Restart, Stop, the log and more. See [Dev servers](https://docs.oblivionide.com/#dev-servers). |
| **Address bar** | Type a URL or just `localhost:3000`; `http://` is added for you and hidden in the bar. Local file paths work too. |
| **Console** | Opens the preview's console (logs and errors) in its own window. Phone console output appears there too. |
| **Mark-up** | Draw on the preview and send it to the AI. See [Mark-up](https://docs.oblivionide.com/#markup). |
| **Viewport** | Switch between Desktop and a phone or tablet frame. The icon shows the current mode. See [frames](https://docs.oblivionide.com/#devices). |
| **Zoom** | Zoom out, reset, zoom in. Also Ctrl++ / Ctrl+\- / Ctrl+0 from anywhere in the window. |
| **Pop out** | Moves the preview into its own window (same device mode). Close it, or click _Return to IDE_, to bring it back. |
| **Collapse** | Shrinks the preview to a thin rail so the terminals get the full width. |

If the page can't be reached, the preview says so with **Retry** and **Clear**. When the workspace has a remembered dev server that isn't running, it also offers **Start dev server**.

**Zoom works two ways.** On Desktop it zooms the page (25%–300%). In a phone or tablet frame it scales the whole device on screen, while the page keeps the device's real resolution.

## Phone & tablet frames

The viewport menu lists Desktop plus 17 devices. Each frame uses the device's real CSS viewport size and pixel ratio, mobile viewport behavior, and its notch, Dynamic Island or camera hole, with a status bar that takes the page's color.

| Device | Key (for the API) | Viewport | Pixel ratio |
| --- | --- | --- | --- |
| iPhone SE | `iphone-se` | 375 × 667 | 2 |
| iPhone 14 (default phone) | `iphone-14` | 390 × 844 | 3 |
| iPhone 15 Pro Max | `iphone-15-pro-max` | 430 × 932 | 3 |
| iPhone 16 | `iphone-16` | 393 × 852 | 3 |
| iPhone Air | `iphone-air` | 420 × 912 | 3 |
| iPhone 17 Pro | `iphone-17-pro` | 402 × 874 | 3 |
| iPhone 17 Pro Max | `iphone-17-pro-max` | 440 × 956 | 3 |
| Pixel 7 | `pixel-7` | 412 × 915 | 2.625 |
| Pixel 9a | `pixel-9a` | 412 × 923 | 2.625 |
| Pixel 9 Pro | `pixel-9-pro` | 410 × 914 | 3.125 |
| Galaxy S20 | `galaxy-s20` | 360 × 800 | 4 |
| Galaxy S25 | `galaxy-s25` | 360 × 780 | 3 |
| Galaxy S25 Ultra | `galaxy-s25-ultra` | 384 × 832 | 3.75 |
| iPad mini | `ipad-mini` | 768 × 1024 | 2 |
| iPad Air 11" | `ipad-air-11` | 820 × 1180 | 2 |
| iPad Pro 11" | `ipad-pro-11` | 834 × 1194 | 2 |
| iPad Pro 13" | `ipad-pro-13` | 1032 × 1376 | 2 |

#### Full-screen app mode

On by default (toggle at the bottom of the viewport menu). The page runs full-screen like an installed app: it draws behind the status bar, notch and camera, and `env(safe-area-inset-*)` returns the device's real insets (iPhone 14: 47px top, 34px bottom). Turn it off for a browser-style view, where the status bar gets its own strip.

**Making content clear the notch:** add `viewport-fit=cover` to your viewport meta tag and pad with `env(safe-area-inset-top)` / `env(safe-area-inset-bottom)`.

## Mark-up & Send to AI

Point at the problem instead of describing it. Click the pencil in the preview toolbar, draw on the page, optionally type a note, and press **Send to AI**.

-   **Tools:** pen, arrow, box and text, in red, yellow or blue. Undo (Ctrl+Z) and Clear all. Drag the toolbar by its handle to move it out of the way.
-   **Send:** Ctrl+Enter or the button. Close with Esc.
-   **What happens:** Oblivion screenshots the preview (including the device frame and your marks), saves it as `.oblivion/screenshots/annotated-<time>.png`, and types your note plus the file path into the focused terminal of that workspace (or its first terminal), then presses Enter.
-   Works the same in the pop-out window, and from the phone app (saved as `phone-annotated-<time>.png`).

The generated `AGENTS.md` tells agents to open that PNG first, fix the marked spots, then screenshot the preview to confirm.

## Dev servers

A dev server started in an agent's own terminal dies when that chat ends or the app closes. Oblivion runs workspace dev servers itself, so they keep running and **start again every time the workspace reopens**.

#### How a workspace gets its server

 

The agent calls `POST /server` with the command and URL (see the [control API](https://docs.oblivionide.com/#control-api)). Oblivion starts the command in the background, waits until the port answers, and loads the URL into the preview. If something already listens on that port, Oblivion just remembers the command for next time.

When the preview loads a `localhost` page from a server started somewhere else (for example, in a terminal), Oblivion works out the command behind that port and remembers it for the workspace.

#### The dev server menu

Click the server button in the preview toolbar. It shows the state (Running, Starting, Stopped, Exited with its code, or Couldn't start), the command, and the last lines of output.

-   **Restart / Start / Stop**. Servers started outside Oblivion can't be stopped from here.
-   **Open log:** the full output, in `.oblivion/server.log`.
-   **Start when this workspace opens:** on by default.
-   **Forget this server:** removes it from the workspace.

Closing Oblivion stops the servers it started. Servers get `BROWSER=none`, so tools like Create React App don't open a browser tab.

## Notifications

When a chat finishes while you're in another app or another workspace, Windows shows a notification such as _"Claude is done · my-site"_ with the start of the agent's last reply. Click it to jump to that terminal. If you're already looking at the chat, nothing pops up.

-   **Claude** reports each finished reply through a hook Oblivion passes at launch (`--settings` with a `Stop` hook). Your own Claude settings and hooks still apply.
-   **Grok** has no hooks, so Oblivion watches its output: after you press Enter, a reply counts as finished once its output stops for about 6 seconds.
-   Turn it off with _Notify me when a chat finishes_ in Settings. Chats that were already open start notifying after their next restart.

## Settings

Open from the profile menu (top right) → **Settings**.

| Setting | Default | What it does |
| --- | --- | --- |
| **Working folder** | chosen on first run | The current workspace folder. _Change…_ picks another. |
| **Launch the agent automatically in new terminals** | On | Starts Claude or Grok in each new terminal. Off gives a plain PowerShell. |
| **Bypass permission prompts** | On | Starts Claude with `--dangerously-skip-permissions`. |
| **Remote Control for Claude chats** | Off | Lets you continue Claude chats from claude.ai/code or the Claude app. Applies to new Claude terminals; in a running chat, type `/remote-control`. |
| **Notify me when a chat finishes** | On | Windows notification when a chat finishes while you're elsewhere. |
| **Open new terminals with** | Claude | Claude, Grok, or both (alternating). |
| **Terminals on startup** | 2 | How many terminals (1–4) a workspace opens with the first time. |
| **Preview logins → Sign out of all sites** | — | Clears cookies and storage for every site in the preview. |

The **phone button** in the top bar holds the phone settings: _Phone preview_ on/off, your connected phones (with Remove) and _Extra ports to share_. See [Oblivion Mobile](https://docs.oblivionide.com/#mobile).

## Oblivion Mobile

The Android companion app shows your live preview on a real phone. It loads the same `localhost` URLs as the IDE preview, follows the preview as it changes, and sends its console output and screenshots back to the PC, so agents can test on real hardware.

#### Connect a phone

1.  In the IDE, click the phone button in the top bar and turn on **Phone preview**.
2.  On the phone, open Oblivion Mobile and sign in with the **same Google account** as the IDE.
3.  Your PC shows up in the app's list. Tap it to connect.

There's no pairing code and no need to be on the same Wi-Fi: **phones connect over the internet**, on Wi-Fi or mobile data.

**Phone:** 
- **Oblivion Mobile** — signed in to your account

**Connection:** 
- **Private signaling channel** — only your account can read it
- **Encrypted WebRTC link** — direct, or through a relay when networks block it

**PC:** 
- **Oblivion IDE Studio** — shares the preview's localhost port

#### What the phone can reach

Only the port the preview is showing (for `http://localhost:3000`, port 3000) plus any **Extra ports to share** you list in the phone panel, such as an API on port 8000. Nothing else on your PC is exposed.

#### On the phone

-   The phone follows the IDE: changing the URL, reloading or switching workspace updates the phone too.
-   Mark up the phone's screen and send it to the AI, just like the desktop mark-up.
-   Agents can screenshot the phone, read its console, reload it and load a URL on it through `/device` endpoints.

**Phones belong to your account.** Signing out of the IDE, or signing in with a different account, removes the phones linked to the old account from this PC.

## Agent control API

Oblivion runs a small HTTP server on `127.0.0.1` so agents in its terminals can drive the IDE. It's plain HTTP, so it works the same for Claude, Grok or any other tool.

-   The address and token are in every terminal's environment as `OBLIVION_CONTROL` and `OBLIVION_TOKEN`, and in `.oblivion/control.json` in the workspace.
-   Every request needs the header `x-oblivion-token: $OBLIVION_TOKEN`. The token changes each time the app starts.

### Endpoints

| Endpoint | Body | What it does |
| --- | --- | --- |
| POST `/preview` | `{"url"}` | Load a URL in the preview |
| POST `/preview/reload` | — | Reload the preview (and connected phones) |
| POST `/preview/clear` | — | Blank the preview |
| POST `/preview/viewport` | `{"mode"}` | `desktop`, `mobile` (iPhone 14) or a [device key](https://docs.oblivionide.com/#devices) |
| GET `/preview/console` | — | Recent console entries: `{ok, entries:[{level, message, source, at}]}` |
| POST `/preview/screenshot` | `{"path"?}` | Save PNGs: `path` (what you see, including the device frame) and `fullPagePath` (the whole scrollable page) |
| GET `/server` | — | Dev server state and its last log lines |
| POST `/server` | `{"command","url"?,"cwd"?,"port"?}` | Hand a dev server to Oblivion: it runs it, loads `url` and restarts it when the workspace reopens |
| POST `/server/start` · `/restart` · `/stop` · `/forget` | — | Control the workspace's dev server |
| GET `/device` | — | Connected phones and the ports they can reach |
| GET `/device/console` | — | Console entries from phones |
| POST `/device/screenshot` | `{"path"?}` | Screenshot of the real phone screen |
| POST `/device/reload` · `/device/navigate` | `{"url"}` for navigate | Reload the phone, or load a URL on the phone only |
| GET `/ping` | — | Health check (no token needed) |

### Examples

```bash
# Hand the dev server to Oblivion (runs it, loads the preview, restarts it on reopen)
curl -s -X POST "$OBLIVION_CONTROL/server" -H "x-oblivion-token: $OBLIVION_TOKEN" \
  -H "content-type: application/json" \
  -d '{"command":"npm run dev","url":"http://localhost:5173","cwd":"."}'

# Check the page: console errors, then a screenshot in a phone frame
curl -s "$OBLIVION_CONTROL/preview/console" -H "x-oblivion-token: $OBLIVION_TOKEN"
curl -s -X POST "$OBLIVION_CONTROL/preview/viewport" -H "x-oblivion-token: $OBLIVION_TOKEN" \
  -H "content-type: application/json" -d '{"mode":"iphone-17-pro"}'
curl -s -X POST "$OBLIVION_CONTROL/preview/screenshot" -H "x-oblivion-token: $OBLIVION_TOKEN" \
  -H "content-type: application/json" -d '{}'
```

```powershell
Invoke-RestMethod -Method Post -Uri "$env:OBLIVION_CONTROL/preview" `
  -Headers @{ "x-oblivion-token" = $env:OBLIVION_TOKEN } `
  -ContentType "application/json" `
  -Body (@{ url = "http://localhost:3000" } | ConvertTo-Json)
```

**Screenshots** are saved in `.oblivion/screenshots/` unless you pass `{"path":"shot.png"}` (relative to the workspace). The full-page image is saved next to it as `shot-fullpage.png`. The preview must be loaded and not collapsed.

## AGENTS.md & workspace files

Oblivion adds a few files to each workspace folder:

| File | Purpose |
| --- | --- |
| `AGENTS.md` | Instructions for any agent: the control API, viewport keys, screenshots, dev servers, the phone and mark-ups, plus how to work (start servers with `POST /server`, check the console and screenshot after changes). Created once; safe to edit or delete. Older generated copies get new sections added. |
| `.oblivion/control.json` | The control server address and token for this run. |
| `.oblivion/session.json` | Saved terminals, Claude session ids, preview URL and the workspace's dev server. |
| `.oblivion/server.log` | Output of the dev server Oblivion runs. |
| `.oblivion/screenshots/` | Preview, phone and mark-up screenshots. |
| `.oblivion/.gitignore` | Keeps the whole `.oblivion` folder (including the token) out of git. |

## Keyboard shortcuts

| Keys | Where | Action |
| --- | --- | --- |
| Ctrl++ / Ctrl+\- | Anywhere in the IDE or pop-out | Zoom the preview in / out |
| Ctrl+0 | Anywhere in the IDE or pop-out | Reset preview zoom |
| Ctrl+Z | Mark-up | Undo the last mark |
| Ctrl+Enter | Mark-up | Send to AI |
| Esc | Mark-up | Close mark-up |

## Privacy & security

-   **The control API is local only.** It listens on `127.0.0.1`, requires a random token that changes every launch, and the token file is git-ignored.
-   **Phone connections are encrypted end to end** (WebRTC, DTLS). Setup messages go through a private channel only your signed-in account can read, and a phone must prove it's signed in to the same account before it connects.
-   **Phones only reach the ports you share:** the preview's port and any extra ports you list.
-   **Your agents use your accounts.** Claude Code and Grok run with your own sign-ins; Oblivion doesn't proxy or read your chats. The finished-chat notification reads only the last reply, locally, to show its first line.
-   **Your Oblivion account** (Google sign-in) holds your profile and the list of your PCs, so the phone app can find them.

## Troubleshooting

### Windows says "Windows protected your PC"

Early-access installers aren't code-signed yet. Click **More info → Run anyway**.

### The preview says "No dev server detected"

Nothing answered at that URL. If the workspace has a remembered server, click **Start dev server**. Otherwise ask the agent to start it with `POST /server`, or start it yourself and click **Retry**. Check the dev server menu's log if it keeps failing.

### A terminal says the process exited

The agent quit or crashed. Hover the terminal and click **Refresh**; a Claude chat resumes where it left off. If it exits right away, check that `claude` (or `grok`) works in a normal PowerShell window.

### My PC doesn't show up in the phone app

Check that **Phone preview** is on (phone button in the IDE's top bar), that the IDE and phone are signed in with the **same Google account**, and that the PC is online. Then tap **Refresh** in the app.

### The phone connects but the page won't load

The phone can only reach the preview's port and your extra ports. If your app calls an API on another port, add it under **Extra ports to share**. Make sure the page loads in the IDE preview first.

### I don't get "done" notifications

Check **Notify me when a chat finishes** in Settings and that Windows notifications (and Focus assist / Do not disturb) allow Oblivion. Notifications only appear while you're in another app or workspace. Chats opened before you updated need a **Refresh** first.

### A site in the preview keeps me logged in as the wrong user

Preview logins are kept between sessions. Use **Settings → Preview logins → Sign out of all sites**.

### Does Oblivion work on macOS or Linux?

Not yet. Oblivion IDE Studio is Windows-only; the phone app is Android.

## Release notes

**NEXT** 

#### Finished-chat notifications

-   Windows notification when a Claude or Grok chat finishes while you're elsewhere; click to jump to it.
-   New setting: _Notify me when a chat finishes_.

**1.7.2** 

#### Cleaner preview toolbar

-   One viewport button for Desktop, phones and tablets; the address bar hides `http://` so the host and port fit.
-   The mark-up toolbar fits on two rows; the dev server menu is less cluttered.
-   Removed the _Default preview URL_ setting; each workspace reopens on the page it last showed.

**1.7.1** 

#### Internet-only phone connection

-   Phones connect only over the internet (Wi-Fi or mobile data). The local Wi-Fi server and its port are gone.

**1.7.0** 

#### Dev servers that come back

-   Each workspace remembers its dev server and starts it again when it reopens, with a server menu in the preview toolbar.
-   Agents hand servers over with `POST /server`.

**1.6.0** 

#### More devices

-   New frames: iPhone 16, iPhone Air, iPhone 17 Pro Max, Pixel 9a, Pixel 9 Pro, Galaxy S25 Ultra, iPad Air 11" and iPad Pro 13".