For developers

Developer reference

Reach Jevie from outside the palette: jevie:// links, an MCP server for your coding agents, long-run hand-offs, your files, extensions, script commands and background agents.

Choose an example to copy it, then try it in Jevie.

Links: jevie://The MCP server Handing off a long run Your Jevie files Extensions Script commands MCP servers Jevie calls Background agents Limits Environment switches

Links: jevie://

Use from Shortcuts, a script (open "jevie://ask?q=dark%20mode&run=1"), a hotkey or a page. Query values are URL-encoded.

URL	What it opens or does
`jevie://ask?q=…`	The palette with that sentence typed in
`jevie://ask?q=…&run=1`	The same, and the sentence is run
`jevie://toggle`	Opens or closes the palette, as `⌘ Space` does
`jevie://voice`	Starts talking to Jevie, as `⌘⌘` does
`jevie://update`	Checks for an update now, and installs what it finds
`jevie://about`	The About Jevie panel
`jevie://uninstall`	Uninstall Jevie…, asked first
`jevie://onboarding`	The first run again, from the start
`jevie://onboarding?page=…`	The first run at one of its pages, for example `page=voice`
`jevie://setup`	The Setup window; `?step=N` opens one of its cards
`jevie://notice?title=…&detail=…`	A notice from Jevie; optional `kind`, `says` (the sentence a click runs) and `sound`
`jevie://appearance?mode=…`	The look: `light`, `dark`, `black`, `graphite`, `system`, `transparent`, `glass`, `aurora`
`jevie://appearance?tint=…`	The tint: `none`, `ember`, `amber`, `tide`, `ocean`, `frost`, `rose`, `dusk`, `moss`
`jevie://theme?mood=…`	A look made from a mood, such as “tokyo at 2am”; without `mood`, the theme picker
`jevie://sounds?on=0`	Jevie’s sounds off (`on=1` back on); also `volume` and `theme`
`jevie://terminal?command=…&cwd=…`	Jevie’s terminal running that command in that folder; alone, a shell
`jevie://wall`	The session wall on this Space; `?layout=spiral` (or `chain`, `main`, `columns`, `rows`, `grid`) lays it out again, `?desktop=N` goes to that desktop’s wall
`jevie://browse?url=…`	Jevie’s own browser on the wall, at that page (repeat `url` for several)
`jevie://tile?do=on`	The live tiler on (`off`, a layout, and its other commands)
`jevie://ink`	Draw over every screen
`jevie://email?id=…`	That email, opened in the palette

jevie://note/…, jevie://page/…, jevie://bookmark/…, jevie://file/… and the like open that item; your pages link and embed with them (mail, calendar and notes). Any other jevie:// link opens the palette. A hotkey whose sentence is a link opens it directly (your Jevie files).

The MCP server

Gives your coding agents your logged-in browser, mail, calendar, files and memory; anything outward still asks you in the palette.

connect jevie to my agents · Registers Jevie with Claude Code, Codex and Gemini CLI where their settings exist (run each once first); an existing jevie server is left alone.
Sessions Jevie starts carry the server, even agents without MCP settings, such as pi.

Tool	What it does
`jevie_ask`	Asks Jevie one plain sentence, as you would type it; waits for a background task up to `wait` seconds
`jevie_task`	Follows a background task by its id: its plan, questions and result
`jevie_capabilities`	What Jevie can answer on this Mac: its areas and installed extensions, with example sentences
`jevie_execute`	Runs a short JavaScript program against your MCP servers, Jevie’s extensions and Jevie itself; a tool that only reads runs at once, anything else asks you first
`jevie_recall`	Searches what you said to Jevie and in Claude Code sessions in the last 14 days, and the agents’ replies; `answer: true` for a short cited answer
`jevie_zoom`	Opens one entry of that record by its name, such as `6958+1`
`jevie_screen`	Opens a screenshot that recall found: its text, and the picture only when asked
`jevie_file_search`	Searches file names, or the text inside files under a folder, from Jevie’s index
`jevie_files`	Lists, reads, checks and writes your Jevie files (below)
`jevie_interface`	Keeps an interface an agent wrote as a Jevie app you open by name
`jevie_run`	Runs a long command in the background and wakes the session when it ends (below)
`browser_…`	Your own Chrome for an agent loop: open, read, find, click, fill, scroll, screenshot and more; consequential presses follow the same approvals as Jevie’s own

Keys never reach the agent: jevie_execute calls tools through Jevie, and a write waits up to two minutes for your yes.

Handing off a long run

An agent hands Jevie a long command and ends its turn; when it ends, the session is told the exit code, time, output path and what to do next (wakes). Example: ~/.jevie/bin/jevie-run --wake "fix any failures" -- npm run test:all.

Option	What it does
`--wake "…"`	What the session is told to do when the command ends
`--to self`	Wake the session the command was run from (the default)
`--to none`	Tell you instead, with a notification
`--to acp:<id>`	Wake a background Codex, Gemini or OpenCode session
`--cwd <folder>`	Run the command in that folder
`--list`	The runs and wakes still waiting

Same as the jevie_run MCP tool. Output in ~/.jevie/runs/, waiting wakes in ~/.jevie/wakes/.

Your Jevie files

~/.jevie/self: plain markdown, each change a git commit, read back within a second; saying a change edits the file (your Jevie files).

File	What it holds
`SOUL.md`	How Jevie talks
`RULES.md`	Your standing rules
`USER.md`	What you told Jevie about yourself
`MEMORY.md`	What Jevie learned, and what it must not learn again
`routines.md`	Your names for several sentences (routines)
`snippets.md` · `quicklinks.md`	Snippets and quicklinks (snippets and quicklinks)
`vocabulary.md`	Word fixes and names for dictation to listen for
`hotkeys.md`	Sentences on global keys
`AGENTS.md`	How an agent should edit the rest

Agents may change your lists, USER.md and MEMORY.md over MCP, not SOUL.md, RULES.md or what agents may do unasked. check my files names unreadable lines. API keys are never here; they live in the Keychain (keys and accounts).

Extensions

A folder ~/.jevie/extensions/<id>/ with a jevie-extension.json manifest and an .mjs entry. It adds tools, commands, surfaces or an MCP server; Jevie still decides meaning and asks before changes.

Manifest field	What it is
`id`	The package’s name; its tools are reached as `@ext-<id>`
`apiVersion`	`1`
`version`	The package’s own version
`description`	One line, shown in lists and to your agents
`entry`	The `.mjs` file whose default export receives the `jevie` object
`topics` · `examples`	Words and sentences that help Jevie offer it

Example: jevie.registerTool({ name: 'hello', readOnly: true, inputSchema, execute: ({ name }) => 'Hello, ' + name }). execute returns a string, data or an MCP-style result, drawn as Jevie's rows, tables and documents.

To add	Use
An operation with structured arguments	`registerTool`
A named command that takes the trailing text	`registerCommand`
Your own objects and their operations	`registerSurface`
An existing MCP service	`registerMcpServer`
Lifecycle and cleanup	`on`, `onDispose`

reload extensionsAfter changing one on disk; it approves what it reloads
extensionsWhat is loaded, disabled or failed
approve extension greeting · disable extension greeting · enable extension greeting
@ext-greeting The package’s tools and commands
make me an extension that shows my github notificationsYour coding agent writes one as a draft, Jevie checks it, and install extension <id> installs it

A package loads only as approved; one changed on disk waits for approval. Each runs in its own process with your permissions: not a sandbox, so install code you trust.

Raycast extensions run with List, Detail, Form, Action and command on the same jevie object (extensions and MCP).

Script commands

Raycast Script Commands work unchanged: say the title, words after it are arguments. Header: # @raycast.schemaVersion 1, # @raycast.title Toggle Dark Mode, and optionally # @raycast.mode silent (or compact, inline, fullOutput) and # @raycast.argument1 { "type": "text", "placeholder": "name" }.

Put them in ~/.jevie/script-commands, or say add script folder ~/raycast-scripts. script commands lists them.

MCP servers Jevie calls

Your servers go in ~/.jevie/mcp.json; Codex, Claude Code, Claude Desktop or Cursor servers are used only when listed under its import. Call one written out (@git git_log repo_path=~/code max_count=5) or in words (@github my open pull requests). Read-only tools run at once; others wait for a yes (extensions and MCP).

Background agents

Codex, Gemini CLI and OpenCode run as terminal-less sessions over the Agent Client Protocol.

start codex in the background: fix the flaky date testA session with no terminal; its steps arrive as events
tell codex: run the tests tooA turn sent to it

Permission prompts come to you (Allow, Deny, Always), following the folder's approvals (approvals); each session gets Jevie's MCP server. The agent must be installed and signed in; Jevie never signs in for it. Claude Code uses its hooks instead (coding-agent sessions).

Limits

Codex is the agent seen working over ACP; Gemini CLI and OpenCode follow the protocol but have not been tried with Jevie yet.
A second turn sent while a background agent is still working is refused.
When Jevie restarts, background agents stop with it; the next turn sent to one starts it again where it was.
jevie-run watches only commands started with it.

Environment switches

Variable	Effect
`JEVIE_SELF`	Where your Jevie files live
`JEVIE_EXTENSIONS=0`	Extensions off
`JEVIE_MCP=0`	Jevie’s MCP client off
`JEVIE_GENUI=0`	Answers as components off
`JEVIE_SESSIONS_IN=background`	Every coding session Jevie starts runs in the background
`JEVIE_TEAM=0`	Team rooms off, whatever your files say

Updated 23 October 2026 · Something wrong or missing? Tell us