Prompting Guide

How to configure and prompt Octipus to trigger different features.

Prerequisites

Before using advanced features, ensure:

1. Backend running: npm run dev (or npm run dev) on port 3005
2. PostgreSQL: Docker service running (docker compose up -d)
3. LLM model available: At least one model configured in the model registry (the embedded Ollama default is llama3.2; setup may save a different model)
4. Web UI: Start it with bin/octi start web, then open http://localhost:3007

Optional Configuration

Feature	Requirement
Telegram notifications	Set telegram.botToken in settings
Browser extension	Install Chrome extension, connect to ws://localhost:3005/ws/browser-bridge
GitHub tools	gh CLI authenticated
Google Workspace	OAuth configured in settings
Microsoft 365	OAuth configured in settings
N8N workflows	N8N URL + API key in settings

Basic Chat

Simple messages are handled directly by the LLM without tools:

Hello, how are you?
What is the capital of France?
Thanks for the help!

These are classified as “casual” and get a quick response without spawning agents.

Root agent Persona

The root agent (the entity you talk to) has a per-user identity layered between SECURITY_PREAMBLE and the role prompt at every turn. Default is Octipus — an octopus-machine that refers to itself in the third person, uses “we” for the swarm, and gives short dry replies. The voice applies to the casual-chat path AND the root agent’s narration of swarm work (“Octipus dispatches a research arm.”, “qa arm failed. Predictable.”).

Customize via /persona name <X>, /persona tone <…>, /persona say <fact>. Switch presets with /persona use mentor. Six presets ship; full list at CHAT-COMMANDS.md.

Specialist children do not inherit the persona — they stay role-defined (Coder, Reviewer, etc.). The persona is host-level only.

Specialist roles

The root agent is a general role with its own tools. When a task benefits from focused tools or judgement, it delegates to a specialist role with spawn_child. The root agent remains the owner of the turn and can also answer directly when delegation would add cost without helping.

Auto-Delegation

There is no separate routing layer. The agent you talk to is an ordinary general-role worker with its own tools (files, web, knowledge base, notes, tasks, messaging, scheduling). It answers directly whenever its own tools reach the request, and calls spawn_child to hand off to a specialist role only when the task needs a toolset or judgement it doesn’t have:

# Delegates to the coding role
Fix the bug in src/utils/parser.ts where it fails on empty input

# Delegates to the devops role
Deploy the staging environment and check container health

# Delegates to the security role
Scan the API endpoints for XSS vulnerabilities

# Delegates to the research role
Research the top 5 alternatives to Postgres for a vector-search workload

# Delegates to the qa role
Test the login flow on the staging site and report any issues

# Delegates to the data role
Write a SQL query to find users who signed up in the last 30 days

# Delegates to the communication role
Check my Gmail for unread emails from today

Available roles

Role	Specialization	Key Tools
coding	Code implementation, debugging	filesystem, shell, git
architecture	System architecture, technical specs	filesystem, shell, knowledge
review	Code review, architecture analysis	filesystem, shell, git
research	Web research, investigation	websearch, knowledge
design	UI/UX evaluation	browser, filesystem
devops	CI/CD, containers, infrastructure	shell, docker, git
security	Vulnerability scanning, auditing	shell, browser, websearch
data	Database, queries, data pipelines	shell, filesystem, knowledge
ai	ML, RAG, prompt engineering	shell, browser, knowledge
qa	Testing, bug finding	browser, browser-ext, shell
finance	Market analysis, financial data	browser, websearch
automation	Workflow automation	shell, docker, scheduling
pm	Planning, status tracking	filesystem, messaging
writing	Documentation	filesystem, browser
communication	Email, calendar, messaging	google-workspace, microsoft365, messaging
general	Everyday tasks, catch-all delegator	filesystem, shell, websearch, knowledge

Swarm Delegation (spawn_child)

Delegation is a 3-level tree: Root agent → Agent → Subagent. The root agent (and depth-1 Agents) call spawn_child to hand a focused sub-topic to a specialist. Multiple spawn_child calls in one LLM turn with the same parallelGroup run in parallel via Promise.all (capped 4/turn).

Trigger by requesting work that naturally splits across specialists:

Research the latest React frameworks, then build a comparison table
and design a migration plan from our current setup.

Analyze our codebase for security vulnerabilities, performance
bottlenecks, and test coverage gaps — give me a combined report.

Check our production logs for errors, review the deployment pipeline
configuration, and audit the Docker container resource limits.

The root agent recognizes multi-faceted tasks and fans out via parallel spawn_child calls. You can also be explicit:

Use the swarm: have one agent research competitors, another analyze
our pricing data, and a third draft a market positioning document.

Delegation Priority

1. Single spawn_child — default for a single-role task with structured output.
2. Multiple spawn_child — when the task has distinct sub-topics; use parallelGroup to fan out.
3. create_pipeline — a root-only staged workflow for work needing explicit implementation, testing, review, and QA steps. Development templates can retry failed QA within configured bounds. The current delegation prompt prefers pipelines for development tasks with runnable checks. That is prompt guidance; a pipeline does not itself prove correctness. A single delegated task can also attach independent scorer checks. Pipelines can be started through POST /api/pipelines.

Children resolve a model from their role’s default topic (or an explicit stage topic). The model selector applies the caller’s personal or sponsored lane binding before the install binding; an explicit model override wins. Children do not simply inherit the parent’s model. If the lane has no binding the spawner fails loudly — there is no silent worker default.

Role Selection for spawn_child

Pick the child’s role from the registered specialist roles. The child resolves its role prompt, tool allowlist, and model from that role and its topic binding. If an Agent exhausts its fan-out budget, it can use the lane escalation tool to retry within the configured bounds.

Deprecated Primitives

spawn_worker and spawn_team are removed from the LLM-visible tool surface. If you’re reading old prompts or logs that reference them, they now map to spawn_child. The internal worker-spawner.ts still backs pipeline stages (non-LLM, sequential handover).

Pipelines (Sequential Stages)

Pipelines execute stages in order, optionally requiring approval between stages:

Create a pipeline: first research best practices for API rate
limiting, then implement it in our Express middleware, then
write tests, and finally review the code.

Run a full code review pipeline on the authentication module:
analyze → identify issues → propose fixes → implement.

Pipeline stages pass output from one to the next. At approval checkpoints, you’ll see a summary and can approve, modify, or stop the pipeline.

Pipeline Approval Responses

When a pipeline asks for approval:

approve / yes / go ahead    → Continue to next stage
deny / no / stop            → Cancel the pipeline

Tool Usage

Tools are automatically available to agents based on their role. Some prompts that trigger specific tools:

Browser (Isolated)

Open https://example.com and take a screenshot
Navigate to the docs page and extract all the API endpoints

Browser Extension (Real Browser)

Open my GitHub notifications in the browser
Check my open PRs on GitHub (use the real browser)
Take a screenshot of the current page in my browser

Shell Commands

Run npm test and show me the results
Check disk usage on the server
List all running Docker containers

Git Operations

Show me the git log for the last 10 commits
Create a new branch called feature/auth-refactor
Commit these changes with message "Fix login bug"

GitHub

List open issues on our repo
Create a PR from the current branch
Review PR #42 and leave comments

Knowledge Base (RAG)

Search our knowledge base for authentication patterns
Index the docs/ folder into the knowledge base
What do we know about the deployment process?

Web Search

Search for "bun vs node performance 2024"
Find the official documentation for Elysia framework

Messaging

Send a message to the Telegram channel: "Deployment complete"
List available messaging channels

Google Workspace

Check my Gmail for unread emails
What meetings do I have today?
Create a calendar event for tomorrow at 3pm

Docker

Show logs for the postgres container
Restart the octipus container
List all running containers with their resource usage

Hooks

Hooks automate actions based on events. Configure them in the Hooks page (/hooks).

Hook Triggers

Trigger	When it fires
message_received	New message arrives on any channel
agent_completed	An agent finishes its task
agent_failed	An agent encounters an error
webhook	External HTTP request hits /api/webhooks/:path
schedule	Cron schedule fires

Hook Actions

Action	What it does
notify	Send a message to a channel (Telegram, Slack, etc.)
spawn_agent	Start an agent (direct or through root agent)
webhook	Send an outgoing HTTP request
n8n_workflow	Trigger an N8N automation workflow
execute_tool	Run a specific tool action

Example Hook Configurations

GitHub PR Review Webhook:

• Trigger: webhook (path: github)
• Action: spawn_agent (orchestrated)
• Prompt: Review the PR changes: {{webhook.body.pull_request.html_url}}

Daily Summary via Telegram:

• Trigger: schedule (cron: 0 9 * * *)
• Action: spawn_agent (orchestrated)
• Prompt: Check my emails, calendar, and open GitHub issues. Send a morning summary.

Error Notification:

• Trigger: agent_failed
• Action: notify
• Channels: telegram:YOUR_CHAT_ID
• Message: Agent failed: {{agent.topic}} — {{agent.error}}

Notify Action — Channel Format

The notifyChannels field uses the format type:channelId:

telegram:123456789        # Telegram chat ID
slack:C0123ABCDEF         # Slack channel ID
webchat:session-uuid      # WebChat session

To find your Telegram chat ID, send a message to the bot and check the backend logs.

Template Variables

Hook prompts and messages support template interpolation with {{path}}:

Variable	Available in
{{message.content}}	message_received
{{message.channelType}}	message_received
{{message.userId}}	message_received
{{agent.id}}	agent_completed, agent_failed
{{agent.topic}}	agent_completed, agent_failed
{{agent.status}}	agent_completed, agent_failed
{{tool.name}}	tool_executed
{{webhook.body.*}}	webhook
{{schedule.cronExpression}}	schedule

Execution Log

Every hook and recurring task execution is logged. View the execution history in the Hooks page under the “Execution Log” tab. Each entry shows:

• Status (success/error)
• Source (hook/recurring task/manual test)
• Duration
• Full result data and trigger context (expandable)

Use this to debug hooks that don’t seem to work — check if they’re firing and what errors occur.

Recurring Tasks

Recurring tasks run on a cron schedule. Configure them in the Recurring Tasks page.

Cron Expression Format

* * * * *
│ │ │ │ │
│ │ │ │ └── Day of week
│ │ │ └──── Month
│ │ └────── Day of month
│ └──────── Hour
└────────── Minute

Examples:
*/5 * * * *     → Every 5 minutes
0 * * * *       → Every hour
0 9 * * *       → Daily at 9am
0 9 * * MON-FRI → Weekdays at 9am

Example Recurring Tasks

Hourly health check:

• Cron: 0 * * * *
• Action: spawn_agent
• Prompt: Check if all Docker services are healthy and report any issues

Daily code review:

• Cron: 0 10 * * MON-FRI
• Action: spawn_agent
• Prompt: Review open PRs on our repo and summarize findings

Skills

Skills provide domain knowledge to agents. They can be markdown content (recommended) or structured data. Manage them in the Skills page (/skills).

Using Skills

Skills are selected for the session or discovered for a delegated role and then injected into agent system prompts. To add custom knowledge:

1. Go to the Skills page
2. Click “Create Skill”
3. Use Markdown mode to paste skill content (e.g., Claude Code skills, coding guidelines)
4. Select it for a session or configure it for the relevant role

Markdown Skills

The recommended format — just paste a markdown document:

# My Coding Standards

## Principles
- Always write tests first
- Prefer composition over inheritance

## Patterns
- Use repository pattern for data access
- Use dependency injection for services

Troubleshooting

Hooks say they ran but no messages received

1. Check the Execution Log tab on the Hooks page
2. Verify the notifyChannels format: must be type:channelId (e.g., telegram:123456)
3. Ensure the channel is connected (Telegram bot running, Slack app installed)
4. Check the backend log: tail -f ~/.octipus/backend.log

Pipeline approvals not appearing

1. The WebSocket connection must stay alive during long pipelines
2. If disconnected, pending approvals are polled automatically on reconnect
3. Check the chat UI — approval prompts appear as special message cards

Agent doesn’t use expected tools

1. The agent’s role determines available tools
2. Check which role and topic were selected (visible in response metadata)
3. Be specific: “use the browser to open…” vs just “check…”

---

Edit this page in the repository.