ocman

A web dashboard for browsing and driving your coding-agent sessions. Supports OpenCode.

Features

• Session browser. List, search, archive, and replay every session. Sessions are grouped by project, with status indicators and a + button to start new ones.
• Live composer. Send messages, answer permission prompts, abort, and compact a running session from the browser. Streaming output renders live.
• Bash mode. Prefix a message with ! to run a shell command in the session's working directory and capture the output.
• Command palette. One ⌘K palette for jumping between sessions, settings, and actions, with in-app notifications.
• Slash commands. /new [title] creates a session, /clear archives the current one and starts fresh. Renaming a session is keyboard-driven too.
• Tmux integration. Launch or auto-launch an OpenCode instance inside tmux from the UI.
• Routines. Save a project prompt, run it now, or schedule it in a fresh OpenCode session. History records errors and links to created sessions. See Routines.
• Multi-remote. Attach other ocman instances over the network and manage every machine's sessions from one dashboard. Every session carries a host badge, and new-session creation knows which machine has the project. See Multi-remote.
• Diff and changes view. Syntax-highlighted diffs inline in the thread, plus a Changes sidebar that combines session edits with the working-tree git diff.
• Stats dashboard. Per-project metrics, wall-clock totals, token and pricing graphs, system stats.
• Model picker. Per-platform favorites and a refreshable catalog, so new models appear without a restart.
• Auth. Optional password gate with rate-limited logins and persistent signed cookies. Off by default for localhost.
• PWA. Installable as a Progressive Web App.

Quick start

curl -fsSL https://forgejo.nousefreak.be/dries/ocman/raw/branch/main/install.sh | bash -s -- install
# Open http://localhost:8228

The script checks your toolchain (git, go, node, pnpm), builds from source into ~/.local/share/ocman/src, installs the binary to ~/.local/bin/ocman, and starts it in the background. It also installs itself as ocman-ctl:

ocman-ctl status | start | stop | restart | logs
ocman-ctl update              # pull, rebuild, restart
ocman-ctl uninstall           # add --purge to also delete state.db
ocman-ctl doctor              # dependency check only

Override with OCMAN_ADDR, OCMAN_PREFIX, OCMAN_BRANCH, OCMAN_SRC.

Alternatively, download the latest binary from the releases page, or build from source with make build (requires Go 1.24+ and Node.js 22+).

macOS desktop app

The releases page also ships ocman-darwin-arm64.dmg, a drag-to-Applications installer for the native desktop build. The DMG is not signed or notarized, so Gatekeeper refuses to open the app on first launch with a "cannot be opened because the developer cannot be verified" warning.

To get past it:

1. Open the DMG and drag ocman.app to /Applications.
2. In Finder, right-click (or Control-click) ocman.app and choose Open.
3. Confirm Open in the dialog. macOS remembers the choice and later launches work normally.

Or strip the quarantine attribute from a terminal:

xattr -dr com.apple.quarantine /Applications/ocman.app

The easiest way to get interactive sessions (composer, permission replies, abort) is to launch them from ocman itself, using the command palette (/wt for worktrees) or the per-project Worktrees view. Ocman manages one OpenCode instance per project and connects automatically.

If you prefer running OpenCode yourself, start it with an explicit port so ocman can discover it:

opencode --port 0   # let OpenCode pick a free port

Without --port, externally launched sessions are still readable but the composer stays disabled.

Configuration

./ocman                              # default: listens on 127.0.0.1:8228
./ocman -addr localhost:9090         # custom listen address
./ocman -db /path/to/opencode.db     # custom OpenCode database path
./ocman -platforms opencode,claude-code  # enable multiple platforms

See Configuration for the full flag and environment variable reference, including authentication setup.

Optional agent integration

You don't need any of this to use ocman as a dashboard. It also embeds an optional, localhost-only MCP server exposing Factory, routine, read-only session, and file-embedding tools.

Point your OpenCode config at http://localhost:8229/mcp (or http://localhost:8228/mcp via the make dev proxy). See the MCP integration guide for setup and the full tool list.

Managing sessions across machines

Run ocman on several machines and manage them all from one hub. On each machine you want to manage remotely, start ocman with a gRPC listen address:

ocman -remote-listen 0.0.0.0:8230 \
  -remote-tls-cert cert.pem -remote-tls-key key.pem

Then on the hub, open Settings → Remotes → Attach a remote, paste the remote's address and its access token (revealed from the remote's own Settings → Remotes page), and its sessions join the unified list with a host badge. Opening, driving, and creating sessions all route to the owning machine automatically.

This is off by default. A plain ./ocman with no remotes is unchanged. See the step-by-step multi-remote guide for TLS, security notes, and troubleshooting.

Documentation

docs/ mirrors the site structure: five chapters, same layout in the repo and on the rendered site (make docs).

• Introduction: what ocman is, install, first session
• Features: overview · multi-remote · MCP integration · routines
• Configuration: flags, env vars, authentication
• FAQ: short answers
• Other: architecture · contributing · profiling · releases

License

MIT. See LICENSE.