Nerdr

OpenCode × VSCodium

Know which agent
needs you.

Nerdr watches every OpenCode agent in your VSCodium terminals, shows each one's state at a glance, and rings a bell when one blocks — or when a build/plan agent finishes. Optionally, keep supervising from a private Telegram chat.

Install See how it works
  • Live roster in the activity bar & bottom panel
  • Attention bells with per-agent cooldown
  • Native Telegram control — reply, approve, switch modes
  • Webhook alerts to your own relay
  • Click to jump to the owning terminal

Built to stop the pane-by-pane hunt

Everything you need to supervise multiple agents without babysitting terminals.

State detection

Lifecycle events map to working, blocked, idle, done, and error in real time.

Attention bells

Rings a tone when an agent blocks, errors, or finishes, with a per-agent cooldown.

Telegram control

Reply to notifications to prompt agents, answer permissions and questions with buttons, and switch Plan/Build with /mode. Long polling only — no VPS or inbound port.

Nerdr panel

The roster lives in both the left activity bar and the bottom panel, sorted attention-first.

Jump to terminal

Click an agent, or run Focus Agent Terminal, and Nerdr reveals the terminal hosting it.

Workspace naming

Agents are named after the directory you started them in. Duplicates get a session-slug suffix.

Webhook relay

POST a one-line alert to your own endpoint for email, SMS, a dashboard, or another relay.

Local & private

State travels over a loopback socket with a per-run token. Telegram uses long polling and stores its token locally.

Two pieces, one loopback socket

An OpenCode plugin streams lifecycle state; the VSCodium extension aggregates, renders, and rings. The same plugin can also bridge a private Telegram chat.

OpenCode plugin

Hooks session, tool, permission, and question events, then reports state.

state →

Nerdr extension

Bridge server, agent store, roster panel, terminal matcher, and the bell.

Optional Telegram bridge: the plugin long-polls the Bot API directly, so notifications, replies, permissions, questions, and mode switches work without a webhook, tunnel, or inbound port.

  1. 1

    Run OpenCode

    Start agents in your VSCodium integrated terminals, as usual.

  2. 2

    Watch the roster

    Each agent appears with a live state and, when needed, a bell.

  3. 3

    Act fast

    Click the blocked agent and answer it — no pane-by-pane hunting.

Supervise from Telegram

Optional, private, and loopback-safe. Keep an eye on agents and answer them from your phone.

What you can do

  • Reply to any notification to prompt that agent.
  • Approve or deny permissions and answer questions with buttons.
  • Switch Plan/Build with /mode.
  • Receive the final assistant text when a turn completes.

Chat commands

/agents   list agents
/use ...  select an agent
/mode ... switch Plan/Build
/status   active agent and mode
/stop     interrupt the active agent
/help     all commands

Run Nerdr: Configure Telegram to paste a @BotFather token and pick your private chat. The token stays in ~/.nerdr/telegram.json with mode 0600. The bridge runs inside the OpenCode plugin and uses long polling, so there is no public URL, webhook, or inbound port.

Install

Requires Node 18+, VSCodium 1.85+, and OpenCode 2.x.

1 · VSCodium extension

# build and package
npm install && npm run build
npm run package -w nerdr

# install the VSIX
codium --install-extension packages/extension/nerdr-0.1.1.vsix

2 · OpenCode plugin

# copy the standalone bundle
mkdir -p ~/.config/opencode/plugins
cp packages/opencode-plugin/dist/nerdr.js \
   ~/.config/opencode/plugins/nerdr.js

Then reload the VSCodium window. OpenCode usually picks up plugin changes automatically; if the new commands are missing, restart the OpenCode 2.x service (opencode service restart).

Tune the bells

Sensible defaults; adjust in VSCodium settings or settings.json.

{
  "nerdr.bell.enabled": true,
  "nerdr.bell.states": ["blocked", "error", "done"],
  "nerdr.bell.agents": ["build", "plan"],
  "nerdr.bell.cooldownMs": 5000
}