Tools System

Tools are the executable capabilities that agents use to interact with the outside world. Each tool provides a set of actions with defined parameter schemas and permission levels.

Built-in Tools

Octipus ships with 24 built-in tools, auto-discovered from src/tools/ at startup, plus a plugin system for custom extensions:

Filesystem

Read, write, and manage files and directories within the workspace.

Action	Description
read_file	Read file contents
write_file	Write content to a file
append_file	Append content to a file
list_directory	List directory contents
file_info	Get file metadata
create_directory	Create a directory
delete_file	Delete a file
copy_file	Copy a file
move_file	Move or rename a file
search_files	Search for files by pattern

Permissions: read: ALLOW, write: ASK, delete: ASK

---

Shell

Execute commands and manage processes.

Action	Description
run	Execute a shell command
run_background	Run a command in the background
which	Find a command’s path
env	Get environment variables

Permissions: execute: ASK, elevated: DENY

---

Git

Full Git operations for version control.

Action	Description
status	Show working tree status
log	View commit history
diff	Show changes
add	Stage files
commit	Create a commit
branch	List or create branches
checkout	Switch branches
pull	Pull from remote
push	Push to remote
stash	Stash changes
reset	Reset changes
clone	Clone a repository

Permissions: read: ALLOW, write: ASK, push: ASK

---

Browser

Playwright-based browser automation for web interaction.

Action	Description
open	Open a new browser
navigate	Navigate to a URL
click	Click an element
type	Type text into an element
screenshot	Take a screenshot
get_text	Extract text from the page
get_html	Get page HTML
evaluate	Execute JavaScript
wait_for	Wait for an element
close	Close the browser
select	Select from a dropdown
scroll	Scroll the page
hover	Hover over an element
press_key	Press a keyboard key
drag	Drag an element to a target
pdf	Export the current page as PDF

Permissions: navigate: ASK, screenshot: ALLOW, execute: ASK

Tip

Install Playwright browsers before using this tool:

bunx playwright install chromium

---

Browser Extension

Control the user’s real browser via Octipus Chrome extension. Uses existing cookies, sessions, and authentication — no bot detection, no sandboxed environment.

Navigation & Tabs

Action	Description
navigate	Navigate the active tab to a URL
new_tab	Open a new browser tab
close_tab	Close a tab by ID
select_tab	Switch to a tab by ID
get_tabs	List all open browser tabs

Screenshots & Content

Action	Description
screenshot	Take a screenshot of the active tab
extract_content	Extract text, links, and forms from the page

Interactions

Action	Description
click	Click an element by CSS selector
fill	Fill an input field with a value
select	Select an option from a dropdown
hover	Hover over an element
press_key	Press a keyboard key
scroll	Scroll the page or an element
drag	Drag an element to a target

Waiting & Debugging

Action	Description
wait_for	Wait for an element or condition
highlight	Highlight an element on the page

JavaScript & State

Action	Description
evaluate	Execute JavaScript in the page context
get_cookies	Get cookies for a domain
set_cookies	Set cookies for a domain
get_storage	Read localStorage or sessionStorage
set_storage	Write localStorage or sessionStorage

Monitoring

Action	Description
get_console	Retrieve captured console log messages
get_network	Retrieve captured network requests

Dialogs

Action	Description
handle_dialog	Accept or dismiss a browser dialog

Permissions: navigate: ASK, screenshot: ALLOW, extract: ALLOW, interact: ASK, evaluate: ASK (dangerous), cookies: ASK (dangerous), tabs: ASK

Note

The Browser Extension requires Octipus Chrome extension to be installed and connected via WebSocket. It bridges commands to the user’s actual browser — unlike the Playwright-based Browser tool which runs a sandboxed headless instance.

---

Web Search

Search the web and fetch page content.

Action	Description
search	Search the web via SearXNG
fetch_page	Fetch and extract text from a URL

Permissions: search: ALLOW, fetch: ALLOW

The web search tool uses a multi-tier fallback:

1. SearXNG — primary meta-search engine (no bot blocking)
2. Google (Playwright) — browser-rendered Google search
3. DuckDuckGo (Playwright) — browser-rendered DuckDuckGo search

---

Docker

Manage Docker containers and images.

Action	Description
list_containers	List running containers
start_container	Start a container
stop_container	Stop a container
container_logs	View container logs
build_image	Build a Docker image
exec_command	Execute a command in a container

Permissions: read: ALLOW, manage: ASK

---

GitHub

Interact with GitHub repositories, issues, and pull requests.

Action	Description
list_repos	List repositories
get_repo	Get repository details
list_issues	List issues
create_issue	Create an issue
list_prs	List pull requests
get_pr	Get PR details with diff
create_pr	Create a pull request
review_pr	Add a review to a PR

Permissions: read: ALLOW, write: ASK

---

GitLab

Interact with GitLab projects, issues, and merge requests.

Action	Description
list_projects	List projects
get_project	Get project details
list_issues	List issues
create_issue	Create an issue
list_mrs	List merge requests
get_mr	Get merge request details
create_mr	Create a merge request

Permissions: read: ALLOW, write: ASK

---

Google Workspace

Interact with Gmail, Calendar, Drive, Docs, Sheets, Contacts, and Tasks.

Service	Actions
Gmail	gmail_list, gmail_search, gmail_read, gmail_send, gmail_reply, gmail_labels, gmail_label, gmail_delete
Calendar	calendar_list, calendar_events, calendar_event_get, calendar_event_create, calendar_event_update, calendar_event_delete
Drive	drive_list, drive_search, drive_download, drive_upload, drive_delete
Sheets	sheets_read, sheets_write, sheets_create, sheets_info
Docs	docs_read, docs_create, docs_update
Contacts	contacts_list, contacts_search, contacts_get, contacts_create
Tasks	tasks_lists, tasks_list, tasks_get, tasks_create, tasks_complete

Permissions: read: ALLOW, send: ASK, delete: ASK

---

Microsoft 365

Interact with Outlook Mail, Calendar, OneDrive, To Do, and Contacts.

Service	Actions
Mail	mail_list, mail_search, mail_read, mail_send, mail_reply, mail_folders, mail_delete
Calendar	calendar_list, calendar_events, calendar_event_get, calendar_event_create, calendar_event_update, calendar_event_delete
OneDrive	drive_list, drive_search, drive_download, drive_upload, drive_delete
To Do	todo_lists, todo_tasks, todo_task_get, todo_task_create, todo_task_complete
Contacts	contacts_list, contacts_search, contacts_get, contacts_create

Permissions: read: ALLOW, send: ASK, delete: ASK

---

Messaging

Send messages to connected channels (Telegram, Slack, Teams).

Action	Description
send	Send a message to a channel
list_channels	List connected channels

Permissions: send: ASK

---

Knowledge Base

Hybrid search and indexing over project files and tiered content. Supports multiple search modes: hybrid (BM25 + vector, default), fts (full-text only), and vector (semantic only).

Action	Description
search_knowledge	Hybrid search across indexed documents (BM25 + vector)
read_knowledge	Load full content for a specific entry
index_file	Index a file for search
index_directory	Index a directory recursively

Permissions: read: ALLOW, index: ALLOW

---

Documents

Process, categorize, and manage uploaded documents with OCR.

Action	Description
upload	Upload and queue documents for processing
list	List processed documents with filters
get	Get document details including OCR text

Permissions: read: ALLOW, upload: ASK

---

Scheduling

Create and manage hooks and scheduled tasks.

Action	Description
list_hooks	List automation hooks
create_hook	Create a new hook or scheduled task
update_hook	Update an existing hook
delete_hook	Delete a hook
toggle_hook	Enable or disable a hook

Permissions: read: ALLOW, manage: ASK

---

Tasks

Personal to-do items with completion tracking.

Action	Description
list_tasks	List all tasks with status
create_task	Create a new task
complete_task	Mark a task as complete
delete_task	Delete a task
update_task	Update a task

Permissions: read: ALLOW, write: ASK

---

Voice

Voice I/O and phone call integration.

Action	Description
initiate_call	Start an outbound call (notify or conversation mode)
continue_call	Send a message in an active call
end_call	Hang up an active call
get_status	Check call state
list_calls	List all active calls

Permissions: initiate: ASK, manage: ALLOW

---

Artifacts

Create, view, and manage artifacts (code snippets, documents, outputs).

Action	Description
create_artifact	Create a new artifact
list_artifacts	List artifacts
get_artifact	Get artifact details
update_artifact	Update an artifact
delete_artifact	Delete an artifact

Permissions: read: ALLOW, write: ASK, delete: ASK

---

Artifacts Toolbox

Utilities for working with artifacts (syntax highlighting, export, etc).

Action	Description
export_artifact	Export artifact in various formats
syntax_highlight	Apply syntax highlighting

Permissions: read: ALLOW

---

Visual

Image generation and analysis.

Action	Description
generate_image	Generate an image from a prompt
analyze_image	Analyze or describe an image

Permissions: generate: ASK, analyze: ALLOW

---

Task State

Read-only inter-agent workflow state tracking. Different from the Tasks tool — used for tracking agent-to-agent work status, not user to-do items.

Action	Description
read_state	Read workflow state for a task
list_states	List all workflow states

Permissions: read: ALLOW

Permission Levels

Each tool action has one of three permission levels:

Level	Behavior
ALLOW	Tool executes immediately without user intervention
ASK	Agent pauses and requests user approval before executing
DENY	Tool call is blocked entirely

Permissions can be customized per-user via the web UI Settings page or the API.

Tool Configuration

Tools are auto-discovered from src/tools/ at startup. To disable tools, modify the discovery config or set ENABLED_TOOLS environment variable:

ENABLED_TOOLS=filesystem,shell,git,browser,websearch,docker,github,gitlab,google-workspace,microsoft365,messaging,scheduling,tasks,voice,artifacts,visual,knowledge,documents,email-processor,profiles,browser-ext,task-state,artifacts-toolbox

All 24 tools are enabled by default if this variable is not set.

Note

Google Workspace and Microsoft 365 tools require OAuth configuration through the Settings page before they can be used.

New Tools

Email Processor

Provider-agnostic batch email processing. Iterates emails one-by-one with per-email classification and actions instead of dumping all into context.

Action	Description
process_emails	Fetch and return emails in batches with continuation tokens
get_email_summary	Get detailed summary of a single email

Supports both Gmail and Outlook. Includes pagination via page_token (Gmail) or skip (Outlook).

People & Profiles

Store and recall information about people, organizations, and relationships.

Action	Description
list_profiles	List all known people/entities
get_profile	Get profile by ID or name
create_profile	Create a new profile
add_fact	Add a fact (location, birthday, preference)
search_profiles	Search by name or fact values

The user’s own profile (isUserProfile: true) is automatically injected into every agent’s system prompt.

Plugin System

Extend Octipus with drop-in plugins. Create a directory in extensions/ with a plugin.json manifest and an index.ts entry file. Plugins are hot-loaded at startup and their tools are registered automatically.

extensions/
  my-plugin/
    plugin.json    # name, version, tools
    index.ts       # tool implementations

API: GET /api/plugins, POST /api/plugins/:name/reload

See the Plugins documentation for details.