Miranda
Telegram bot for remote Claude orchestration. The ractor who gives voice to the Primer.
Named after Miranda from Neal Stephenson's "The Diamond Age" - the ractor who voices the Young Lady's Illustrated Primer for Nell.
What is Miranda?
Miranda lets you orchestrate oh-my-pi agent sessions from your phone via Telegram:
- Start autonomous tasks - Spawn agents that claim GitHub issues, work them in isolated branches, and create PRs
- Answer questions remotely - When the agent needs input, get a Telegram notification and respond via inline buttons
- Batch merge PRs - Review and merge multiple PRs as a cohesive batch
- Address PR feedback - Handle review comments autonomously
- Monitor progress - Check session status from anywhere
Components
| Name | Role | Reference |
|---|
| Miranda | Telegram bot | The ractor who voices the Primer |
| oh-plan | Task planner | Investigates and creates GitHub issues |
| oh-task | Issue worker | Works GitHub issues autonomously |
| oh-merge | Batch merger | Merges GitHub issue PRs in rhythm |
| oh-notes | PR feedback | Addresses review comments |
| jira-plan | Jira planner | Creates Jira subtasks from context |
Architecture
Phone <-> Telegram <-> Miranda <-> oh-my-pi agent processes (RPC mode)
|
JSON lines over stdin/stdout
Miranda spawns oh-my-pi in RPC mode as child processes and communicates via JSON lines:
- Agent questions arrive as
extension_ui_request events on stdout
- User responses are sent as
extension_ui_response commands on stdin
- Task completion is signaled via the
signal_completion custom tool
- Process exit without completion signal is treated as an error
Completion Signaling
Skills call the signal_completion custom tool as their final action. Miranda watches for tool_execution_end events where toolName === "signal_completion" and extracts the structured payload (status, pr, error, blocker, message). This tool is installed to ~/.claude/tools/ and auto-discovered by oh-my-pi.
Prerequisites
Server Requirements
| Requirement | Purpose | Install |
|---|
| Node.js 20+ | Runs Miranda | nodejs.org |
| pnpm | Package manager | npm install -g pnpm |
| Bun | Runs oh-my-pi agent | bun.sh |
| oh-my-pi | Agent runtime | bun install -g @oh-my-pi/pi-coding-agent |
| gh CLI | GitHub operations | cli.github.com |
| superego | Code review | cargo install sg |
Verify prerequisites
node --version # >= 20
pnpm --version
bun --version
omp --version # oh-my-pi CLI
gh auth status # GitHub CLI, authenticated
sg --version # superego
Setup
1. Clone and install
git clone https://github.com/open-horizon-labs/miranda.git
cd miranda
pnpm install
pnpm build
2. Create a Telegram bot
- Message @BotFather on Telegram
- Create a new bot, copy the token
- Get your Telegram user ID from @userinfobot
3. Configure environment
mkdir -p ~/.config/miranda
cat > ~/.config/miranda/env << 'EOF'
TELEGRAM_BOT_TOKEN=<your-bot-token>
ALLOWED_USER_IDS=<your-telegram-id>
OMP_CLI_PATH=/home/<user>/.bun/bin/omp
PROJECTS_DIR=~/projects
PATH=/home/<user>/.bun/bin:/home/<user>/.cargo/bin:/home/<user>/.local/bin:/usr/local/bin:/usr/bin:/bin
EOF
| Variable | Required | Description |
|---|
TELEGRAM_BOT_TOKEN | Yes | From @BotFather |
ALLOWED_USER_IDS | Yes | Comma-separated Telegram user IDs |
OMP_CLI_PATH | Yes | Path to oh-my-pi CLI binary (e.g., /home/user/.bun/bin/omp) |
PROJECTS_DIR | No | Directory to scan for projects (default: ~/projects) |
MIRANDA_HOME | No | Override Miranda project root (default: derived from module location) |
4. Install the signal_completion tool
oh-my-pi discovers custom tools from ~/.claude/tools/. The signal_completion tool must be installed there:
mkdir -p ~/.claude/tools
cp plugin/tools/signal-completion.ts ~/.claude/tools/signal-completion.ts
5. Deploy with systemd (user-level)
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/miranda.service << 'EOF'
[Unit]
Description=Miranda - Telegram bot for remote Claude orchestration
After=network.target
[Service]
Type=simple
WorkingDirectory=%h/miranda
ExecStart=/usr/bin/node dist/index.js
Restart=always
RestartSec=5
Environment=NODE_ENV=production
EnvironmentFile=%h/.config/miranda/env
[Install]
WantedBy=default.target
EOF
# Enable lingering so service runs without active login (needs root, one-time)
sudo loginctl enable-linger $(whoami)
