Realm

One workspace for every coding agent, on your Mac.

realm.computer  ·  Download  ·  iPhone app (TestFlight)  ·  Changelog

macOS · Apple silicon · in active development

!Realm's window floating beside a lit realm in deep space: every space in the sidebar under Needs you, a session that fixed a crash with the card for the two files it edited, and the file its answer named open in the side panel at the line it named.

Every space in the sidebar, a session and the two files its turn edited, and the file its answer named, open beside it at the line it named.

Local-first agent control plane for macOS — profiles → spaces, every space in one sidebar, split panes for sessions beside one side panel for terminals / browsers / devices / documents, a context pool, and an MCP gateway. See docs/superpowers/specs/2026-08-17-realm-v1-design.md.

Architecture

docs/architecture is the map of how Realm is built: every process and the lines between them, every package and who depends on whom, and the stack layer by layer with its versions. features.md follows each feature through it, one drawing each, and realm-architecture.html is the whole system as a poster you can pan and zoom.

Dev

• Node ≥ 22.13, pnpm 10, macOS.
• Hugeicons Pro token in .npmrc (see .npmrc.example), if you have one; see below if you do not.
• pnpm install && pnpm dev
• Tests: pnpm test · Types: pnpm typecheck
• Data lives in ~/Realm/ (override with REALM_HOME).

Building without the Pro icons

The icons come from Hugeicons Pro where there is a token for Hugeicons' registry. Without one there is nothing to set up: pnpm install skips the Pro pack, which is optional, and the app draws the free @hugeicons/core-free-icons pack (MIT) under the same names. At the pinned version those are the same glyphs.

git clone https://github.com/31Carlton7/realm.git && cd realm
pnpm install --frozen-lockfile
pnpm build

The build prints [hugeicons] the Pro pack is not installed; drawing the free pack when it is drawing the free pack. docs/dev/hugeicons.md has the rest.

Website

site/ is the marketing site and docs (Next.js, deployed on Vercel with Root Directory = site). It is deliberately outside the pnpm workspace and carries its own lockfile — see site/README.md for why that matters and how to verify the WebGPU hero shader headlessly.

Agent sessions

• Claude sessions run on @anthropic-ai/claude-agent-sdk, which drives the claude CLI: install it and log in first (claude auth login). An expired login shows up as an error in the transcript.

• ACP agents — Cursor, Gemini, OpenCode, GitHub Copilot, goose, Qwen Code, Grok and fx all speak the

• Offline / UI work: REALM_ENABLE_FAKE_AGENT=1 pnpm dev registers a scripted Fake agent (echoes what you send) in the model picker.
• MCP gateway — third-party MCP servers are configured in a space's settings, not per-agent: every session gets one Realm gateway endpoint, and credentials or OAuth tokens never reach the agent CLI. Every proxied tool call shows up in the Activity view (Connections ▸ Activity, or "MCP Activity" in the command palette).

Command line (realm)

apps/server/bin/realm runs Realm's server and drives it from a shell, with no window. It talks to the server on a home (--home, else $REALM_HOME, else ~/Realm) through the port and token in that home's daemon.json, so a running app and a script see the same spaces, worktrees and terminals: a command started with realm run shows up in the sidebar as a terminal.

realm serve &                                   # the server alone, headless (ready in under a second)
realm repo add ~/code/app                       # a checkout as a project; idempotent
realm run ~/code/app --worktree fix-login -- claude -p "fix the login bug"
realm ps                                        # every terminal: running, exited N, or killed (signal N)
realm wait --timeout 600                        # exit 0 only if every command exited 0
realm logs <terminal>; realm kill <terminal>
realm ship <checkout> --message "Fix the login bug" --pr   # commit it all, push the branch, open a PR

realm ship takes the checkout's id, which realm run --json prints as environmentId and realm worktree list prints first. It stages every change in that checkout, as the Changes pane's Stage all does, and commits it. --push also pushes the branch, setting its upstream when the remote has never seen it, and --pr pushes it and opens a pull request with gh. Where gh is missing or not signed in, it prints the GitHub link that makes the pull request instead. It is the same commit, push and pull request the Changes pane makes, and it lands in the space's History beside theirs. It exits 0 only when every step it was asked for happened, so 1 means nothing to commit (and nothing to push), a push the remote refused, or a pull request it could only link to.

--json makes every command print one JSON document. Every packaged app ships the command at /bin/realm and runs it on the app's own binary as Node, so it needs no Node install and no display: Realm.app/Contents/Resources/bin/realm, squashfs-root/resources/bin/realm in an AppImage extracted with --appimage-extract, /opt/Realm/resources/bin/realm from the deb, and resources\bin\realm.cmd on Windows. From a checkout it uses node (22.13+) on dist/realm.js after pnpm --filter @realm/server build. realm run with --worktree puts each command in its own worktree on realm/, with that worktree's port block in its environment.

A server on another machine

realm serve runs anywhere Node 22.13 runs, Linux included, and keeps agents working with your laptop closed. On a Linux machine, from a checkout: pnpm install, pnpm --filter @realm/server build, then link apps/server/bin/realm onto your PATH (on a Mac, link Realm.app/Contents/Resources/server/bin/realm). It listens on loopback only unless you add --listen. A client on another machine then needs an access token, made on the server:

# on the server
realm token create laptop            # prints the token once; only its hash is kept
realm serve --tailscale              # tailnet only: Tailscale Serve's HTTPS in front of 127.0.0.1:7420
on the laptop
realm remote add vps wss://vps.tail1234.ts.net     # paste the token when asked
realm --server vps run /home/me/app --worktree fix-login -- claude -p "fix the login bug"
realm --server vps wait --timeout 600; realm --server vps logs <terminal>

Three ways to reach it, from the most to the least recommended:

• Tailscale Serve: realm serve --tailscale [--tailscale-port 443] listens on 127.0.0.1:7420 and

• An SSH tunnel: realm serve --listen 127.0.0.1:7420 on the server, ssh -N -L 7420:127.0.0.1:7420

• TLS on an open port: realm serve --listen 0.0.0.0:7420 --tls-cert cert.pem --tls-key key.pem

What it refuses:

• Listening on every address (0.0.0.0, ::) or a public address without TLS. No flag allows it.
• Listening on a private address (a LAN, a tailnet IP) without TLS, unless you pass

• On the client, sending a token over ws:// to anything but this machine, without --allow-plaintext.
• Any handshake without a valid access token, including the server's own daemon.json token, and any

• An address after ten refused handshakes in a minute: it is refused for a minute, valid token or not.

Saved remotes live in ~/.config/realm/remotes.json (mode 0600; a file other users can read is refused). --server also takes a URL with --token, or $REALM_SERVER and $REALM_TOKEN. With --server, paths are the server's and must be absolute. Agent CLIs run on the server, so sign them in there once, over SSH.

Pairing an iPhone with a server that has no window

realm pair                           # draws the pairing code in the terminal, then asks before pairing
realm phones; realm phones remove <id|name>

realm pair works on the server or with --server. A server started by realm serve has no Realm app to unlock the Keychain, so it keeps its phone identity sealed with its own key, in /keys/remote.key (0600), or in the file $REALM_REMOTE_KEY_FILE names, such as a systemd credential. Anyone who can read that home can read the key. The app opens what a headless server paired. A headless server never replaces an identity the app sealed with the Keychain: it says to open Realm on that Mac once.

Running it as a service

realm service install --tailscale    # or any realm serve options; status, uninstall

On Linux this writes ~/.config/systemd/user/realm.service and enables it. Run loginctl enable-linger $USER to keep it running when you are logged out. On macOS it writes a launchd agent, ~/Library/LaunchAgents/co.charmtechnologies.realm.server.plist, which logs to /logs/service.log. The file runs the exact Node and realm.js you installed it from, so install again after moving either.

Code graphs (Graphify)

Graphify extracts a queryable knowledge graph from a checkout. It is a Python CLI, installed out of band like the agent CLIs — Realm probes for it and never installs it.

• Install it with the mcp extra: uv tool install "graphifyy[mcp]". A plain

• graphify.probe / graphify.update are Realm's own RPC methods, not agent kinds — graphify

• As an MCP server, add it in a space's Connections: transport stdio, command graphify-mcp,

• The rendered graphify-out/graph.html opens in the documents pane. graphify points its only

• Proof: pnpm --filter @realm/server exec tsx scripts/live-graphify-check.ts drives the real CLI,

Saved sign-ins (browser panes)

An agent driving a browser pane can sign you in to a site without ever seeing the password.

• You enroll your own passwords in Settings → Sign-ins. That is the only path for a value you

• An agent can ask Realm to GENERATE one, with browser_fill_credential's generate argument

• Values live in the OS Keychain, encrypted by Electron's safeStorage

• Every fill is gated three ways: the pane's current origin, read from CDP, must exactly equal the

• Typing into a password field with browser_act is still refused, in every mode.

• Two-factor is not automated, and will not be. A Duo/Okta push cannot be driven from here, and a

• A Mac without a Touch ID sensor can save sign-ins but cannot fill them: promptTouchID is

Packaging

• pnpm dist — full build + DMG and zip in apps/desktop/release/ (pnpm dist:dir stops at an

• pnpm app:update — the fast local update loop: builds the unpacked app, gracefully quits the

• No system Node needed: the packaged app runs realm-server under its own binary with

• Proof: node apps/desktop/scripts/packaged-smoke.cjs launches the packaged binary with a

• Unsigned by default: with no signing credentials in the env, pnpm dist builds an unsigned,

Releasing

• pnpm release — bumps the app version (patch; --minor / --major for more), prepends a

Updates

• Signed packaged builds check the public GitHub release feed on launch, download a newer version

• Public releases must carry the dmg, zip, and latest-mac.yml artifacts produced by pnpm release.

• The hard gate in apps/desktop/src/main/updater.ts still disables updates in development and in

Importing from the agent CLIs

Settings → Import brings what Claude Code, Codex and Cursor already have on disk into Realm: transcripts, the Claude memory tool's per-project fact folders, and user-level skills.

• The agents' directories are read-only. ~/.claude, ~/.codex, ~/.cursor, ~/.agents and

• import.scan writes nothing. It opens files, matches candidates to spaces and answers; no

• Space matching is most-specific-location-wins (apps/server/src/import/match.ts): walking the

• Imported sessions keep their provider id when the recorded cwd still exists, so sending a

• Memory is not flattened into the space doc. Fact files are copied to

• Skills are copied, never symlinked or overwritten, and land unscoped — visible in every space,

One transcript is not one file. Codex rewrites a whole thread into a new rollout file every time it is resumed — on one machine here, 241 files were 71 conversations, with 158 of them replays of a single Stora thread. The scan keeps the fullest copy of each and counts the rest, so the panel offers conversations rather than files.

Two scripts, from apps/server:

• tsx scripts/live-import-check.ts — prints what an import would do against this machine's real CLI

• tsx scripts/undo-import.ts --all-imported --sweep-environments — takes an import back out. Only

Screens

Real captures of a real space, taken against the built app by site/scripts/capture-product.mjs, then framed as the site frames them and laid on an opaque ground by site/scripts/capture-brand.mjs — the window is made of translucent material, so a capture laid straight onto GitHub's white theme washes its sidebar out.

Every space, in one sidebar. Each space is a section of one list, and Needs you heads it with every session waiting on a permission or a question, from every space and every profile.

!The sidebar: Needs you lists two questions, one from another profile, above the Realm, Dashboard, Site and School spaces and their sessions.

Two questions waiting on you, one from another profile, above every space's sessions.

Bring the agent you already use. Claude Code, Codex, Cursor, Gemini, OpenCode, GitHub Copilot, goose, Qwen Code and Grok all run here, each keeping its own login, models and permission modes.

!The model picker open on a new session: Claude's and Codex's models grouped by harness, Opus 5.5 picked with its description, context and price, and the effort track at Max, lit, with fast mode on.

Every installed agent's models in one list: Opus 5.5 picked, at Max, with fast mode on.

Your tools, without your credentials. Connections belong to the space rather than to an agent, so a session is handed the tools and never the token — it calls Realm, and Realm calls the server.

!The Connections page, showing Linear, Notion, Slack, GitHub, Jira & Confluence and Figma as cards, each with what it grants and a Connect button.

Connecting an app to a space. One click each, and every session in the space can use them.

Confine what an agent can touch. A space can put its agents and terminals behind a macOS Seatbelt policy. It ships off, per space — Seatbelt is not a container, and the network stays open.

!The Sandbox settings page for a space, showing its three postures — Workspace write, Read only and No sandbox — with No sandbox selected.

The three postures a space can take, on the one it ships with.

Skills

skills/ holds skills Realm ships, one folder per skill, laid out exactly like the library at ~/Realm/skills/ (spec §7) so installing one is a copy. SkillSync — per-profile enablement and the symlink into each session's .claude/skills/ — is not built yet, so until it is, enable a bundled skill by hand:

ln -s "$PWD/skills/mac" ~/.claude/skills/mac

• study-guide / lecture-notes — the school workflow (Plan 22): how to write a self-contained

• mac — the mac-cli binary: Calendar, Reminders, Contacts, Mail,

License

Realm is released under the MIT License. A few bundled parts (file-type icons, the iOS device runner, the Inter and JetBrains Mono fonts) keep their own licenses; THIRD-PARTY-NOTICES.md lists them.