Oblivion IDE documentation

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.

#Install

Oblivion IDE Studio is in early access. Join the list at oblivionide.com 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.

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.

#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.
3. Terminals open. Two by default, each starting Claude Code (change this in 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.

#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.

#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:

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

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.

#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.

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.

#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).

#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 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.

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.

#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.

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.

#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

Examples

# 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 '{}'

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)

#AGENTS.md & workspace files

Oblivion adds a few files to each workspace folder:

#Keyboard shortcuts

#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

#Release notes