On My Radar
On this page

Guides Agents and MCP

omr-agent setup

Install omr-agent so Claude Code or Codex starts every session in a workspace already running as one of your On My Radar agents, and see what a checkout puts in your repo.

Updated October 30, 2026 · Checked against On My Radar build 2c4905d

After this page you can make a Claude Code or Codex workspace start every session as one of your On My Radar agents, with its prompt and memory already loaded, and you will know which files that adds to your repository.

What omr-agent is, and whether you need it

omr-agent is one JavaScript file that needs Node.js 22 or newer and no other packages. It does three jobs:

  • Loads the agent before the first turn. A start-up hook in your tool runs omr-agent boot, which calls load_agent and hands the result to the tool. The model does not have to remember to do it.
  • Connects the tool to On My Radar. omr-agent mcp is a local bridge to the same server, using the same login. A load session belongs to the connection that opened it, so the model must write through the connection that loaded the agent.
  • Keeps memory out of local files. An advisory guard refuses writes to places where tools keep their own memory, so the agent's memory stays in On My Radar.

You do not need it to use an agent. Without it, a workspace holds a short block of instructions that asks the model to call load_agent itself. That works, but a model can skip it. See "What a checkout adds to your repo" below.

The quick way

  1. Open Agents and choose Connect a tool. Pick the agent and the tool, then Continue setup. (From an agent's page, the Connect a tool… menu goes straight to the same dialog.)
  2. In step 1, Connect On My Radar to your tool, choose Copy setup prompt. It copies one sentence:
Fetch and execute the appropriate instructions to set me up for On My Radar from https://onmyradar.io/agent-setup/prompt.md for Claude Code — agent id: <uuid>
  1. Paste it into Claude Code or Codex. The tool follows the steps below.
  2. Approve access in the browser when asked. Start a new session in the tool.

Copying the prompt does not connect anything by itself. The Check connection button in step 3 turns to "Connection verified" when a new session from your account arrives.

Note: Claude on the web has no setup prompt. For it the dialog shows the manual steps only. See Connect your agent.

What the setup prompt does

prompt.md is a fixed page on onmyradar.io that is the same for everyone and holds no user content. It tells the tool to:

  1. Check that Node.js 22 or newer is installed.
  2. Download omr-agent.mjs and check its SHA-256 against SHA256SUMS. If they differ, delete the file and stop.
  3. Run login.
  4. Connect the tool: install the plugin for Claude Code, or run install --harness codex for Codex. For any other tool, add the MCP server by hand and use checkout_agent.
  5. If it was given an agent id, run use to point the workspace at that agent.
  6. Report what changed. It does not switch the current session to the agent. The next session starts as the agent.

The prompt also tells the tool never to print, ask for or store a token, and to download only from https://onmyradar.io/agent-setup/. If a step fails it tells the tool to diagnose and fix it while keeping the checksum check. The commands described below are stricter than the prompt: install and use always show a change first and write only with --yes.

Setting it up by hand

1. Download and check the file

mkdir -p ~/.config/omr/bin && curl -fsSL https://onmyradar.io/agent-setup/omr-agent.mjs -o ~/.config/omr/bin/omr-agent.mjs

Fetch https://onmyradar.io/agent-setup/SHA256SUMS and compare it with shasum -a 256 ~/.config/omr/bin/omr-agent.mjs.

2. Log this machine in

node ~/.config/omr/bin/omr-agent.mjs login

Your browser opens On My Radar's consent screen. The login asks for radars:read radars:write only, never radars:manage. It registers an app named omr-agent on <your machine name>, which then appears under Connected apps in Settings, Connections. The login waits five minutes for you to approve.

The token goes into the operating system keychain: the macOS Keychain, or secret-tool (libsecret) on Linux. If there is no keychain, set OMR_TOKEN_STORE=file to keep it in a file readable only by you, ~/.config/omr/credentials.json. Check with:

node ~/.config/omr/bin/omr-agent.mjs status

It prints the server, the store, login: yes or login: no, and the nearest .omr/agent.json.

3. Connect your tool

Claude Code. Install the omr plugin:

claude plugin marketplace add https://onmyradar.io/agent-setup/marketplace.json
claude plugin install omr@onmyradar

The plugin loads the workspace's agent when a session starts, on a clear and after compaction, but not on resume. It also provides the On My Radar MCP server as omr, so you do not add a separate entry.

Codex. Run:

node ~/.config/omr/bin/omr-agent.mjs install --harness codex

This prints what it would change in ~/.codex/config.toml and writes nothing. Check the diff, then run it again with --yes. It adds one managed block with an omr MCP server and a session-start hook, copies itself to ~/.config/omr/bin, and keeps a copy of the old file as config.toml.omr-backup. It first asks Codex itself to load the file, before and after the change, and writes nothing if either fails. Use --dry-run to preview and --codex-home <dir> for a different Codex directory. Codex asks you to trust the new hook at its next start. Choose to trust it, or it will not run.

Other tools. omr-agent cannot hook them. Add the server as in Connect your agent, then use checkout_agent.

4. Point a workspace at an agent

From inside the repository:

node ~/.config/omr/bin/omr-agent.mjs use --agent <uuid> --harness claude-code

Use --harness codex for Codex. This writes only .omr/agent.json, after showing the change. Add --yes to write it. The next session in that directory, or below it, starts as the agent.

What a checkout adds to your repo

Whether done by use, by the Connect a tool dialog or by an agent calling checkout_agent, the files are pointers. They hold the agent's handle and id. A helper file also carries the agent's one-line description and its tool settings. No file holds a password. They hold the prompt or memories only if a checkout is requested with the snapshot option, through checkout_agent or the API. It is off by default and writes a read-only copy of the prompt, memories and briefs under .omr/snapshot/<handle>/. The Connect a tool dialog has no such option.

In the default mode, where the agent runs the whole project, .omr/agent.json is written. use writes only this file. Claude on the web and the helper mode below write no .omr/agent.json:

{
  "version": 1,
  "server": "https://onmyradar.io/mcp",
  "agents": [
    { "id": "<uuid>", "slug": "<handle>", "role": "primary", "prompt": "live" }
  ]
}

The dialog and checkout_agent also write a second file, which depends on the tool. The instructions in it tell the model to call load_agent with the agent id, the tool's name and the workspace, adopt the prompt it returns, treat memories as notes, and save memory only with agent_remember and agent_forget.

  • Claude Code: .omr/AGENT.md and a CLAUDE.md that contains @.omr/AGENT.md.
  • Gemini CLI: .omr/AGENT.md and GEMINI.md.
  • Codex, Copilot, Zed and other tools: an AGENTS.md block. Zed adds it to the first rules file it reads.
  • Cursor: .cursor/rules/omr-agent.mdc.
  • Windsurf: .windsurf/rules/omr-agent.md.
  • Claude on the web: no files. You paste a block into a Project's instructions, or choose the agent from the connector in a chat.

In the dialog's step 2 you choose This project runs as the agent (primary) or Available as a helper (a subagent, in tools that have them). That choice changes which files are written. Helper mode writes a tool-native file such as .claude/agents/<handle>.md and carries the agent's profile settings. Change those settings in the agent's Tools tab, not in the file, because the next checkout rewrites it.

If you would rather add the files yourself, the dialog's Or add the files yourself lists each file with a copy button. Ticking Also apply these settings to the project also merges the profile into a shared settings file such as .claude/settings.json. That affects everyone on the repository.

Commit the files if you want everyone who works in the repository to get the same agent. People without access to the agent in On My Radar cannot load it. With omr-agent they see a "NOT loaded" notice, and the model is told not to act as the agent. Do not commit them if the agent is only for you. Add them to your ignore file instead.

To run a fixed prompt version, set "prompt" to a whole number such as 3 in .omr/agent.json, instead of "live". An agent shared with you runs the version you accepted, unless you turned on Follow updates for it.

Headless machines, SSH and CI

omr-agent's login needs a browser on the same machine. The setup prompt says a headless login over SSH is unsupported. The server does not offer the device sign-in that a browserless login would need, so login --device, which the tool picks by itself when SSH_CONNECTION is set, stops with "does not offer the device grant yet". OMR_TOKEN_STORE=file changes where the token is kept, not how you log in.

For CI or a server, do not use omr-agent. Use a personal access token with the tool's own MCP configuration. Codex reads it from the environment with bearer_token_env_var. See Connect your agent and Tokens, scopes and revocation.

When loading fails

The hook fails closed. If it cannot load the agent, it says "On My Radar agent <handle> was NOT loaded", gives the reason, and tells the model not to act as the agent and not to rebuild its memory from local files. It fails closed when the server cannot be reached, the login is missing or refused, the agent is archived or no longer shared, .omr/agent.json is malformed, Node.js is too old, or loading takes more than 15 seconds.

Failing closed means the model is told. It does not necessarily stop the session. Read the first lines of the session.

Another failure is size. Claude Code accepts at most 10,000 characters from one hook, so the plugin splits the load over four hooks of up to 9,500 characters. The agent's header, prompt and tool addendum are never cut. If they need more than the four hooks hold, which is roughly 36,000 characters, loading fails rather than loading half a prompt. Codex takes the load in one piece.

Other commands and safety

  • logout removes this machine's login. To revoke it on the server too, choose Disconnect on omr-agent on <machine name> in Settings, Connections.
  • version prints the version, currently 0.3.0.
  • mcp --allow <tool,tool> and mcp --all-tools widen the bridge. By default it offers only the agent's own tools, blips, comments and notifications. Delete, share, membership, webhook, feed, dashboard, prompt-edit and import or export tools are refused by the bridge before they reach the server.
  • Credentials go only to https://onmyradar.io. A repository cannot redirect them, because login ignores .omr/agent.json. Someone running their own server adds it to OMR_ALLOWED_SERVERS in their own environment.
  • The memory guard is advisory. It stops file tools and obvious shell commands from writing memory files. A command that builds its path at run time can get past it.
  • The start-up shim is POSIX sh. On Windows you need Git Bash or WSL, and that setup is untested.

Next