Tools

KosmoKrator ships with a full suite of built-in tools that the agent uses to read, write, search, and execute code. This page is the complete reference for every tool, its parameters, and typical usage patterns.

Tools requiring approval (file_write, file_edit, apply_patch, bash, shell_start, shell_write, and execute_lua) depend on your permission mode. In Prometheus mode governed prompts are auto-approved, but blocked paths and explicit deny rules are still enforced.

File Operations

file_read

Read a file from the project with line numbers. Supports partial reads via offset/limit and includes an automatic caching layer: if a file has not changed since the last read, the tool returns [Unchanged since last file_read of path (lines X-Y); content omitted to save tokens] instead of re-sending the full contents. Files larger than 10 MB are streamed line-by-line to avoid memory pressure.

Parameter	Type	Required	Description
path	string	Yes	Absolute or project-relative path to the file.
offset	int	No	Line number to start reading from (1-based). Omit to start from the beginning.
limit	int	No	Maximum number of lines to return. Omit to read the entire file.

Example: Read lines 50–80 of a controller:

file_read path="src/Controller/UserController.php" offset=50 limit=30

When the agent is exploring a large file it will often use offset and limit to read only the relevant section, keeping the context window lean.

file_write

Create a new file or completely overwrite an existing one. Any missing parent directories are created automatically. Returns the total line count of the written file.

Parameter	Type	Required	Description
path	string	Yes	Absolute or project-relative path for the file.
content	string	Yes	The full content to write.

Example: Create a new configuration file:

file_write path="config/cache.yaml" content="cache:\n  driver: redis\n  ttl: 3600\n"

file_edit

Perform a targeted find-and-replace within a file. The old_string must appear exactly once in the file; if it matches zero or more than one location the edit is rejected. Returns the edit summary with separate removed and added line counts (e.g., "Edited path (-5, +3 lines)").

Parameter	Type	Required	Description
path	string	Yes	Path to the file to edit.
old_string	string	Yes	The exact text to find. Must match exactly once.
new_string	string	Yes	The replacement text.

Example: Rename a method call:

file_edit path="src/Service/Mailer.php" \
  old_string="$this->sendLegacy($message)" \
  new_string="$this->send($message)"

The agent prefers file_edit over file_write for surgical changes because it only transmits the diff, keeping token usage low and making approval review easier.

apply_patch

Apply a structured patch to one or more files. Uses KosmoKrator’s custom patch format with *** Begin Patch / *** End Patch delimiters and file-level markers: *** Add File:, *** Update File:, and *** Delete File:. Supports multi-file, multi-hunk patches. The parser streams the patch content for memory efficiency, making it suitable for large changesets.

Parameter	Type	Required	Description
patch	string	Yes	The patch content using *** Begin Patch / *** End Patch format.

Example: Apply a multi-file patch:

apply_patch patch="*** Begin Patch
*** Update File: src/Model/User.php
@@ -12,6 +12,7 @@ class User
     public string $name;
     public string $email;
+    public ?string $avatar = null;

     public function __construct(string $name)
*** Update File: tests/UserTest.php
@@ -8,4 +8,10 @@ class UserTest extends TestCase
     {
         $this->assertInstanceOf(User::class, new User('Ada'));
     }
+
+    public function test_avatar_defaults_to_null(): void
+    {
+        $user = new User('Ada');
+        $this->assertNull($user->avatar);
+    }
 }
*** End Patch"

Search

glob

Fast file-name pattern matching across the project tree. Automatically skips common non-project directories (.git, vendor, node_modules). Returns up to 200 matching file paths, sorted by name.

Parameter	Type	Required	Description
pattern	string	Yes	Glob pattern to match (e.g. **/*.php, src/Model/*.php).
path	string	No	Base directory to search from. Defaults to the project root.

Example: Find all migration files:

glob pattern="database/migrations/*.php"

grep

Regex-powered content search. Uses ripgrep when available on the system for maximum speed; falls back to GNU grep otherwise. Returns up to 50 matches per file, capped at 100 output lines, each with file path and line number.

Parameter	Type	Required	Description
pattern	string	Yes	Regular expression pattern to search for.
path	string	No	File or directory to search in. Defaults to the project root.
glob	string	No	File name filter (e.g. *.php, *.ts).

Example: Find all usages of a deprecated method in PHP files:

grep pattern="->sendLegacy\(" glob="*.php"

The agent typically combines glob and grep in sequence: first glob to discover which files exist, then grep to find specific patterns inside them.

Web

KosmoKrator keeps native web_fetch separate from optional external web providers. External search, extract, and crawl tools are disabled by default and only run after you enable the related web.* settings or configure a provider with web:configure.

web_search

Search the web through Tavily, Firecrawl, Exa, Brave Search, Parallel, Jina, SearXNG, Perplexity, OpenAI native web search, or Anthropic native web search.

Parameter	Type	Required	Description
query	string	Yes	Search query.
provider	enum	No	Override web.search.provider.
max_results	int	No	Defaults to web.search.max_results.
mode	enum	No	Provider hint such as fast, deep, cached, or live.
allowed_domains, blocked_domains	array	No	Domain filters when supported.

web_search query="Symfony TUI latest release" provider="tavily" max_results=5

web_fetch_external / web_extract

Fetch or extract a specific URL through an external provider. This does not replace native web_fetch; native fetch remains the default for providers that expose it directly. External fetch is approval-gated by default.

Parameter	Type	Required	Description
url	string	Yes	URL to fetch.
provider	enum	No	Override web.fetch.provider.
format	enum	No	markdown, text, or html.

web_fetch_external url="https://symfony.com/blog/" provider="firecrawl" format="markdown"

web_crawl

Crawl multiple pages from a site with Tavily or Firecrawl. Crawling is disabled by default and approval-gated because it can expand one user request into many external fetches.

Parameter	Type	Required	Description
url	string	Yes	Starting URL.
provider	enum	No	Override web.crawl.provider.
max_pages	int	No	Defaults to web.crawl.max_pages.
instructions	string	No	Optional provider-specific crawl instructions.

web_crawl url="https://docs.example.com" provider="tavily" max_pages=10

Shell

bash

Execute a shell command in the project directory. Output (combined stdout and stderr) is streamed via a progress callback so the UI can display it in real time. The result includes the full output text and the process exit code.

Parameter	Type	Required	Description
command	string	Yes	The shell command to execute.
timeout	int	No	Maximum execution time in seconds. Default: 120. Maximum: 7200 (2 hours).

Example: Run the test suite with a generous timeout:

bash command="php vendor/bin/phpunit --testdox" timeout=300

Shell Sessions

Interactive persistent shell sessions allow the agent to start long-running processes (dev servers, watchers, REPLs) and interact with them over time. Each session gets a unique ID and persists until explicitly killed or the agent session ends.

shell_start

Start a new interactive shell session.

Parameter	Type	Required	Description
command	string	Yes	The command to start (e.g. php artisan tinker, npm run dev).
cwd	string	No	Working directory for the session. Defaults to the project root.
timeout	int	No	Inactivity timeout in seconds before the session is auto-terminated.
wait_ms	int	No	Milliseconds to wait for initial output after starting.

shell_write

Send input to a running shell session.

Parameter	Type	Required	Description
session_id	string	Yes	The session ID returned by shell_start.
input	string	Yes	The text to send to the session’s stdin.
submit	boolean	No	Whether to append a newline after the input. Defaults to true.
wait_ms	int	No	Milliseconds to wait for output after writing.

shell_read

Read buffered output from a running shell session.

Parameter	Type	Required	Description
session_id	string	Yes	The session ID.
wait_ms	int	No	Milliseconds to wait for new output before returning.

shell_kill

Terminate a running shell session.

Parameter	Type	Required	Description
session_id	string	Yes	The session ID to terminate.

Example: Start a dev server, verify it boots, then tear it down:

# Start the server
shell_start command="php artisan serve --port=8080" wait_ms=2000
# Returns: { session_id: "sess_abc123", output: "Starting development server..." }

# Check that it is responding
shell_read session_id="sess_abc123" wait_ms=1000

# Shut it down when done
shell_kill session_id="sess_abc123"

Agent Coordination

subagent

Spawn a child agent that runs in its own context window. Subagents inherit the project’s tool set and permission mode but operate independently. They can run in the foreground (await) or background, form dependency chains, and be grouped for batch execution. See Agents for the full subagent architecture guide.

Parameter	Type	Required	Description
task	string	No	Natural-language description of what the subagent should accomplish.
type	string	No	Agent type: general (full tool access, default), explore (read-only tools), or plan (no tools, planning only).
mode	string	No	await (block until complete, default) or background (run concurrently).
id	string	No	Custom identifier for referencing in dependency chains.
depends_on	array	No	List of subagent IDs that must complete before this one starts.
group	string	No	Sequential execution group — agents in the same group run one at a time.
agents	array	No	Batch mode: array of agent specs to run concurrently. Each spec is an object with task (required), type, id, depends_on, and group. When set, the top-level task, type, id, depends_on, and group parameters are ignored.

Example: Fan out three explore agents, then merge their findings:

# Phase 1: parallel exploration
subagent task="Map the authentication flow" type="explore" mode="background" id="auth"
subagent task="Map the payment flow" type="explore" mode="background" id="pay"
subagent task="Map the notification flow" type="explore" mode="background" id="notify"

# Phase 2: plan based on all three
subagent task="Design a unified event system based on the auth, payment, and notification flows" \
  type="plan" mode="await" depends_on=["auth","pay","notify"]

Memory

memory_save

Persist a piece of knowledge to the memory store so it survives across sessions. Memories are stored as Markdown files and can be scoped to the project, the user, or tagged as architectural decisions.

Parameter	Type	Required	Description
type	string	Yes	Memory scope: project (codebase facts, architecture), user (preferences, workflow), or decision (architectural choices, trade-offs).
title	string	Yes	Short descriptive title for the memory.
content	string	Yes	Markdown content — the knowledge to persist.
class	string	No	Memory class: priority, working, or durable (default).
pinned	boolean	No	Whether the memory should be favored during recall.
expires_days	number	No	Optional expiry in days — useful for working memory.
id	string	No	Existing memory ID to update. Omit to create a new memory.

Example: Record an architectural decision:

memory_save type="decision" \
  title="Use event sourcing for orders" \
  content="## Context\nOrder history is critical for auditing.\n\n## Decision\nAll order mutations go through an event store."

memory_search

Search and list saved memories. Use to recall project facts, user preferences, or past decisions before asking the user. Returns ranked results with title, type, and content preview.

Parameter	Type	Required	Description
query	string	No	Text to search for in memory titles and content.
type	string	No	Filter by memory type: project, user, decision, or compaction.
class	string	No	Filter by memory class: priority, working, or durable.
scope	string	No	Search scope: memories (default), history, or both.

Example: Recall a previous decision about caching:

memory_search query="caching strategy"

Session History

Session tools let the agent browse and search prior KosmoKrator conversations for the current project. They are useful when a user refers to earlier work, asks what happened last time, or wants the agent to reuse decisions from a previous session.

session_search

Browse recent sessions or search across saved session history. With no query, it returns recent sessions with IDs, titles, dates, message counts, and a preview. With a query, it performs keyword search and groups matches by session.

Parameter	Type	Required	Description
query	string	No	Search terms, exact phrases in quotes, or file paths. Omit to browse recent sessions.
limit	integer	No	Maximum number of sessions or search groups to return. Defaults to 5, max 10.

Example: Find previous work on authentication:

session_search query="authentication middleware" limit=5

session_read

Load a prior session transcript by full ID or unique prefix. Use this after session_search when the agent needs the detailed context from a specific past conversation.

Parameter	Type	Required	Description
session_id	string	Yes	Session ID or unique prefix. session_search shows short prefixes in brackets.
limit	integer	No	Maximum messages to return. Defaults to 50, max 200.

Example: Read a matching session:

session_read session_id="a1b2c3d4" limit=80

Tasks

The task system lets the agent track multi-step work items. Tasks persist in the session and appear in the UI’s context bar so both the agent and the user can see progress at a glance.

task_create

Create one or more tasks to track work progress. Use subject for a single task, or tasks (JSON array) to create multiple at once. Each task can optionally be nested under a parent. Provide either subject or tasks, but not both.

Parameter	Type	Required	Description
subject	string	No*	Task title (for creating a single task).
description	string	No	Task details or acceptance criteria (single task mode).
active_form	string	No	Present-continuous label for the spinner, e.g. "Running tests" (single task mode).
parent_id	string	No	Parent task ID for nesting (single task mode).
tasks	string	No*	JSON array of task objects for batch creation. Each object: {"subject": "...", "description": "...", "active_form": "...", "parent_id": "..."}. Only subject is required per object.

* Must provide either subject (single) or tasks (batch), but not both.

Example:

task_create subject="Migrate user table to UUIDs" description="Replace auto-increment IDs with UUIDv7 primary keys."

Example: Batch-create multiple tasks:

task_create tasks='[{"subject":"Add avatar column","active_form":"Adding avatar column"},{"subject":"Update user factory","active_form":"Updating user factory"}]'

task_update

Update a task’s status, subject, description, or dependencies. Status flow: pending → in_progress → completed | cancelled.

Parameter	Type	Required	Description
id	string	Yes	The task ID.
status	string	No	New status: pending, in_progress, completed, or cancelled.
subject	string	No	Updated task title.
description	string	No	Updated task details.
active_form	string	No	Updated spinner label.
add_blocked_by	string	No	JSON array of task IDs that block this task.
add_blocks	string	No	JSON array of task IDs this task blocks.

Example:

task_update id="task_001" status="completed"

task_get

Retrieve full details of a single task.

Parameter	Type	Required	Description
id	string	Yes	The task ID to retrieve.

Example:

task_get id="task_001"

task_list

List all tasks in the current session. Returns every task with its ID, title, status, and creation timestamp. Takes no parameters.

Parameter	Type	Required	Description
No parameters.

Example:

task_list

Lua Scripting

The Lua scripting tools let the agent execute Lua code inside a sandboxed environment with access to integration APIs and native tools. Always start by discovering available namespaces with lua_list_docs, then read detailed docs with lua_read_doc before writing code.

For the full Lua model — host-side Lua tools, app.integrations.*, app.mcp.*, app.tools.*, multi-account namespaces, and discovery workflow — see Lua.

execute_lua

Execute Lua code with app.* namespace access. Use app.integrations.* for OpenCompany integration calls, app.mcp.* for configured MCP server calls, and app.tools.* for native tools (file_read, glob, grep, bash, subagent, etc.). Always use lua_read_doc first to look up function names and parameters. Use print() or dump() for output.

Parameter	Type	Required	Description
code	string	Yes	Lua code to execute. Use print()/dump() for output. Access integrations via app.integrations.{name}.{function}() and MCP tools via app.mcp.{server}.{tool}().
memoryLimit	integer	No	Memory limit in bytes. Default: 33554432 (32 MB).
cpuLimit	number	No	CPU time limit in seconds. Default: 30.0.

Example: Query an integration and print the result:

execute_lua code="local stats = app.integrations.plausible.query_stats({site_id='example.com'})
print(stats.visitors)"

Example: Call an MCP server tool from Lua:

lua_read_doc page="mcp.github"
execute_lua code="local repos = app.mcp.github.search_repositories({query='kosmokrator'})
dump(repos)"

lua_list_docs

List available Lua API namespaces and functions. Each namespace maps to an integration (plausible, coingecko, celestial, etc.), MCP server, or native Lua tool namespace. Shows function signatures with parameter names. Use this first to discover what is available.

Parameter	Type	Required	Description
namespace	string	No	Filter to a specific namespace (e.g. "integrations.plausible" or "mcp.github"). Omit to list all.

Example: List all available namespaces:

lua_list_docs

Example: Show functions in a specific integration:

lua_list_docs namespace="integrations.plausible"

Example: Show functions in a specific MCP server:

lua_list_docs namespace="mcp.github"

lua_search_docs

Search the Lua scripting API documentation by keyword. Searches function names, descriptions, and parameter info across all available namespaces and supplementary docs.

Parameter	Type	Required	Description
query	string	Yes	The search query (e.g. "send message", "analytics", "query stats").
limit	integer	No	Maximum number of results. Default: 10.

Example:

lua_search_docs query="analytics" limit=5

lua_read_doc

Read Lua API documentation for a namespace, function, or guide.

• Namespace (e.g. "integrations.plausible" or "mcp.github") → full API reference with all functions and parameters
• Function (e.g. "integrations.plausible.query_stats" or "mcp.github.search_repositories") → detailed single-function docs
• Guide (e.g. "overview", "examples") → supplementary documentation

Always use lua_read_doc before writing Lua code to confirm function names and parameters.

Parameter	Type	Required	Description
page	string	Yes	Page to read: namespace (e.g. "integrations.plausible"), function path (e.g. "integrations.plausible.query_stats" or "mcp.github.search_repositories"), or guide name (e.g. "overview", "examples").

Example:

lua_read_doc page="integrations.plausible.query_stats"

Example:

lua_read_doc page="mcp.github.search_repositories"

Interactive

Interactive tools let the agent ask the user for input mid-task. This is useful when the agent encounters an ambiguous situation and needs clarification rather than guessing.

ask_user

Pose a free-form question to the user. The agent pauses and waits for the user’s typed response before continuing.

Parameter	Type	Required	Description
question	string	Yes	The question to display to the user.

Example:

ask_user question="The tests reference a 'staging' database. Should I use the local SQLite DB or set up a MySQL container?"

ask_choice

Present a set of discrete choices to the user. The UI renders them as a numbered list (ANSI mode) or selectable options (TUI mode). Each choice is a JSON object with label (required), detail (optional description), and recommended (optional boolean to highlight the suggested option).

Parameter	Type	Required	Description
question	string	Yes	The question or prompt text.
choices	string	Yes	JSON array of choice objects. Each object: {"label": "...", "detail": "...", "recommended": true/false}. Only label is required per object.

Example: Let the user pick a database driver:

ask_choice \
  question="Which database driver should this project use?" \
  choices='[{"label":"SQLite","detail":"Lightweight, zero config","recommended":true},{"label":"MySQL","detail":"Production-grade"},{"label":"PostgreSQL","detail":"Advanced features"}]'

Tool Internals

This section describes how KosmoKrator executes tool calls under the hood. Understanding the pipeline is helpful when debugging unexpected behaviour, tuning performance, or writing custom tool integrations.

Tool Execution Pipeline

When the LLM response contains one or more tool calls, KosmoKrator processes them through a multi-stage pipeline:

1. ToolExecutor receives tool calls — the executor collects all tool calls from the parsed LLM response. Each call includes the tool name and a map of parameters.
2. Permission check — before any tool runs, the Permissions system validates the call against the active policy. Calls that require approval are queued for user confirmation (or rejected outright in strict mode).
3. Concurrent partitioning — independent tool calls are grouped and executed in parallel (see Concurrent Execution below).
4. Results streamed back — tool results are returned to the LLM as part of the conversation, enabling the next reasoning step.

Tip: The entire pipeline is visible in the TUI’s Tools panel. You can watch each stage — permission check, execution, and result — in real time as the agent works.

Concurrent Execution

The executor partitions tool calls into groups based on their dependencies and runs independent groups concurrently:

Partition	Behaviour	Examples
Independent calls	Run in parallel when no file paths overlap.	Reading src/A.php and src/B.php simultaneously.
Overlapping file calls	Serialized to prevent race conditions.	A file_read followed by file_edit on the same file.
Subagent spawns	Handled on a separate worker pool; do not block regular tools.	subagent calls for parallel research or delegated work.

Maximum parallelism is configurable via the --max-parallel-tools CLI flag (default: 4). Increasing this value can speed up large refactoring tasks but consumes more memory and API tokens.

Output Management

Every tool result passes through a series of post-processors before being added to the conversation context:

Stage	Limits	Purpose
OutputTruncator	2,000 lines / 50 KB cap	Prevents oversized results from flooding the context window. The full output is saved to a temporary file on disk and a summary is injected in place.
ToolResultDeduplicator	—	Removes results that have been superseded by a later call to the same tool with the same parameters (e.g. re-reading a file after editing it).
ContextPruner	Configurable budget	Replaces old, low-value tool results with short placeholders to free up context window space for new information.

Tip: For a deep dive into how context is managed, see the Context and Sessions & Memory docs. They cover pruning strategy, memory persistence, and how to tune the context budget for your workflow.

File Change Detection

The file_read tool maintains a lightweight cache of previously read files. On subsequent reads:

• If the file has not been modified since the last read, the tool returns [Unchanged since last file_read of path (lines X-Y); content omitted to save tokens] instead of re-sending the full content — saving context window tokens and reducing latency.
• If the file has been modified (by file_edit, file_write, or an external process), the full updated content is returned.
• Large files exceeding 10 MB are streamed line-by-line to avoid memory spikes and to respect the OutputTruncator limits.

This caching behaviour is automatic and transparent to the LLM. The agent always sees the correct file state, but avoids wasting context on redundant re-reads.

Tip: If you need to force a fresh read (for example, after an external build tool modifies a generated file), the agent can use file_read with offset=1 to bypass the cache.