Tools

Luna provides 45 built-in tools, 14 computer use tools, and dynamic MCP tool discovery. The LLM agent autonomously selects and executes tools based on the task. Permission modes and per-mode rulesets control which tools are available.

Tool Prefix Conventions

Prefix	Source	Example
builtin__	Built into Luna	builtin__bash, builtin__read_file
custom__	Discovered from workspace	custom__my_tool
mcp__	MCP server	mcp__github_create_issue

File Operations

bash

Execute shell commands in the workspace directory.

Parameter	Type	Required	Description
command	string	Yes	Shell command to execute
timeout	number	No	Timeout in milliseconds (default: 120000)

Output limited to 16KB. Exit code included in result. Commands use fork/exec with pipe capture.

read_file

Read file contents with optional line range. Detects image files and returns base64-encoded content blocks for vision-capable models.

Parameter	Type	Required	Description
path	string	Yes	Absolute file path
offset	number	No	Starting line number (1-based)
limit	number	No	Maximum lines to read

write_file

Create or overwrite a file atomically.

Parameter	Type	Required	Description
path	string	Yes	File path
content	string	Yes	File content

Max size: 10MB. Uses atomic write (write to .tmp, then rename). Queued through mutation queue.

edit_file

Search and replace in an existing file. Fails if old_text is not found or matches multiple locations.

Parameter	Type	Required	Description
path	string	Yes	File path
old_text	string	Yes	Exact text to find
new_text	string	Yes	Replacement text

fuzzy_edit

Fuzzy search and replace, tolerant of whitespace differences. Uses multi-strategy matching: exact, strip-whitespace, normalize-indent, fuzzy-line.

Parameter	Type	Required	Description
path	string	Yes	File path
old_text	string	Yes	Text to find (fuzzy matched)
new_text	string	Yes	Replacement text

multi_edit

Edit multiple files atomically. If any edit fails, all changes roll back.

Parameter	Type	Required	Description
edits	array	Yes	Array of {file_path, old_string, new_string} objects

list_directory

List directory contents. Returns file names, types, and sizes.

Parameter	Type	Required	Description
path	string	Yes	Directory path

create_directory

Create a directory recursively (like mkdir -p).

Parameter	Type	Required	Description
path	string	Yes	Directory path

delete_file

Delete a file or empty directory. Non-empty directories are not deleted.

Parameter	Type	Required	Description
path	string	Yes	Path to delete

notebook

Read and edit Jupyter notebook cells (.ipynb files).

Parameter	Type	Required	Description
command	string	Yes	list_cells, read_cell, edit_cell, add_cell
file_path	string	Yes	Path to .ipynb
cell_index	number	No	Cell index (0-based)
content	string	No	Cell content
cell_type	string	No	code or markdown

Search

glob_search

Find files matching a glob pattern. Max 100 results, sorted by modification time.

Parameter	Type	Required	Description
pattern	string	Yes	Glob pattern (supports ** recursive)
path	string	No	Base directory

grep_search

Search file contents with regex. Max 50 results.

Parameter	Type	Required	Description
pattern	string	Yes	Regular expression pattern
path	string	No	Base directory

code_search

Search code using language-server analysis or text search fallback.

Parameter	Type	Required	Description
query	string	Yes	Symbol name or text pattern
search_type	string	Yes	definition, references, symbols, text
file_path	string	No	Limit to this file
language	string	No	Limit to this language

Code Intelligence

lsp

Query a language server. Supports 7+ language servers.

Parameter	Type	Required	Description
operation	string	Yes	goToDefinition, findReferences, hover, documentSymbol, diagnostics
path	string	Yes	File path
line	number	Yes	Line number (1-based)
character	number	Yes	Column number (1-based)

Git

git

Execute structured git operations. Dangerous operations (force push, hard reset, rebase) are blocked.

Parameter	Type	Required	Description
command	string	Yes	status, diff, log, branch, show, add, commit, stash, checkout
args	string	No	Optional arguments
path	string	No	Optional file path

git_snapshot

Manage git snapshots for undo and review. Auto-created after mutating tools.

Parameter	Type	Required	Description
command	string	Yes	list, diff, restore
snapshot_id	string	No	Snapshot commit hash
files	array	No	File paths to restore
count	number	No	Number to list (default: 10)

Web

web_fetch

Fetch content from a URL. Output limited to 1MB. Uses libcurl via FFI.

Parameter	Type	Required	Description
url	string	Yes	URL to fetch
format	string	No	text (default) or markdown

web_search

Search the web via SearXNG or Brave Search API.

Parameter	Type	Required	Description
query	string	Yes	Search query
max_results	number	No	Maximum results (default: 10)

http_request

Make HTTP requests (GET, POST, PUT, PATCH, DELETE, HEAD).

Parameter	Type	Required	Description
url	string	Yes	Request URL
method	string	Yes	HTTP method
headers	object	No	Request headers
body	string	No	Request body
timeout	number	No	Timeout in milliseconds
stream	boolean	No	Stream response
max_stream_bytes	number	No	Max bytes when streaming (default: 100KB)

MCP Tools

mcp_read_resource

Read a resource from an MCP server. If no server specified, tries all connected servers.

Parameter	Type	Required	Description
uri	string	Yes	MCP resource URI
server	string	No	Specific MCP server name

mcp_get_prompt

Get a prompt template from an MCP server.

Parameter	Type	Required	Description
name	string	Yes	Prompt template name
arguments	object	No	Template arguments
server	string	No	Specific MCP server name

Session Tools

todo

Manage a session-scoped task checklist.

Parameter	Type	Required	Description
action	string	Yes	list, add, update, remove
id	string	No	Task ID
text	string	No	Task description
status	string	No	pending, in_progress, completed
priority	string	No	high, medium, low

undo_edit

Undo the last file edit(s). Maintains a stack of up to 50 entries.

Parameter	Type	Required	Description
count	number	No	Number of edits to undo (default: 1)

task

Spawn a sub-agent with its own context. 60-second timeout, up to 20 steps.

Parameter	Type	Required	Description
prompt	string	Yes	Task description
tools	array	No	Restrict to these tools
backend	string	No	local, zmq, luerl

switch_mode

Switch the agent to a different operating mode.

Parameter	Type	Required	Description
mode	string	Yes	Mode name
reason	string	Yes	Why the switch is needed

tool_search

Search and retrieve full tool schemas by name or description.

Parameter	Type	Required	Description
query	string	Yes	Partial tool name or keyword

Team Tools

team_spawn

Spawn a teammate agent for collaborative work. Requires ZMQ connection to Sol.

Parameter	Type	Required	Description
team_id	string	Yes	Team ID
mode	string	No	Agent mode (default: build)
prompt	string	No	Initial task assignment

team_mail

Send a message to team members via priority mailbox.

Parameter	Type	Required	Description
team_id	string	Yes	Team ID
body	string	Yes	Message body
to	string	No	Recipient ID or all
subject	string	No	Message subject
priority	string	No	high, normal, low

Utility Tools

calculator

Evaluate mathematical expressions safely. No code execution.

Parameter	Type	Required	Description
expression	string	Yes	Math expression

diagram

Generate Mermaid diagrams from descriptions.

Parameter	Type	Required	Description
description	string	Yes	What the diagram should show
diagram_type	string	No	flowchart, sequence, class, state, er, gantt
code	string	No	Direct Mermaid code

file_watcher

Watch a file or directory for changes. Uses inotify when available.

Parameter	Type	Required	Description
path	string	Yes	File or directory path
timeout	number	No	Seconds to watch (default: 10, max: 60)

attach_image

Attach an image for multimodal analysis. Max 20MB.

Parameter	Type	Required	Description
path	string	Yes	Absolute path to image

Computer Use Tools

14 desktop automation tools registered when a display server (X11 or Wayland) is detected:

Tool	Description	Permission
screenshot	Capture screenshot	execute
mouse_move	Move cursor to coordinates	execute
mouse_click	Click mouse button	execute
mouse_drag	Drag from start to end	execute
type_text	Type text at cursor	execute
press_key	Press key combination	execute
scroll	Scroll up or down	execute
get_cursor	Get cursor position	read
display_info	Screen resolution and display info	read
window_list	List all visible windows	read
clipboard_read	Read clipboard contents	read
clipboard_write	Write text to clipboard	write
window_manage	bspwm window management	execute
desktop_notify	Send desktop notification	execute

All computer use tools gracefully degrade in headless environments.

Tool Discovery

Luna scans the workspace for custom tool definitions:

• Workspace scanning from .luna/tools/ and ~/.luna/tools/
• Hot-reload with /tools-reload slash command
• Listing with /tools-list slash command
• Namespacing with custom__ prefix for discovered tools

Tool Selection Patterns

Task	Tools
Explore codebase	glob_search, grep_search, read_file
Fix a bug	read_file, bash, edit_file, undo_edit
Create a new file	write_file
Refactor code	glob_search, read_file, edit_file, multi_edit
Run tests	bash
Research online	web_search, web_fetch
Code navigation	lsp
Track multi-step work	todo
Delegate subtask	task
Team collaboration	team_spawn, team_mail