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.

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.

Example: Read lines 50–80 of a controller:

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

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.

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)").

Example: Rename a method call:

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

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.

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.

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.

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

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

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.

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.

shell_write

Send input to a running shell session.

shell_read

Read buffered output from a running shell session.

shell_kill

Terminate a running shell session.

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.

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.

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.

Example: Recall a previous decision about caching:

memory_search query="caching strategy"

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.

* 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.

Example:

task_update id="task_001" status="completed"

task_get

Retrieve full details of a single task.

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.

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.

execute_lua

Execute Lua code with app.* namespace access. Use app.integrations.* for API calls, 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.

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)"

lua_list_docs

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

Example: List all available namespaces:

lua_list_docs

Example: Show functions in a specific integration:

lua_list_docs namespace="integrations.plausible"

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.

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") → full API reference with all functions and parameters
• Function (e.g. "integrations.plausible.query_stats") → 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.

Example:

lua_read_doc page="integrations.plausible.query_stats"

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.

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).

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.

Concurrent Execution

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

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:

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.