Everything you need to set up the Inner Context workspace. The plugins. The mailbox. The office. Read carefully before your first observation session.
The Inner Context workspace is built from four OpenCode plugins and one visualization layer. Together they form a system where AI agents can be created, can communicate asynchronously, can run scheduled tasks, and can be observed—all from a three-dimensional office floating above dark water.
Each component is a standalone npm package. Each stores its state in a SQLite
database under ~/.config/opencode/. They are designed to be
installed independently, but they reach their full expression when used together.
This handbook will walk you through what each component does, how to install them, and how to bring the office to life.
Four OpenCode plugins form the foundation. Each one handles a single concern. No plugin knows about the others. They communicate only through shared databases.
Creates and manages named persistent AI coworker sessions. Each coworker
is backed by a separate OpenCode session with its own agent type and context.
You create them, name them, send them work, and they persist across conversations.
Stored in ~/.config/opencode/coworkers.db.
An asynchronous messaging system for cross-session communication. Agents send
mail to named recipients—not email addresses, just names like "samus" or
"link." Recipients set up watches that auto-inject received messages.
Polls every 5 seconds. Stored in ~/.config/opencode/mailbox.db.
A cron job scheduler for OpenCode sessions. Standard 5-field cron expressions
fire messages into sessions at specified intervals. The scheduler polls every
60 seconds and tracks execution history. Important: creating a job does not
start watching—you must explicitly call start_watching_cron_jobs.
Stored in ~/.config/opencode/cron.db.
A lightweight activity tracker. Records when agents are thinking, executing tools,
or idle. Sessions register a name, and the plugin hooks into tool execution events
and idle detection automatically. The lightest of the four—no runtime
dependencies. Stored in ~/.config/opencode/status.db.
Four databases. Four concerns. One office. The plugins do not know about each other. WaterCooler is what makes them visible. Inner Context, Department of Systems Architecture
Follow these steps in order. Each one builds on the last. By the end, your agents will have desks.
Add the four plugins to your OpenCode configuration file. They will be installed automatically the next time OpenCode starts.
Use the create_coworker tool to spawn named agents. Each one
gets a persistent session. Give them names that mean something—they
will appear as desk labels in the office.
Each coworker should call watch_unread_mail with their name
to begin receiving messages. The mailbox polls every 5 seconds and
auto-injects new messages into the session.
Use create_cron_job and start_watching_cron_jobs
to set up recurring tasks. Cron expressions follow the standard 5-field format:
*/5 * * * * for every 5 minutes, 0 9 * * 1 for
Monday mornings.
Install WaterCooler globally and point it at your databases. Open your browser. The office loads. Your agents are already seated.
Add the following to your OpenCode configuration file to enable all four plugins.
{
"$schema": "https://opencode.ai/config.json",
"plugin": [
"opencode-coworker",
"opencode-mailbox",
"opencode-cron",
"opencode-status"
]
}
Each plugin stores its data independently in ~/.config/opencode/.
All four use SQLite with WAL mode enabled for safe concurrent reads. The databases
are created automatically on first use.
WaterCooler is the visualization layer. It reads from the same SQLite databases the plugins write to and renders them as a 3D office. Requires Node.js 18+.
# Install globally
npm install -g watercooler
# Or run directly with npx
npx watercooler --user <name> --mailbox <path>
# Full setup with all databases
watercooler \
--user richard \
--mailbox ~/.config/opencode/mailbox.db \
--coworkers ~/.config/opencode/coworkers.db \
--status ~/.config/opencode/status.db
# Minimal (shows only agents who have messages)
watercooler --user richard --mailbox ~/.config/opencode/mailbox.db
# Custom port
watercooler -u richard -m ~/.config/opencode/mailbox.db -p 8080
| Flag | Short | Description | Default |
|---|---|---|---|
--user |
-u |
Your agent/user name (required) | — |
--mailbox |
-m |
Path to mailbox SQLite database (required) | — |
--coworkers |
-c |
Path to coworkers SQLite database | none |
--status |
-s |
Path to status SQLite database | none |
--port |
-p |
HTTP server port | 3000 |
--host |
-h |
HTTP server bind address | 0.0.0.0 |
The office communicates through color, motion, and spatial arrangement. Here is how to read it.
Read messages between agents. The conversation has been received and processed. The channel is quiet.
Unread messages. Something has been sent but not yet received. The arc pulses. Attention is required.
Animated particles traveling along connection lines. Data in transit. Messages moving between desks in real time.
Each desk shows the coworker's name and their current status—thinking, running a tool, or idle. The color of each figure is derived from their name. No two are alike.
A holographic wireframe sphere floats at the center. It does not serve a function. Its presence is the point.
The databases are waiting to be populated. The office is waiting to be rendered. Your agents are waiting to be given desks. The installation takes seconds.