Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Effectful-Tech/clanka/llms.txt

Use this file to discover all available pages before exploring further.

The AgentTools module provides the core set of tools available to Clanka agents. It exports context services that agents depend on, a Toolkit containing all built-in tools, and Layer implementations that wire up real or mock handler backends.

​
Context services

These three services are required by specific tools and must be provided in the agent’s Context before the toolkit is executed.

​
CurrentDirectory

export class CurrentDirectory extends Context.Service<
  CurrentDirectory,
  string
>()("clanka/AgentTools/CurrentDirectory") {}
Holds the agent’s current working directory as a string. Tools such as readFile, bash, ls, and glob resolve relative paths against this value.

​
TaskCompleter

export class TaskCompleter extends Context.Service<
  TaskCompleter,
  (output: string) => Effect.Effect<void>
>()("clanka/AgentTools/TaskCompleter") {}
A callback invoked by the taskComplete tool when the agent signals that its task is finished.

​
SubagentExecutor

export class SubagentExecutor extends Context.Service<
  SubagentExecutor,
  (prompt: string) => Effect.Effect<string>
>()("clanka/AgentTools/SubagentExecutor") {}
A callback used by the delegate tool to spawn a sub-agent and return its result.

​
makeContextNoop

export const makeContextNoop: (cwd?: string) => Context.Context<
  CurrentDirectory | TaskCompleter | SubagentExecutor
>
Creates a minimal Context with no-op implementations of all three services. The TaskCompleter is a no-op (Effect.void), and SubagentExecutor calls Effect.die. Useful in unit tests where agent context side-effects should not run.
​
cwd
string
Optional working directory to inject as CurrentDirectory. Defaults to "/".

​
Toolkits

​
AgentTools

export const AgentTools: Toolkit.Toolkit<{
  readFile: Tool.Tool<...>
  rg: Tool.Tool<...>
  delegate: Tool.Tool<...>
  glob: Tool.Tool<...>
  gh: Tool.Tool<...>
  listTodos: Tool.Tool<...>
  addTodo: Tool.Tool<...>
  updateTodo: Tool.Tool<...>
  clearTodos: Tool.Tool<...>
  bash: Tool.Tool<...>
  applyPatch: Tool.Tool<...>
  writeFile: Tool.Tool<...>
  removeFile: Tool.Tool<...>
  renameFile: Tool.Tool<...>
  ls: Tool.Tool<...>
  webSearch: Tool.Tool<...>
  fetchMarkdown: Tool.Tool<...>
  sleep: Tool.Tool<...>
  taskComplete: Tool.Tool<...>
}>
The base toolkit containing all built-in agent tools except search. Use this when the SemanticSearch layer is not available.

​
AgentToolsWithSearch

export const AgentToolsWithSearch: Toolkit.Toolkit<
  typeof AgentTools.tools & { search: Tool.Tool<...> }
>
AgentTools merged with the search tool. The search tool requires the SemanticSearch service in context. Use this toolkit when you have a SemanticSearch layer wired up.
AgentToolsWithSearch is produced by Toolkit.merge(SearchTool, AgentTools). The search tool is only usable when a SemanticSearch layer is provided.

​
Layers

​
AgentToolHandlers

export const AgentToolHandlers: Layer.Layer<
  Tool.HandlersFor<typeof AgentToolsWithSearch.tools>,
  never,
  | FileSystem.FileSystem
  | Path.Path
  | ChildProcessSpawner.ChildProcessSpawner
  | HttpClient.HttpClient
>
The production Layer that provides handler implementations for all tools in AgentToolsWithSearch. It includes real ExaSearch and WebToMarkdown service implementations backed by external HTTP calls. Requirements: FileSystem, Path, ChildProcessSpawner, HttpClient.

​
AgentToolHandlersTest

export const AgentToolHandlersTest: Layer.Layer<
  Tool.HandlersFor<typeof AgentToolsWithSearch.tools>,
  never,
  | FileSystem.FileSystem
  | Path.Path
  | ChildProcessSpawner.ChildProcessSpawner
>
A test-only Layer identical to AgentToolHandlers but with ExaSearch and WebToMarkdown replaced by empty mock implementations. No HTTP client is required.
Use AgentToolHandlersTest together with makeContextNoop in unit tests to exercise tool handler logic without network calls or real sub-agent execution.

​
Tools

Each tool is registered in AgentTools (or AgentToolsWithSearch) via Tool.make. The sections below document each tool’s parameter schema and return type.

​
readFile

Read a file and return its content. Returns null if the file does not exist.
​
path
string
required
Path to the file. Resolved relative to CurrentDirectory.
​
startLine
number
1-based line number to start reading from. Lines before this are skipped.
​
endLine
number
1-based line number to stop reading at (inclusive).
Returns: string | null

​
writeFile

Write content to a file. Parent directories are created automatically. Prefer applyPatch when updating existing files.
​
path
string
required
Destination path, resolved relative to CurrentDirectory.
​
content
string
required
Full text content to write.
Returns: void. If SemanticSearch is available, the written file is re-indexed automatically.

​
removeFile

Remove a file from the filesystem.
​
path
string
required
Path of the file to remove, resolved relative to CurrentDirectory.
Returns: void. Removal is also forwarded to SemanticSearch when available.

​
renameFile

Rename or move a file. Parent directories for the destination are created automatically.
​
from
string
required
Source path, resolved relative to CurrentDirectory.
​
to
string
required
Destination path, resolved relative to CurrentDirectory.
Returns: void.

​
ls

List the entries in a directory.
​
directory
string
required
Directory path, resolved relative to CurrentDirectory.
Returns: string[] — a list of entry names.

​
glob

Find files whose paths match a glob pattern.
​
pattern
string
required
A glob expression (e.g. "src/**/*.ts"). Matched against paths under CurrentDirectory.
Returns: string[] — matching paths relative to CurrentDirectory.

​
rg

Search for a regex pattern in files using ripgrep.
​
pattern
string
required
The regex or literal pattern to search for.
​
glob
string
--glob filter passed to ripgrep (e.g. "*.ts").
​
filesOnly
boolean
When true, uses --files-with-matches to return only matching file paths instead of matching lines.
​
maxLines
number
Maximum number of output lines to return across all files. Defaults to 500.
Returns: string — ripgrep output, with headings and line numbers.

​
bash

Run a bash command and return combined stdout and stderr output.
​
command
string
required
The shell command to run.
​
timeoutMs
number
Timeout in milliseconds. Defaults to 120000 (2 minutes). Maximum is 240000 (4 minutes).
Returns: string — the command output.
The command runs with stdin set to "ignore". Interactive commands will not work.

​
gh

Run the GitHub CLI (gh) with the given arguments. Prefer this over bash for GitHub operations.
​
args
string[]
required
Arguments to pass to the gh binary (e.g. ["pr", "list", "--state", "open"]).
Returns: string — the command output.

​
applyPatch

Apply a git-style unified diff to add, update, or delete one or more files in a single operation.
​
patch
string
required
A git diff / unified diff / wrapped patch string.
Returns: string — a summary listing each affected file with its change type (A, M, or D).

​
webSearch

Search the web for recent information using the Exa search API.
​
query
string
required
The search query string.
​
numResults
number
Number of search results to retrieve. Defaults to 3.
Returns: string — the text content of the top result.

​
fetchMarkdown

Fetch a web page and return its content converted to Markdown.
​
url
string
required
The URL to fetch.
Returns: string — the page content as Markdown.

​
delegate

Delegate a task to a sub-agent via SubagentExecutor. The sub-agent receives the task description as a prompt and its result is returned.
​
task
string
required
A description of the task to perform.
Returns: string — the sub-agent’s output.

​
taskComplete

Signal that the current task is complete and deliver the final output message. Only call this when all work is finished.
​
output
string
required
The final output message to send.
Returns: void. Invokes the TaskCompleter callback.

​
listTodos

Read the agent’s current todo list. Parameters: none. Returns: TodoItem[] 
interface TodoItem {
  id: number
  text: string
  completed: boolean
}

​
addTodo

Add a new item to the todo list.
​
text
string
required
The text of the todo item.
Returns: void.

​
updateTodo

Update an existing todo item by its numeric ID.
​
id
number
required
The ID of the todo item to update.
​
text
string
New text for the todo item.
​
completed
boolean
New completion status.
Returns: void. Calls Effect.die if no item with the given ID exists.

​
clearTodos

Remove all items from the todo list. Parameters: none. Returns: void.

​
sleep

Pause execution for a given duration.
​
ms
number
required
Number of milliseconds to sleep.
Returns: void.
Perform a semantic code search against the indexed codebase. Only available in AgentToolsWithSearch when a SemanticSearch layer is provided.
​
query
string
required
A natural-language description of what you are looking for (e.g. "function that validates email addresses").
Returns: string — the top-5 matching code chunks, joined with double newlines.

Build docs developers (and LLMs) love

Get started for freeTalk to us