Orchestrator

The Orchestrator is the brain of Octipus. It receives incoming messages, classifies them, and decides how to handle them — from simple casual responses to complex multi-step task execution with specialized worker agents.

How It Works

1. Message arrives from any channel (Telegram, Slack, Teams, WebChat)
2. Classifier analyzes the message and assigns a type: casual, task, or agent
3. Routing determines the appropriate response strategy:
   • Casual messages get a direct LLM response
   • Task messages spawn an orchestrator agent that breaks work into sub-tasks
   • Agent messages are routed to a specific existing agent

Message Classification

The classifier uses keyword matching combined with optional LLM classification to determine message intent with a confidence score.

Classification	Description	Action
casual	Greetings, questions, small talk	Direct LLM response
task	Work requests requiring tools	Spawn orchestrator agent
agent	Directed at a specific agent	Route to that agent

Orchestrator Roles

When a task message arrives, the orchestrator classifies it and spawns a specialist worker with the appropriate role. Each role has a set of tools attached to it.

Role	Tools	Description
orchestrator	profiles	Breaks tasks into sub-tasks, coordinates workers
research	browser, browser-ext, websearch, knowledge, filesystem, profiles, mcp	Web research, data gathering, knowledge base
coding	filesystem, shell, git, knowledge, mcp	Code writing, debugging, git operations
review	filesystem, shell, git, knowledge	Code review, testing, linting (read-only)
qa	browser, browser-ext, shell, docker, filesystem, knowledge	Testing, UI automation, test suites
communication	google-workspace, microsoft365, messaging, scheduling, profiles, email-processor, voice	Email, calendar, contacts, phone calls
design	browser, filesystem	UI/UX design, mockups, visual analysis
devops	shell, docker, git, filesystem, mcp	CI/CD, infrastructure, containers
security	shell, filesystem, browser, browser-ext, websearch, knowledge, mcp	Security analysis, vulnerability assessment
data	shell, filesystem, knowledge, mcp	Databases, data engineering, ETL
ai	shell, filesystem, browser, browser-ext, websearch, knowledge, mcp	ML/AI tasks, model evaluation
finance	browser, websearch, filesystem	Financial analysis, reporting
automation	shell, docker, filesystem, scheduling, mcp	Workflow automation, cron tasks, hooks
pm	filesystem, messaging	Project management, planning
writing	filesystem, browser, websearch, knowledge, messaging	Documentation, content creation
general	filesystem, browser-ext, websearch, messaging, knowledge, scheduling, profiles, email-processor, mcp	Multi-purpose: browsing, messaging, knowledge

Orchestrator Meta-Tools

The orchestrator itself has access to special meta-tools for managing the workflow:

Tool	Description
spawn_worker	Spawn a role-specific worker agent
create_pipeline	Create a multi-stage pipeline
filter_pii	Filter personally identifiable information
request_user_approval	Ask the user for approval before proceeding
send_status_update	Send progress updates to the user

Routing Keywords

The classifier uses keyword matching to suggest a role before the orchestrator decides:

Category	Keywords
development	implement, write code, fix bug, refactor, debug, typescript, react, git commit, pull request
research	research, investigate, search the web, compare, find out, tell me about, summarize
devops	docker, kubernetes, deploy, CI/CD, nginx, terraform, infrastructure
security	vulnerability, audit, OWASP, threat model, security review, encryption
data	database schema, SQL query, migration, ETL, data pipeline
writing	documentation, write docs, readme, technical writing, changelog
design	UI design, UX, wireframe, mockup, accessibility, typography
finance	budget, financial analysis, ROI, cost analysis, pricing
communication	email, gmail, calendar, phone call, call me, outlook, contacts
automation	schedule, cron, recurring task, remind me, automate, hook
general	browser, screenshot, telegram, send message, knowledge base, upload

Prompt Examples

"Fix the login bug in auth.ts"         → coding role
"Search the web for React best practices" → research role
"Deploy the Docker container"          → devops role
"Check my Gmail inbox"                 → communication role
"Call +1234567890"                      → communication role
"Create a daily reminder at 9 AM"      → automation role
"Run the test suite"                   → qa role
"Who is my wife?"                      → general role
"Scan for SQL injection vulnerabilities" → security role

Fallback Chain

The orchestrator uses a prioritized fallback chain when selecting a model for worker agents:

1. CLI models (Claude Code, Gemini CLI, Codex CLI) — free subscription-based
2. Default model — configured in the database
3. Any local model — Ollama models with tool support

Safety Guarantees

• Reasoning model detection: Automatically skips reasoning models (DeepSeek Reasoner, etc.) for orchestration since they are incompatible with tool-calling agent loops
• CLI sub-agent fallback: When CLI models fail (quota exhausted), retries with the default local model
• Safe fallback: Only falls back to local (Ollama) models for tool-calling roles — never silently routes to paid API models

Note

User-initiated stops do not trigger the fallback chain. Only genuine failures (quota exhaustion, crashes) activate fallback routing.

Approval Management

The orchestrator includes an approval system for sensitive operations:

1. Agent encounters a tool call requiring user approval (permission level: ASK)
2. Agent pauses and sends an approval request notification
3. User reviews the request in the web UI or via the API
4. User can approve, skip, or stop the operation
5. Agent resumes or stops based on the user’s decision