OctoOffice

A local-first orchestrator that turns CLI coding agents into a fully simulated virtual software company — with departments, meetings, workflows, and a pixel-art office you can watch them work in.

Quick Start  ·   How It Works  ·   Features  ·   Workflow Packs  ·   Screenshots  ·   Providers  ·   Messenger  ·   Tech Stack  ·   Security  ·   Release Notes

---

---

What is OctoOffice?

OctoOffice connects your AI coding assistants — Claude Code, Codex CLI, Gemini CLI, OpenCode, OpenClaw, GitHub Copilot, Antigravity, or any LLM API — and organizes them into a virtual software company. You give orders as the CEO. They collaborate across departments, execute multi-phase workflows, and deliver results — all from a single dashboard.

> Local-first & private — Everything runs on your machine. SQLite database, no cloud dependency, no data leaves your network.

Why OctoOffice?

One dashboard, many agents — Stop juggling terminals. Manage all your AI providers from MissionControl.

Real autonomous collaboration — Agents work in isolated git worktrees, attend planning meetings, and hand off work across departments.

Declarative workflows — Define multi-phase pipelines in YAML. The graph runner handles sequencing, connector dispatch, and phase advancement.

Visual & transparent — A pixel-art retro office shows what every agent is doing. Live terminal output. Real-time WebSocket updates.

Talk from anywhere — Send directives via Telegram, Discord, Slack, or WhatsApp. Approve decisions without opening the browser.

---

How It Works

1. You give a directive — type $ Build a REST API in the chat or send it via Telegram

2. CEO analyzes & delegates — the orchestrator parses your request and creates a task

3. Team leader assigns — the department's team leader picks the best-fit agent

4. Agent executes in isolation — each agent works in its own git worktree

5. Phases advance automatically — the graph runner moves through the workflow pack's DAG

6. You review & decide — approve, request changes, or let the CEO route follow-ups

---

CEO Orchestrator (Autonomous Mode)

When enabled, the CEO Orchestrator runs on a periodic tick and autonomously reviews your inbox, creates tasks from messages, approves completed reviews, rebalances workloads, and reprioritizes queues. Conservative by design — max 3 decisions per tick, only acts on clear signals.

CEO Follow-Up Routing

When you submit follow-up feedback, the CEO makes an intelligent routing decision:

| Decision | When | Effect | | :----------------: | :------------------------: | :-----------------------------------------------------: | | Supplement | Small fix or clarification | Routes to the best-fit agent (may differ from original) | | Pipeline Reset | Significant rework | Resets workflow phases from a specified point | | New Task | Out of scope | Creates a separate linked task with its own pipeline |

Direct Agent Chat

Send a message without $ to talk directly to a specific agent. Requires a session mapping (messenger channel → agent). The agent responds in the same channel.

---

Quick Start

Prerequisites

| Tool | Version | Install | | :---------: | :-----: | :------------------------------------: | | Node.js | >= 22 | nodejs.org | | pnpm | latest | corepack enable (built into Node.js) | | Git | any | git-scm.com |

Typical setup time: 3–8 minutes on Linux/macOS with Node 22+ and pnpm already installed; 5–15 minutes via Docker.

One-Command Install

macOS / Linux

git clone https://github.com/Chepko932/OctoOffice.git && cd OctoOffice && bash install.sh

Windows (PowerShell)

git clone https://github.com/Chepko932/OctoOffice.git; cd OctoOffice; powershell -ExecutionPolicy Bypass -File .\install.ps1

Start

pnpm dev          # Web UI on :8800, API on :8790 (binds 0.0.0.0, network-accessible)
# or
pnpm dev:local    # Same, but loopback only (127.0.0.1)

Open http://127.0.0.1:8800 — done.

Manual setup

corepack enable
pnpm install
cp .env.example .env
# Generate OAUTH_ENCRYPTION_SECRET and INBOX_WEBHOOK_SECRET (32-byte hex each)
node -e "const fs=require('fs'),c=require('crypto'),g=()=>c.randomBytes(32).toString('hex');let e=fs.readFileSync('.env','utf8').replace(/^OAUTH_ENCRYPTION_SECRET=.*$/m,\`OAUTH_ENCRYPTION_SECRET=\${g()}\`).replace(/^INBOX_WEBHOOK_SECRET=.*$/m,\`INBOX_WEBHOOK_SECRET=\${g()}\`);fs.writeFileSync('.env',e)"
pnpm run setup -- --port 8790
pnpm dev

Install with AI

Paste this to your coding agent:

Install OctoOffice following the guide at:
https://github.com/Chepko932/OctoOffice

Docker

No local Node.js required — just Docker:

git clone https://github.com/Chepko932/OctoOffice.git && cd OctoOffice
cp .env.example .env

# Generate OAUTH_ENCRYPTION_SECRET and INBOX_WEBHOOK_SECRET in one shot
node -e "const fs=require('fs'),c=require('crypto'),g=()=>c.randomBytes(32).toString('hex');let e=fs.readFileSync('.env.example','utf8').replace(/^OAUTH_ENCRYPTION_SECRET=.*$/m,\`OAUTH_ENCRYPTION_SECRET=\${g()}\`).replace(/^INBOX_WEBHOOK_SECRET=.*$/m,\`INBOX_WEBHOOK_SECRET=\${g()}\`);fs.writeFileSync('.env',e)"

docker compose --profile prod up --build    # Production (all on :8790)
docker compose --profile dev up --build     # Development (Vite :8800, API :8790)

All CLI providers are pre-installed in the image. SQLite persisted to a Docker volume.

Remote access (Tailscale / LAN) — set BIND_HOST in .env to bind ports to a non-loopback IP:

# .env
BIND_HOST="100.x.x.x"   # your Tailscale IP, or 0.0.0.0 for every interface

Default is 127.0.0.1 (localhost only). Combined with the login password in Settings → General → Remote Access, this gives you encrypted remote access over Tailscale.

---

Features

MissionControl Dashboard

The home view — a 3-column layout with an agent sidebar (sprite avatars, token usage), an embedded pixel-art office canvas with MiniKanban and metrics, and a real-time chat panel supporting task conversations, announcements, reports, and CEO directives.

Pixel-Art Office

A Tiled-map-based 2D office rendered with Pixi.js 8. Agents walk between desks, attend meetings, and work across 7 department rooms. Supports light and dark themes with Press Start 2P pixel font and JetBrains Mono for data. Expandable to fullscreen.

Kanban Task Board

Full task lifecycle — Inbox → Planned → In Progress → Review → Done — with drag-and-drop, pack-aware phase views, filters, and batch operations.

Visual Node Editor

Four modes in one:

| Mode | Purpose | | :------------: | :-------------------------------------------------------------------: | | Visualizer | Read-only graph of any pack's phase DAG | | Monitor | Live execution overlay — watch phases turn green in real time | | Editor | Drag-to-connect ports, property panel, YAML preview + save | | Builder | Create new packs from scratch with a node palette and guidance editor |

Built with React Flow. Node types from the registry appear in the palette, grouped by category.

AI Provider Support

CLI Providers — Claude Code · Codex CLI · Gemini CLI · OpenCode · OpenClaw · GitHub Copilot · Antigravity

API Providers — OpenAI · Anthropic · Google · Ollama · OpenRouter · Together · Groq · Cerebras

OAuth — GitHub & Google with AES-256-GCM encrypted token storage

Messenger Integration

Full bidirectional messaging with Telegram and Discord (built-in receivers). Outbound support for Slack, WhatsApp, Google Chat, Signal, and iMessage. Send $ directives, approve decisions, and receive live updates — all from your phone.

Decision Inbox

When agents need approval, they send numbered option lists to your messenger:

📋 Decision Required: Code Review for auth-refactor
1. Approve and merge
2. Request changes
3. Reject
→ Reply with the option number.

Works in the Web UI and all connected messenger channels. Multi-language responses supported.

CEO Directives & Routing

| Prefix | Effect | | :----------------------------: | :----------------------------------------------: | | $ Build a REST API | Broadcast to all agents, delegated via Planning | | $ @design @qa Redesign login | Targeted — specific departments receive the task | | Fix the null check | Direct chat with the session-mapped agent | | 1 or approve | Decision reply — approves the pending action |

Git Worktree Isolation

Every agent works in its own isolated git worktree and branch. No conflicts between parallel agents. Merges happen only on CEO approval.

Obsidian Knowledge Base

Bidirectional sync with local Obsidian vaults. Before task execution, vault files are copied into the agent's worktree. After execution, changes sync back.

Skills Library

Categorized skills library with custom skill upload and classroom-style training. Assign skills to agents to specialize their capabilities.

Server Management

Register external servers with health checks, resource allocation, and queue processing.

In-App Updates

Auto-detect new GitHub releases with guided update instructions — never miss a version.

Mobile Responsive

Dedicated mobile components for phones and tablets: collapsible office canvas with pinch-to-zoom, vertical Kanban, bottom-sheet modals, and 44px touch targets.

Multi-Language UI

English · Korean · Japanese · Chinese · German

MCP Integration

OctoOffice acts as an MCP client — connect to external MCP servers and their tools are automatically available to all agents. Supports stdio and sse transports.

Node Type System

Reusable workflow building blocks that run server-side TypeScript — no agent spawn needed. Built-in types: echo, comfyui_generate, planning_meeting, cross_dept.

Remote Access

Password-protected remote access for Tailscale or similar setups. Scrypt-hashed passwords, 7-day session tokens. Localhost remains password-free.

---

Workflow Packs

Packs are declarative YAML files that define a phase DAG — the complete workflow for a type of project. Each phase specifies its department, agent guidance, dependencies, and execution mode.

Execution modes: agent (LLM executes) · hybrid (agent + connector guidance) · server (connector executes directly)

| Pack | Key | Focus | Departments | | :----------------------: | :---: | :------------------------: | :----------------------------------------------------------: | | Development | DEV | Engineering baseline | Research, Planning, Development, Testing, Review, Design, QA | | Design Studio | DSN | UI design & design systems | Design Planning, UI Design, Design QA, Handoff Engineering | | Web Research | WEB | Citation-first research | Research Strategy, Crawler Team, Fact Check | | Video Pre-Production | VID | ComfyUI video pipeline | Creative Direction, Visual Production, Visual QA |

Select packs in Settings > General > Office Workflow Pack.

Create your own pack:  Copy the starter template and edit the YAML — zero code changes required.

cp -r server/packs/community/_template server/packs/community/my_pack
# Edit pack.yaml + guidance files, restart the server — done.

See the full [Community Pack Creation Guide](docs/creating-community-packs.md) for schema reference, guidance writing tips, and common patterns.

---

Screenshots

MissionControl (Dark)Agent sidebar, embedded pixel office, MiniKanban, and live chat

MissionControl (Light)Same layout with emerald accent on light background

Visual Node EditorPhase DAG with live execution monitor and drag-to-connect editing

Kanban BoardDrag-and-drop task management with filters and pack-aware phases

Agent RosterAll agents with department filter, provider badge, and status indicators

SettingsCLI providers, API keys, messenger channels, workflow packs

Onboarding

First launch walks you through a 5-step wizard — company/CEO identity, default CLI provider, optional extras, Obsidian knowledge base, and final sanity check.

Mobile

Full responsive layout for phones — 5-tab bottom navigation (Office, Tasks, Chat, Ops, More), slide-up bottom sheets, pinch-to-zoom office canvas, and 44px minimum touch targets throughout.

---

Provider Setup

OctoOffice supports three provider paths:

CLI tools — Local coding CLIs spawned as subprocesses OAuth accounts — GitHub/Google-backed flows via secure token exchange API keys — External LLM APIs configured in Settings > API

CLI Providers

| Provider | Install | Auth | | :----------------------------------------------------------------: | :---------------------------------------: | :-------------------------: | | Claude Code | npm i -g @anthropic-ai/claude-code | claude (follow prompts) | | Codex CLI | npm i -g @openai/codex | OPENAI_API_KEY in .env | | Gemini CLI | npm i -g @google/gemini-cli | OAuth via Settings | | OpenCode | npm i -g opencode | Provider-specific | | OpenClaw | npm i -g openclaw | Profile-based (--profile) | | GitHub Copilot | npm i -g @githubnext/github-copilot-cli | gh auth login | | Antigravity | npm i -g antigravity | Provider-specific |

Configure providers and models in Settings > CLI Tools.

OpenClaw profile-based local LLM setup

OpenClaw supports per-agent profile isolation via --profile <name>. Each profile maintains its own config under ~/.openclaw-<name>/.

openclaw --profile qwen config set agents.defaults.model.primary "vllm/qwen3.5-35b-moe"
openclaw --profile qwen config set tools.elevated.enabled true

Set an agent's provider to OpenClaw and enter the profile name in the dashboard.

---

Messenger Integration

Configure channels in Settings > Channel Messages.

Bidirectional (built-in receivers)

| Channel | Protocol | Requirements | | :----------: | :----------: | :-----------------------------------------------------------: | | Telegram | Long-polling | Bot token from @BotFather + chat ID | | Discord | Polling | Bot token + channel ID |

Outbound-only

| Channel | Transport | Requirements |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Chepko932
• Source: Chepko932/OctoOffice
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.