Built-in Tools

Every built-in tool your Comis agents can use for files, shell commands, web access, and browser automation

Built-in tools are the core capabilities that come with every Comis agent. They handle file operations, shell commands, web access, and browser automation. These tools are always available unless you restrict them with a tool policy.

Where these fit. Comis ships 70 tools in total. The 13 documented in this page (plus the context tools and terminal driver tools below) are the framework-level “built-ins” that any coding-agent host would have. The remaining tools — messaging, scheduling, sessions, media, fleet admin, etc. — are platform tools layered on top. For per-tool guides with deeper examples, see the Agent Tools tab.

All Built-in Tools

Tool	What It Does	Config Toggle
read	Read file contents	builtinTools.read
write	Create or overwrite files	builtinTools.write
edit	Search-and-replace edits in files	builtinTools.edit
notebook_edit	Cell-level Jupyter notebook editing (insert, replace, delete cells)	builtinTools.notebookEdit
grep	Search file contents with patterns	builtinTools.grep
find	Find files by name pattern	builtinTools.find
ls	List directory contents	builtinTools.ls
exec	Run shell commands	builtinTools.exec
process	Manage background processes	builtinTools.process
web_search	Search the web (8 providers)	builtinTools.webSearch
web_fetch	Fetch and read web pages	builtinTools.webFetch
apply_patch	Apply multi-file patches	Enabled with edit
browser	Control a headless browser	builtinTools.browser

Tool Details

read -- Read file contents

Reads the contents of a file with line numbers. Useful for inspecting source code, configuration files, logs, or any text file in the workspace.

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Path to the file to read
offset	number	No	Start reading from this line number
limit	number	No	Maximum number of lines to return

Example usage:

# Read the first 50 lines of a config file
tool: read
path: config.yaml
limit: 50

Notes:

• Respects safe path rules — agents cannot read files outside the workspace directory
• Automatically detects binary files and returns a warning instead of garbled content
• Line numbers are included in the output for easy reference

write -- Create or overwrite files

Creates a new file or completely overwrites an existing file. Use this for creating new files from scratch. For surgical edits to existing files, use the edit tool instead.

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Path where the file should be created
content	string	Yes	The full content to write to the file

Example usage:

# Create a new configuration file
tool: write
path: settings.json
content: |
  {
    "theme": "dark",
    "language": "en"
  }

Notes:

• Automatically creates parent directories if they do not exist
• Respects safe path rules — agents cannot write files outside the workspace
• Overwrites the entire file — there is no append mode

edit -- Search-and-replace edits in files

Makes precise text replacements in an existing file. The agent specifies the exact text to find and the text to replace it with. This is safer than rewriting entire files because it only changes the targeted section.

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Path to the file to edit
old_string	string	Yes	Exact text to find (must match exactly)
new_string	string	Yes	Replacement text

Example usage:

# Change a configuration value
tool: edit
path: config.yaml
old_string: "port: 3000"
new_string: "port: 8080"

Notes:

• Requires an exact match — this is not a regular expression search
• Fails if old_string is not found in the file
• Fails if old_string appears more than once (ambiguous edit)
• Respects safe path rules

notebook_edit -- Cell-level Jupyter notebook editing

Edits Jupyter notebook (.ipynb) files at the cell level. Supports inserting new cells, replacing cell content, and deleting cells by index. This is safer than rewriting an entire notebook because it preserves cell metadata and outputs for unchanged cells.

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Path to the .ipynb notebook file
action	string	Yes	Action to perform: insert, replace, or delete
index	number	Yes	Cell index (0-based) to operate on
content	string	For insert/replace	Cell source content
cell_type	string	No	Cell type: code (default) or markdown

Example usage:

# Insert a new code cell at position 2
tool: notebook_edit
path: analysis.ipynb
action: insert
index: 2
content: "import pandas as pd\ndf = pd.read_csv('data.csv')"

# Replace cell content
tool: notebook_edit
path: analysis.ipynb
action: replace
index: 0
content: "# Updated Analysis\nThis notebook analyzes the Q4 results."
cell_type: markdown

Notes:

• Respects safe path rules — agents cannot edit notebooks outside the workspace
• Preserves cell outputs and metadata for unchanged cells
• Enabled via builtinTools.notebookEdit config toggle (default: true)

grep -- Search file contents with patterns

Searches through files using regular expression patterns, similar to the grep command-line tool. Returns matching lines with file paths and line numbers.

Parameters:

Parameter	Type	Required	Description
pattern	string	Yes	Regular expression pattern to search for
path	string	No	Directory to search in (defaults to workspace root)
include	string	No	File glob filter (e.g., *.ts, *.md)

Example usage:

# Find all TODO comments in TypeScript files
tool: grep
pattern: "TODO"
include: "*.ts"

Notes:

• Uses ripgrep under the hood for fast searching
• Respects .gitignore rules by default
• Safe path rules apply to the search directory

find -- Find files by name pattern

Finds files matching a glob pattern. Returns a list of file paths. Useful for locating files when you know part of the name but not the exact directory.

Parameters:

Parameter	Type	Required	Description
pattern	string	Yes	Glob pattern to match file names (e.g., *.config.ts)
path	string	No	Directory to search in (defaults to workspace root)

Example usage:

# Find all test files
tool: find
pattern: "*.test.ts"

Notes:

• Uses fd under the hood for fast file discovery
• Respects .gitignore and .fdignore rules
• Returns full paths relative to the workspace root

ls -- List directory contents

Lists the contents of a directory, including hidden files (dotfiles). Returns file and directory names in alphabetical order.

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Path to the directory to list

Example usage:

# List workspace root
tool: ls
path: "."

Notes:

• Shows dotfiles (files starting with .)
• Results are sorted alphabetically
• Respects safe path rules

apply_patch -- Apply multi-file patches

Applies a set of file operations (add, update, delete, move) in a single atomic operation. All changes succeed together or none are applied. This is useful when an agent needs to make coordinated changes across multiple files.

Parameters:

Parameter	Type	Required	Description
patch	string	Yes	Patch content in the *** Begin Patch format

The patch format supports four operations per file:

• Add — create a new file with specified content
• Update — modify specific sections of an existing file
• Delete — remove a file
• Move — rename or relocate a file

Notes:

• Atomic — all patches apply or none do, preventing partial updates
• Enabled when the edit config toggle is on
• Respects safe path rules for all file operations

exec -- Run shell commands

Runs a shell command and returns the output (stdout, stderr, and exit code). Supports foreground mode (waits for completion) and background mode (returns immediately).

Parameters:

Parameter	Type	Required	Description
command	string	Yes	The shell command to execute
cwd	string	No	Working directory (defaults to workspace root)
timeoutMs	number	No	Timeout in milliseconds (default 30000, max 300000)
env	object	No	Environment variable overrides
background	boolean	No	Run in background and return immediately
input	string	No	String to write to the process stdin

Example usage:

# Run a build command
tool: exec
command: "npm run build"
timeoutMs: 60000

# Run a server in the background
tool: exec
command: "node server.js"
background: true

Notes:

• OS-level sandbox (enabled by default) — on Linux, commands run inside a bubblewrap namespace where only the workspace, graph shared directory, and system binaries are visible. On macOS (dev only), sandbox-exec provides equivalent file-access restrictions. The agent cannot read other workspaces, home directory secrets, or system files — they simply do not exist inside the sandbox. Set execSandbox.enabled: "never" to disable (falls back to denylist-only protection).
• Blocks dangerous commands like rm -rf /, filesystem format commands, and piped script execution as an additional defense-in-depth measure
• Working directory is validated to prevent execution outside workspace bounds
• Dangerous environment variables (LD_PRELOAD, DYLD_*, etc.) are blocked
• Large outputs are automatically truncated with a notice showing the original size

process -- Manage background processes

Manages background processes that were started by the exec tool. Provides four actions for process lifecycle management.

Parameters:

Parameter	Type	Required	Description
action	string	Yes	Action to perform: list, kill, status, or log
sessionId	string	For kill/status/log	The session ID of the target process
offset	number	No	Line offset for log pagination
limit	number	No	Maximum lines to return for log (default 200)

Actions:

• list — show all background process sessions with status and command
• kill — terminate a running process (sends SIGTERM then SIGKILL)
• status — inspect a single process session
• log — read paginated output from a process

Notes:

• Only manages processes started by the agent via exec with background: true
• Each background process gets a unique session ID returned at creation time

web_search -- Search the web

Searches the web using one of 8 configurable search providers with automatic fallback. Returns a list of search results with titles, URLs, and descriptions.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query string
count	number	No	Number of results to return (1-10, default 5)
deepFetch	number	No	Auto-fetch full content for top N results (0-5, default 0)
country	string	No	2-letter country code for regional results (e.g., US, DE)
search_lang	string	No	ISO language code for results (e.g., en, fr)
freshness	string	No	Filter by time (Brave only): pd (past day), pw (past week), pm (past month), py (past year)
provider	string	No	Override search provider for this call

Available providers: Brave, Perplexity, Grok, DuckDuckGo, SearXNG, Tavily, Exa, Jina. DuckDuckGo requires no API key. Other providers need API keys configured in your Comis settings.

Example usage:

# Basic search
tool: web_search
query: "latest Node.js release"

# Search with full page content for top 3 results
tool: web_search
query: "TypeScript best practices"
deepFetch: 3
count: 5

Notes:

• Results are cached for 15 minutes by default to reduce API calls
• When deepFetch is greater than 0, the tool automatically fetches full page content for the top results, saving separate web_fetch calls
• If the primary provider fails, the tool automatically tries fallback providers
• See Web Tools Guide for provider setup details

web_fetch -- Fetch and read web pages

Fetches a URL and extracts the readable content. Converts HTML pages into clean Markdown or plain text using the Readability algorithm (the same technology behind browser reading modes).

Parameters:

Parameter	Type	Required	Description
url	string	Yes	HTTP or HTTPS URL to fetch
extractMode	string	No	Extraction mode: markdown (default) or text
maxChars	number	No	Maximum characters to return (default 50000)

Example usage:

# Fetch a documentation page
tool: web_fetch
url: "https://docs.example.com/guide"

# Get plain text with a smaller limit
tool: web_fetch
url: "https://news.example.com/article"
extractMode: "text"
maxChars: 10000

Notes:

• Uses SSRF (Server-Side Request Forgery) validation to prevent access to internal network addresses — agents cannot fetch localhost or private IPs
• Uses Chrome TLS fingerprinting to avoid bot detection on most websites
• Results are cached to reduce duplicate fetches
• JSON responses are automatically pretty-printed

browser -- Control a headless browser

Controls a headless Chromium browser for web research, form filling, and page interaction. Supports 16 different actions for full browser automation.

Key actions:

• navigate — go to a URL
• screenshot — capture the current page as an image
• snapshot — get the accessibility tree (a structured representation of page elements)
• act — interact with the page (click, type, fill, press keys, hover, scroll, select)
• start / stop — launch or close the browser
• tabs / open / close / focus — manage browser tabs
• console — read browser console logs
• pdf — save the current page as a PDF
• upload — upload files to file input elements
• dialog — handle browser dialogs (alerts, confirms, prompts)
• profiles — list available browser profiles
• status — check if the browser is running

Example usage:

# Navigate to a page and take a screenshot
tool: browser
action: navigate
targetUrl: "https://example.com"

tool: browser
action: screenshot

Notes:

• URLs are validated through the SSRF guard before navigation — agents cannot browse to internal network addresses
• The browser runs headless (no visible window) on the server
• Screenshots are returned as images that the agent can analyze
• See Browser Guide for the complete action reference with all parameters

Context Tools

Context tools help your agent search and recall information from the current conversation session. In the default DAG (LCD) mode the available tools are three in-session expansion tools — ctx_search, ctx_inspect, and ctx_expand — that recover detail the summary hierarchy compressed away within the current conversation. They are active only in DAG mode (contextEngine.version defaults to "dag"), never-export, and distinct from cross-session recall (memory_search, session_search). In the opt-in pipeline mode the available tool is session_search instead. See Context expansion tools and Compaction for how the engines work.

ctx_expand performs a bounded in-process multi-hop walk: starting from a summary, it descends the summary-parent hierarchy (condensed summary -> child summaries -> leaf summaries -> the underlying messages) and — when the knowledge graph is populated — fuses bounded KG hops, returning a ranked, cited evidence bundle. The walk is depth-capped per model tier (nano 1 / small 2 / mid 3 / frontier 4 hops), token-capped (maxExpandTokens), and node-visit capped, so it can never run away on a deep or cyclic hierarchy. It is read-only, runs inside the per-conversation single-flight serializer, secret-scrubs and taint-wraps every recovered region on re-entry, and spills oversized output to a session file. It is not a sub-agent — the walk is deterministic and in-process. When the knowledge graph is empty (the default), the walk degrades cleanly to summary-parent edges only.

Availability

Tool	Pipeline Mode	DAG Mode	Description
session_search	Yes	Yes	Search current session history
ctx_search	No	Yes	Full-text search over this conversation’s compressed history
ctx_inspect	No	Yes	Inspect a compressed summary’s metadata and children
ctx_expand	No	Yes	Bounded multi-hop walk that recovers a compressed region’s underlying detail (depth-capped per model tier) as a ranked, cited bundle

session_search -- Search session history

Searches through the current conversation session history using case-insensitive substring matching. Available in pipeline mode.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search pattern (case-insensitive substring match)
scope	string	No	Filter by message role: "all" (default), "user", "assistant", "tool"
limit	number	No	Maximum results to return (1-30, default 10)

Notes:

• Search results are protected from observation masking, so recovered content remains visible
• This tool is registered as a protected tool name — its results survive compaction

ctx_expand -- Multi-hop recover a compressed region (DAG mode)

Recovers the underlying detail of a compressed summary region of the current conversation via a bounded in-process multi-hop walk. Given a summary id (from ctx_search / ctx_inspect), it descends the summary-parent hierarchy — a condensed summary’s child summaries, then their leaf summaries, then the underlying messages — and returns a ranked, cited evidence bundle. Available in DAG mode only.

Parameters:

Parameter	Type	Required	Description
summaryId	string	Yes	The summary id (from ctx_search / ctx_inspect) whose compressed region to recover

Caps (the walk is always bounded):

Cap	Bound
Depth	Tier-gated per the agent’s model: nano 1, small 2, mid 3, frontier 4 hops
Tokens	contextEngine.maxExpandTokens (default 4000) — oversized output spills to a session file with a handle
Node visits	Capped so a wide or cyclic hierarchy can never run away (a visited-set makes it cycle-safe)

Notes:

• Read-only and runs inside the per-conversation single-flight serializer, so it never interleaves with a concurrent compaction write.
• Every recovered region is secret-scrubbed and taint-wrapped on re-entry (untrusted content), and large bundles spill to a session file you can read with the file tools.
• The knowledge-graph (KG) hop is optional: when the KG is empty or disabled (the default), the walk degrades cleanly to summary-parent edges only — the KG is never a precondition.
• It is not a sub-agent: the walk is deterministic and in-process. A drifted (missing) message id is skipped, never fatal — the result reports a partial-coverage count.

Terminal Driver

Nine tools for driving interactive terminal sessions (v2.11). Each tool requires an operator-configured allowlist (allowEntries) — without a matching allowlist entry the tool rejects. Designed for use with the bubblewrap sandbox on Linux. See exec sandbox for the bubblewrap sandbox that terminal tools require.

Tool	Description
terminal_session_create	Start an interactive terminal session driving an allowlisted binary. Fail-closed without a sandbox provider.
terminal_session_read	Read buffered output from an active terminal session (accumulated bytes since last read).
terminal_session_list	List all active terminal sessions for the current agent.
terminal_session_kill	Terminate an active terminal session and free its resources.
terminal_session_send_text	Write text to a terminal session’s stdin.
terminal_session_send_key	Send a named keypress (e.g., Enter, Ctrl-C) to a terminal session.
terminal_session_resize	Resize a terminal session’s pseudo-TTY (cols x rows).
terminal_session_wait	Wait for a terminal session to produce matching output or a timeout.
terminal_session_status	Registered with its final schema; execute rejects with [not_implemented] until the implementation lands.

terminal_session_status is a registered stub — its schema is final but the execute handler immediately returns [not_implemented]. All other eight terminal tools are fully implemented.

Disabling Tools

Each built-in tool can be individually toggled off through configuration. This is useful when you want to restrict what an agent can do at the config level, independent of the tool policy:

skills:
  builtinTools:
    exec: false      # Disable shell commands
    browser: false   # Disable browser automation
    write: false     # Disable file creation
    webSearch: false  # Disable web search

When a tool is disabled via config, it is completely removed from the agent’s available tools — the agent will not even know it exists. This is different from the tool policy, which can deny access to a tool but still lets the agent see it.

See Configuration Reference for the full list of config options.

Related

Platform Tools

Comis-specific tools for messaging, scheduling, and administration

Tool Policy

Control which tools each agent can use

Web Tools Guide

Web search providers and URL content fetching

Browser Guide

Headless browser automation with 16 actions