Agent Tools

LeanCTL provides the AI with 23 tools to interact with your codebase. The AI uses them automatically — you don't need to learn any of these.

File Operations

Tool	Permission	Description
`read_file`	Read	Read a file, optionally a specific line range
`write_file`	Write	Create or overwrite a file
`edit_file`	Write	Replace an exact string in a file (search-and-replace)
`multi_edit`	Write	Apply multiple replacements in a single file
`delete_file`	Write	Delete a file
`rename_file`	Write	Rename or move a file

read_file

Reads file content with optional line range. Automatically detects binary files (returns an error instead of corrupted output). File access is sandboxed to the project root.

# Parameters
path: string      # file path (required)
offset: integer   # start line, 1-based (optional)
limit: integer    # number of lines (optional)

When used with the LeanCTX compression engine, reads support smart caching (~13 tokens for re-reads) and delta mode (only changed lines since last read).

write_file

Creates or overwrites a file. After a successful write, LeanCTL automatically runs the appropriate formatter for the file type:

Language	Formatter
Rust	`rustfmt`
Go	`gofmt`
Python	`ruff format`
JS/TS/CSS/HTML/JSON	`prettier`
Zig	`zig fmt`
Nix	`nixfmt`
Dart	`dart format`
Elixir	`mix format`

Auto-formatting has a 15-second timeout and is best-effort — it won't fail the write if the formatter is not installed.

edit_file

The primary editing tool. Finds an exact string match and replaces it. This ensures precise, predictable edits.

# Parameters
path: string       # file path (required)
old_string: string # exact text to find (required)
new_string: string # replacement text (required)

multi_edit

Applies multiple search-and-replace operations to a single file in one call. More efficient than multiple edit_file calls.

# Parameters
path: string     # file path (required)
edits: array     # array of (old_string, new_string) pairs (required)

Search & Navigation

Tool	Permission	Description
`search_code`	Read	Regex pattern search across project files
`list_files`	Read	List directory contents with configurable depth
`semantic_search`	Read	Search code by meaning using vector embeddings
`related_files`	Read	Find related files via dependency graph analysis

search_code

Searches your codebase for regex patterns. Returns matching lines with file paths and line numbers.

# Parameters
pattern: string  # regex pattern (required)
path: string     # directory to search (optional, default: project root)

semantic_search

Finds code by meaning, not exact text. Uses BM25 embeddings to locate semantically related code even without keyword matches.

# Parameters
query: string    # natural language query (required)
path: string     # directory to search (optional)
top_k: integer   # number of results (optional, default: 10)

related_files

Analyzes import graphs and symbol references to find files related to a given file. Useful for understanding change impact.

# Parameters
path: string     # file to analyze (required)
action: string   # "related" | "impact" | "symbol" (optional)

Execution

Tool	Permission	Description
`run_command`	Execute	Run a shell command in the project directory
`task`	Read	Spawn a read-only sub-agent for research tasks

run_command

Executes shell commands in your project directory via sh -c. Output is captured, compressed (90+ CLI patterns recognized), and displayed in the TUI.

# Parameters
command: string  # shell command to execute (required)

Limit	Value
Timeout	120 seconds
Max stdout/stderr	512 KB each

Output is automatically compressed using LeanCTX's 90+ pattern library (git, cargo, npm, docker, kubectl, pytest, etc.). Unrecognized commands get entropy-based compression if savings exceed 15%.

task

Spawns a read-only sub-agent for research tasks. The sub-agent can read files, search code, and list directories, but cannot make changes or run commands.

# Parameters
prompt: string  # the research question or task (required)

Limit	Value
Max iterations	10 tool loops
Available tools	Read-only tools only (no write, execute, or task)

Git Operations

Tool	Permission	Description
`git_status`	Read	Show changed, staged, and untracked files
`git_diff`	Read	Show diff of changes (staged or unstaged)
`git_commit`	Execute	Stage files and create a commit

Git Tool Details

git_diff

# Parameters
staged: boolean  # show staged changes instead of unstaged (optional, default: false)
path: string     # limit diff to a specific file (optional)

Output is truncated to 300 lines for large diffs.

git_commit

# Parameters
message: string  # commit message (required)
paths: string[]  # specific files to stage (optional — omit to stage all changed files via git add -u)

Web Tools

Tool	Permission	Description
`web_search`	Execute	Search the web via DuckDuckGo and return snippets
`web_fetch`	Execute	Fetch a URL and return its text content (max 2 MB, 300 lines)

web_search uses DuckDuckGo for privacy-respecting search results. web_fetch retrieves any URL, strips HTML tags, and returns plain text — limited to 2 MB download size and 300 lines of output.

Context & Intelligence

Tool	Permission	Description
`batch_read`	Read	Read multiple files in a single call with cross-file deduplication
`context_fill`	Read	Fill context window with files up to a token budget
`project_knowledge`	Read	Persistent knowledge store — remember facts across sessions
`question`	Read	Ask the user a question and wait for a response
`savings_stats`	Read	Show token savings statistics for the current session
`savings_report`	Read	Generate a savings report for a given period

batch_read

Reads multiple files in a single tool call. More efficient than individual read_file calls because it uses cross-file deduplication to eliminate redundant content.

# Parameters
paths: string[]  # file paths to read (required)
mode: string     # "full" | "map" | "signatures" | "aggressive" | "entropy" (optional)

context_fill

Loads files into the context window up to a specified token budget. Prioritizes by relevance and applies compression as needed.

# Parameters
paths: string[]  # file paths to include (required)
budget: integer  # maximum tokens (required)

project_knowledge

A persistent knowledge store that survives across sessions. The AI can remember architecture decisions, patterns, and conventions. Supports contradiction detection and temporal tracking.

# Actions
remember     — store a fact (with optional confidence score)
recall       — search facts by query
pattern      — store a recurring pattern (naming, architecture, etc.)
status       — show knowledge summary
remove       — delete a fact by key
timeline     — view change history
rooms        — list fact categories
search       — cross-session search
wakeup       — get a project briefing at session start
export       — export all knowledge
consolidate  — merge and deduplicate facts

# Key parameters
action: string        # required — one of the above
category: string      # fact category (e.g. "architecture", "conventions")
key: string           # fact identifier (for remember/remove)
value: string         # fact content or pattern description
query: string         # search term (for recall/search)
confidence: number    # 0.0–1.0 confidence score (for remember)

Permission Levels

Each tool has a permission level that determines whether it requires user confirmation:

Level	Label	Confirmation	Tools
Read	`read`	Never	read_file, search_code, list_files, git_status, etc.
Write	`write`	When `confirm_edits = true`	write_file, edit_file, delete_file, rename_file
Execute	`exec`	When `confirm_commands = true`	run_command, git_commit, web_search

Disable confirmations with leanctl --yolo, the /yolo command, or per-tool in .leanctl/permissions.toml.

Safety & Limits

Path sandboxing: All file operations are restricted to the canonical project root. Path traversal (../) outside the project is blocked.
Binary detection: read_file detects binary files and returns an error instead of corrupted output.
Command timeout: run_command has a 120-second timeout. Output is capped at 512 KB per stream.
Loop protection: LeanCTL detects when the AI calls the same tool with identical arguments repeatedly. After 25 iterations in a turn, the loop is terminated.
Auto-dedup: Every 15 tool loops, cross-file deduplication runs automatically to remove redundant context.
Search limits: search_code returns max 100 matches. semantic_search defaults to 10 results.

Tool Output Compression

LeanCTL automatically compresses tool output based on the cost of your provider:

Level	When	Behavior
Minimal	Free/local providers (Ollama)	Light compression — larger file excerpts, more search results
Standard	Mid-tier providers (Groq, DeepSeek)	Balanced compression
Aggressive	Premium providers (Anthropic, OpenAI)	Maximum compression — API signatures only, minimal search results

This means free local models get more raw context, while expensive cloud models get maximally compressed output to save costs.