Prompt Engineering

How to configure and prompt Octipus to trigger different features.

Prerequisites

Requirement	Details
Backend running	bun run dev on port 3005
PostgreSQL + Redis	Docker services running
LLM model	At least one model configured in LiteLLM
Web UI	http://localhost:3007 (auto-started)

Optional Configuration

Feature	Requirement
Telegram	Set telegram.botToken in settings
Browser extension	Install Chrome extension, connect to WebSocket
GitHub tools	gh CLI authenticated
Google Workspace	OAuth configured in settings
Microsoft 365	OAuth configured 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.

Auto-Routing Examples

The orchestrator classifies your message and spawns the right specialist:

# → Coding expert
Fix the bug in src/utils/parser.ts where it fails on empty input

# → DevOps expert
Deploy the staging environment and check container health

# → Security expert
Scan the API endpoints for XSS vulnerabilities

# → Research expert
Research the top 5 alternatives to Redis for caching

# → Data expert
Write a SQL query to find users who signed up in the last 30 days

# → Communication expert
Check my Gmail for unread emails from today

Direct Expert Chat

Bypass the orchestrator by specifying an expertId:

POST /api/chat
{
  "message": "Review the authentication module",
  "expertId": "security-analyst"
}

Agent Teams (Parallel)

Trigger by requesting work that naturally requires multiple perspectives:

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.

You can also be explicit: Use a team: have one agent research competitors, another analyze our pricing data, and a third draft a market positioning document.

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.

At approval checkpoints, respond with approve / yes to continue or deny / no to cancel.

Tool-Triggering Prompts

Tools are automatically available based on the agent’s role. Examples:

Tool	Example Prompt
Browser (isolated)	“Open https://example.com and take a screenshot”
Browser extension	”Open my GitHub notifications in the browser”
Shell	”Run npm test and show me the results”
Git	”Show me the git log for the last 10 commits”
Knowledge base	”Search our knowledge base for authentication patterns”
Web search	”Search for bun vs node performance 2024”
Google Workspace	”Check my Gmail for unread emails”
Docker	”Show logs for the postgres container”

Hooks

Hooks automate actions based on events. Configure in the Hooks page.

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

Action	What It Does
notify	Send a message to a channel
spawn_agent	Start an agent
webhook	Send an outgoing HTTP request
n8n_workflow	Trigger an N8N automation workflow
execute_tool	Run a specific tool action

Skills

Skills provide domain knowledge to agents as markdown content. Manage them in the Skills page:

1. Go to the Skills page
2. Click “Create Skill”
3. Paste markdown content (coding guidelines, best practices, etc.)
4. Assign to an expert in the expert configuration

Skills are automatically injected into the agent’s system prompt based on the expert configuration.