Using it
Builtin tools
What the agent can actually call. Read out of the tool registry and each tool's own class, so this page cannot list a tool that is gone or miss one that shipped.
Not the CLI
These are agent tools — the functions the model calls mid-turn (
bash, write_file, web_search). The CLI reference is a different thing: the oara subcommands you type, generated from the argument parser. Two inventories, two generators, two pages. Keep them apart.
Generated
Produced by
gen-tools.py from create_tool_registry in prometheus/__main__.py and the name / description each tool class declares. Descriptions are the text the model sees, verbatim. Regenerate with python3 gen-tools.py --src <checkout> > docs-src/tools.body.html. A tool nobody files under a heading aborts the build rather than disappearing.
Captured from Prometheus at feca69e: 51 tools register on every install, plus 3 that register when their subsystem is on (marked below). Dynamic MCP tools extend the set at runtime and are not listed here.
How they run
Each turn's tool calls are partitioned by is_read_only(). Read-only calls run concurrently under asyncio.gather; mutating calls run one at a time, in order. The security gate's PreToolUse and PostToolUse hooks fire on every call regardless. See Tokens and the open web API for what the gate refuses.
Files and shell
The working set. Where most calls land.
| Tool | What it does |
|---|---|
bash | Run a short shell command in the local repository. For work that outlives this turn (long builds, downloads, file watches) use task_create instead of 'nohup … &' — a backgrounded Bash job is killed at the timeout and left untracked. |
read_file | Read a text file from the local repository. |
write_file | Create or overwrite a file with UTF-8 text content, written verbatim. Handles any text-based format (.md, .py, .json, .csv, .svg, .html). For binary or converted formats (.pdf, .docx, .xlsx, images), write the source as text with this tool, then convert it via bash (e.g. pandoc, python-docx, libreoffice) — do not refuse these formats. |
edit_file | Edit an existing file by replacing a string. |
grep | Search file contents with a regular expression. |
glob | List files matching a glob pattern. |
notebook_edit | Edit a cell in a Jupyter notebook (.ipynb). Can replace or append cells, and creates the notebook if it doesn't exist. |
Work that outlives the turn
Managed background tasks and the sessions that run them.
| Tool | What it does |
|---|---|
task_create | Create a managed background task instead of running a long job with 'nohup … &'. Types: local_bash (shell command), local_agent (sub-agent prompt), file_watch (wait for a file matching a glob), poll (run a predicate command until it succeeds). The daemon detects completion and sends a Telegram notification; set on_complete='reengage'/'both' to also have the agent act on the result. Returns a task id immediately. |
task_get | Get the status and details for a background task. |
task_list | List all background tasks, optionally filtered by status. |
task_update | Update a task's description, progress percentage, or status note. |
task_stop | Stop (terminate) a background task. |
task_output | Read the tail of a background task's output log. |
sessions_list | List agent sessions (background tasks) with their IDs, status, and descriptions. Use to discover running agents. |
sessions_send | Send a text message to a running agent session (by task ID). The message is written to the session's stdin. |
sessions_spawn | Create a new background agent session with the given prompt. Returns the session/task ID for tracking. |
agent | Launch a subagent to handle a complex task autonomously. The subagent runs with isolated context and returns its result. |
Web and media
Fetching, searching, generating.
| Tool | What it does |
|---|---|
web_search | Search the web via DuckDuckGo and return top results with titles, URLs, and snippets. Use this when you don't know a specific URL: finding documentation, looking up current facts (versions, prices, news), discovering libraries or repositories, comparing options, or researching unfamiliar topics. Once you have a URL from search results, use web_fetch to read its full content. No API key required. |
web_fetch | Fetch any URL (web page, GitHub repo, API endpoint, raw file) and return its text content. Use this for: fetching GitHub repos, reading documentation, calling JSON APIs, reading any public URL. Handles 404/403/private URLs gracefully without crashing. |
browser | Headless browser automation for pages that require JavaScript rendering, login flows, or interactive elements. Use web_fetch instead for simple URL fetching — only use browser when the page won't work without JavaScript. |
youtube_transcript | Fetch the transcript/subtitles from a YouTube video by URL or video ID. Returns the full text content without downloading the video. |
download_file | Download a file from a URL to local disk. Saves to ~/.prometheus/downloads/ by default. Streams with a size limit. |
image_generate | Generate an image from a text prompt. Backends: 'pollinations' (free hosted, no key), 'comfyui' (local GPU, FLUX-backed, sovereign), 'dashscope' (PAID Alibaba WAN 2.5 — only when explicitly requested). Default 'auto' picks comfyui when reachable else pollinations; auto NEVER picks the paid backend. Returns the path to the saved image. Defaults: 1024x1024, flux model. Set seed for reproducible output. |
video_generate | Generate a video from a text prompt via the Kling 3.0 API (PAID — requires KLING_ACCESS_KEY + KLING_SECRET_KEY). Pass image_path for image-to-video (the image becomes the first frame). Durations 5 or 10 seconds. Generation takes MINUTES — the tool waits and polls. Returns the path to the saved .mp4 in ~/.prometheus/cache/videos/. |
tts | Convert text to speech audio using a local engine (espeak-ng or piper). Returns the path to the generated audio file. |
dashboard | Start a lightweight HTTP server that serves the provided HTML content. Returns the URL to view the dashboard. Binds to localhost by default, so the URL is reachable from this machine only; an operator can widen it with the security.dashboard_tool_bind_host config key, in which case the URL names the Tailscale or LAN address. |
Memory, wiki and context
What the daemon remembers, and how the agent reads it back.
| Tool | What it does |
|---|---|
memory | Manage persistent memory entries. Call 'add' when the user shares a durable fact about themselves (preferences, key contacts, ongoing projects) or about the system (infrastructure, conventions, decisions) that should persist across sessions. Use 'replace' to update, 'remove' to delete, 'list' to read all entries. |
wiki_compile | Compile extracted memory facts into the Prometheus wiki. Pass an entity_name to compile facts for a single entity, or omit it to compile all facts since the last compilation. |
wiki_query | Search the Prometheus wiki for answers to knowledge questions. Returns relevant wiki page content. Substantial multi-page answers are saved to wiki/queries/ for future reference. |
wiki_lint | Scan the wiki for health issues: orphan pages, broken links, stale pages, duplicate entities, missing cross-references, and category imbalance. Optionally auto-fix safe issues. |
lcm_grep | Search conversation history and summaries using FTS5 full-text search. Returns matching messages and/or summary nodes ranked by relevance. |
lcm_expand | Expand an LCM summary node to see its source content. Depth-0 summaries expand to original messages; higher-depth summaries expand to child summary nodes. |
lcm_describe | Show metadata for a specific LCM summary node (depth, parents, source count, token count, etc.) or overall LCM statistics (total messages, summaries, max depth, compression ratio). |
lcm_expand_query | Search compressed conversation history for context relevant to a question, then expand the most relevant summary nodes back to their original messages. Use this when you need to recall details from earlier in the conversation that may have been compressed by LCM. |
vault_search | Search the BRAIN VAULT — Will's second brain, compiled from his full claude.ai and Claude Code history: projects, decisions, people, companies and standing engineering principles. Returns matching page paths with context; read a full page with vault_read. Searches the vault's compiled wiki/ tree. This is NOT the Prometheus wiki (wiki_query) — different knowledge, different root. |
vault_read | Read a file from the BRAIN VAULT by its vault-relative path — compiled pages under wiki/, original sources under raw/, human notes under notes/. Read-only. Large files come in windows: a partial read names the true size, the next offset, and an outline of '@offset heading' jump targets. Use vault_search first to find the path (its context lines carry @offset for jumping). |
Scheduling and people
Cron, messages out, questions back.
| Tool | What it does |
|---|---|
cron_create | Create or replace a local cron job. Accepts standard 5-field cron expressions OR natural-language phrases like 'every Monday at 9am' or 'in 30 minutes'. Jobs are executed by the Prometheus cron scheduler. |
cron_delete | Delete a local cron job by its unique name. |
cron_list | List all registered cron jobs with schedule, status, and next run time. |
message | Send a text message to Discord (webhook), Slack (webhook/bot), Telegram (bot API), or a generic webhook endpoint. |
ask_user | Ask the user a question and wait for their response. Use when you need clarification before proceeding. |
todo_write | Append a TODO item to a project markdown checklist. |
Introspection
The daemon looking at itself.
| Tool | What it does |
|---|---|
anatomy | Query Prometheus infrastructure state — hardware, loaded model, VRAM, services, project configurations, and architecture diagrams. |
sentinel_status | Returns the current state of the SENTINEL proactive subsystem: observer state, dream engine state, recent signals, pending nudges, and last dream cycle results. |
audit_query | Query recent security gate decisions. Use to debug why something was blocked. — registers when the security gate has an audit log (it does by default) |
tool_search | Search for available tools and skills by name or description. Use 'search' to find tools or skills matching a query, or 'select' to load a specific tool by exact name. Use the skill tool to load a skill's instructions. |
skill | Read a builtin or user-defined skill by name. |
mcp_status | Show MCP server connection status and available tools. — daemon only, when MCP servers are configured |
lsp | Code intelligence: get definitions, references, type info, diagnostics, and document symbols via LSP. Use the 'context' action to get definition + references + type info in a single call (recommended). — daemon only, when lsp.enabled is true |
SYMBIOTE
Code assimilation. Experimental, off by default; the tools register but the coordinator behind them only runs when symbiote.enabled is true.
| Tool | What it does |
|---|---|
github_search | Search GitHub for open-source repositories matching a capability need. Returns a JSON array of candidates with name, description, stars, language, license, and a README excerpt. |
symbiote_scout | Search GitHub for open-source solutions to a capability gap. Returns a ranked candidate list. Read-only; no clones, no writes. |
symbiote_harvest | Clone an approved GitHub repository, scan its source, extract relevant modules. Requires Trust Level 1 approval upstream. |
symbiote_graft | Apply the harvest's adaptation plan: write adapted files with provenance headers, generate tests, run the suite, update PROMETHEUS.md. Requires Trust Level 1 approval upstream. |
symbiote_status | Return the current SYMBIOTE session state (or a named session). Optionally include the most recent N past sessions. |
If a tool here reads wrong, the fix is its description in the source — this page follows it.