omp-agents

A local web dashboard for every omp session and subagent on your machine.

omp-agents lists the sessions that run in your terminals and the ones it starts itself, streams each conversation as it happens, and lets you message, steer, interrupt, resume, or fork any of them from one browser tab. It reads omp's own session files and speaks omp's own protocols through omp's installed modules, so it stays in step with the omp version you run.

Contents

• Features
• Requirements
• Quick start
• Configuration
• Usage
• How it works
• Security
• Contributing
• License

Features

• Live roster. Every running and past session, with a status dot (running, idle, or waiting on a question), filtered by workspace. Pin a session to keep it at the top in every window, and let a routine pin the session it just finished in place of its last one. Sessions that stopped when the dashboard went down wait in an interrupted group, and Resume all brings them back. Claude Code and Codex sessions on the same machine list beside omp's, as read-only transcripts you can search.
• Session details. The focused conversation's todo list, the files its agent changed with each file's latest diff, the live session's subagents as a tree, and every screenshot and image its agents' tools returned; subagents also open from the task call that spawned them, and a back arrow returns to the session.
• Live conversations. Streaming Markdown transcripts, tool calls, and context-window usage, in up to four split panes.
• Full control. Prompt, with images attached, dropped, or pasted, steer, queue follow-ups, interrupt, answer ask questions and extension dialogs, message and cancel subagents, run ! shell and built-in / commands in a session the dashboard started, switch model and thinking level, end sessions.
• Next-prompt suggestions. When omp ends a reply with a Suggestions: block, as the starter kit's system prompt asks it to, the composer lists them; press a number key to send one, or pick one with ↓ and ↑.
• Session lifecycle. Start a session in any workspace, on any branch or a new one in its own git worktree, resume a past one, or fork a conversation from any prompt or reply. Ending a session removes the git worktree it worked in, and keeps its branch and any worktree with uncommitted changes. An agent can end its own session through the starter kit's end_session tool, so "Merge on main, then end the session" needs no follow-up.
• Session processes. A live session's dev servers, watchers, and omp broker services, biggest memory first, each with a Stop button; the server stops them once their sessions have been idle for 30 minutes, or a time you pick, and when their session ends.
• Pull requests. A Graphite-style list of your GitHub pull requests, sorted by whose move it is and linked to the sessions that submitted or worked on them.
• Linear tickets. The Linear issues assigned to you, grouped by workflow state like Linear's My issues, read through omp's Linear MCP sign-in. Click one to read it in full, and start a session that works on it or plans it.
• Slack. Search, history, and sending in Slack from every omp session, through Slack's MCP server at https://mcp.slack.com/mcp. Save a dedicated internal Slack app in Settings › Integrations, then connect it.
• Calendar. A month of routine runs, due todos and Linear tickets, and your Google Calendar's events, read with omp's sign-in to Google Calendar's MCP server.
• Inbox. Your Gmail inbox's latest conversations, with a rich-text editor to reply and write new mail, and Delete to Trash, each opening in Gmail, read with omp's sign-in to Gmail's MCP server.
• Several Google accounts. Connect more than one Gmail and Google Calendar account; the Inbox and the Calendar merge them, tagged by address, and an address you link to workspaces shows only in those and under All workspaces. omp sessions are told, through the starter kit's google-accounts extension, which account each MCP server signs in as and which one their workspace links.
• Your own todo list. Categories, due days with a Today list, drag-to-reorder, search, and an archive with undo. A todo links to the sessions, pull requests, and Linear issues it is about, starts a session or opens a Linear issue from its notes, and agents add the steps only you can take through the starter kit's user_todo tool and check off a todo once they finish its work. The desktop app captures a todo from any app and badges the Dock with what is left.
• Notes. Markdown notes with search, optional todo links, and Undo, shared with agent sessions through the starter kit's user_note tool.
• Settings editor. Edit omp's model roles, fallback chains, retry settings, and context files (AGENTS.md, config.yml, skills, rules) in place, and pin a skill that every new session starts through.
• Plan quota. Remaining quota per provider plan, from omp usage.
• Keyboard-first. Shortcuts that follow omp's terminal keys; press ? to list them.
• omp starter kit. An optional, ready-made omp setup (model routing, agent rules, a review agent, a /ship workflow, skills) that one command installs.

Requirements

• Bun 1.4 or later. Tested with Bun 1.4.2.

• omp installed with Bun and on your PATH, signed in to at least one model provider with /login. Tested with omp 18.12.3.

  bun install -g @oh-my-pi/pi-coding-agent

• Optional, for the pull request list: the GitHub CLI (gh), signed in with gh auth login.

• Optional, for the Linear tickets: Linear's MCP server added to omp (/mcp add with https://mcp.linear.app/mcp) and signed in.

• Optional, for Slack in omp sessions: a dedicated internal Slack app, with the MCP server and token rotation turned on, an HTTPS redirect, and the user scopes you choose, saved from Settings › Integrations.

• Optional, for Google Calendar: a Google OAuth client of type Web application, with the Google Calendar API turned on, saved from Settings › Integrations.

• Optional, for the Inbox: a Google OAuth client of type Web application, with the Gmail API turned on, saved from Settings › Integrations; the Google Calendar client works too.

Quick start

git clone https://github.com/MaisonnatM/omp-agents.git
cd omp-agents
bun install --frozen-lockfile
omp config set collab.autoStart control   # show the sessions you start in a terminal
bun start

On start, the server prints a sign-in address, http://127.0.0.1:4317/?token=<token>. Open it once: it signs the browser in with a cookie, and from then on http://127.0.0.1:4317 works in that browser. Sessions that the dashboard starts appear right away, and terminal sessions once they start after the collab.autoStart change; see Show terminal sessions.

Getting started walks through a first session and each integration's setup.

Desktop app

Download the DMG for your Mac (Apple silicon arm64 or Intel x64) from the latest release and drag omp agents to Applications. The app ships its own Bun and server; it still needs omp installed, and finds it, gh, and git through your login shell's PATH. It checks GitHub Releases for updates and installs them when you quit or pick Restart to Install; until releases are signed with a Developer ID, macOS asks you to allow the app in System Settings › Privacy & Security, and updates download but do not install.

To run it from the clone instead:

bun run desktop

The first run downloads Electron into desktop/node_modules, about 100 MB; a git pull updates it. bun scripts/build-desktop-artifact.ts builds the packaged app into desktop/release. The window signs itself in, so it needs no token from you.

• If an omp-agents server already listens on the port, for example a bun start in another terminal, the window uses that server and leaves it running when you quit. Otherwise the app starts the server and stops it, with every session that the dashboard started, when you quit.
• On macOS, closing the window (Cmd+W) hides it and keeps the server and its sessions running; click the app in the Dock to show it again. Cmd+Q quits.
• In the packaged app, Open at Login in the app menu starts the app, and with it your routines, when you log in, and Install omp Starter Kit… installs the starter kit.
• Links to GitHub, Graphite, Linear, and every other site open in your default browser.
• PORT works as for bun start. A browser tab on the same address keeps working alongside the window.

Configuration

Show terminal sessions

Terminal sessions reach the dashboard through omp's local Collab registry. Have omp publish each session it starts:

omp config set collab.autoStart control

Only sessions that start hosting after the change appear. Restart a session that was already running, or run /new or /collab inside it. With view instead of control, the dashboard shows those sessions read-only.

Environment variables

Variable	Default	Purpose
PORT	4317	Port the server listens on, always on 127.0.0.1.
OMP_PACKAGE_DIR	resolved from omp on PATH	The installed @oh-my-pi/pi-coding-agent directory. Set it when omp is not on your PATH, or resolves to a build that does not ship its sources.

PORT=5000 bun start

omp starter kit

templates/omp holds the omp setup this project is built with: model roles and fallback chains across Anthropic, OpenAI Codex, Cursor, and OpenRouter, an AGENTS.md, a review agent, a /ship command, and skills. It also turns on collab.autoStart. It is opinionated: it expects accounts on those four providers, installs the third-party pstack plugin from the cursor/plugins marketplace, and sets a reply format for every session in APPEND_SYSTEM.md. Run it with --dry-run first to see each change. Install it with:

bun run omp-template --dry-run   # list what would change
bun run omp-template
bun run omp-template --maintainer

Pass --maintainer to also install the maintainer git profile. That profile tells a session to push local main, to register Graphite branches, and to clean up worktrees. The default install leaves it out.

Files and settings that you already have keep your version unless you pass --force. See the kit's README for what it contains.

Usage

Select a session in the left sidebar to read its conversation and message it. Cmd-click (Ctrl-click on Linux and Windows) opens it in a split pane. Click + to start a session, Resume to continue a past one, and Fork from here under a prompt or a reply to branch a conversation. The Pull requests tab shows your pull requests, the Tickets tab your Linear issues, and the Settings tab opens Settings.

While a turn runs, Enter queues a follow-up and Cmd+Enter (Ctrl+Enter on Linux and Windows) steers the turn. Esc interrupts it.

In a session the dashboard started, built-in / commands and !<command> run as they do in omp's terminal. A terminal session cannot run them, because Collab accepts guest prompts and not host-side commands. No session runs the $ Python shortcut from the dashboard, and only the omp terminal runs !!. The composer refuses a draft that starts with one of those and does not send it.

See docs/usage.md for the full interface reference, including every keyboard shortcut and URL format.

How it works

flowchart LR
  page[Browser page] <-->|WebSocket + JSON API| server[omp-agents server]
  server -->|watches| files[(omp session files)]
  server <-->|Collab guest| terminal[Terminal omp sessions]
  server <-->|RPC over stdio| child[Dashboard-started omp children]
  server -->|gh| github[GitHub]

Loading

• Transcripts come from omp's session files on disk, read incrementally as they grow. Live events only add what the file does not hold yet.
• Terminal sessions are joined as a Collab guest named omp-agents, the same way omp join does, for prompts, interrupts, questions, and subagent status.
• Dashboard sessions are omp child processes in RPC mode (--mode rpc-ui), spawned through omp's own RpcClient.

The server imports these protocols from your installed omp instead of reimplementing them. Joining a terminal session makes it count omp-agents as one more participant and send its transcript snapshot and live events through its Collab relay (collab.relayUrl); see why.

See docs/architecture.md for the design and the HTTP API, and docs/code-layout.md for where each file lives.

Security

Warning

The agents run tools on your machine. The access token stops web pages and other user accounts, not a program that runs as you: it can read the token file. Run the dashboard only on a machine that you alone use, and never expose its port through a tunnel or a proxy.

The server listens on 127.0.0.1 only, keeps Collab links and room keys in memory, and requires an access token, kept in ~/.config/omp-agents/token with mode 0600, for the page, the WebSocket, and every /api/ route. Delete the file and restart to rotate it. See SECURITY.md for the full threat model and how to report a vulnerability.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md to set up a development environment and run the checks.

License

MIT © 2026 Maxence Maisonnat