Skip to content

tools.md

Latest commit

 

History

History
403 lines (255 loc) · 14.4 KB

tools.md

File metadata and controls

403 lines (255 loc) · 14.4 KB
Raw

Tools

nca's agent has access to a set of built-in tools for interacting with your codebase, running commands, and searching the web. Tools are the actions the agent can take on your behalf.

Tool Categories

Read-Only Tools

These tools are always available, including in safe mode.

Tool Description
read_file Read the contents of a file
search_code Search code using ripgrep with structured JSON output
list_directory List files and directories at a path
git_status Show git status for the workspace
git_diff Show git diff (staged or unstaged)
web_search Search the web via DuckDuckGo
fetch_url Fetch and extract text content from a URL

Write Tools

Available in standard mode. Requires appropriate permissions.

Tool Description
write_file Create or overwrite a file
create_directory Create a directory (including parents)
apply_patch Apply one or more exact string replacements to a file
edit_file Replace a specific string in an existing file
replace_match Precision replace using line and column coordinates
rename_path Rename a file or directory
move_path Move a file or directory
copy_path Copy a file
delete_path Delete a file or directory

Execution Tools

Tool Description
execute_bash Execute a shell command in the workspace (PTY-backed)
run_validation Run an allowlisted build/test/lint command

Intelligence Tools

Tool Description
query_symbols Search for symbol definitions in the codebase
ask_question Ask the user a structured question with options
invoke_skill Load and follow a skill's instructions
spawn_subagent Spawn a child agent session for parallel work

MCP Tools

Tools from configured MCP servers appear as mcp__<server>__<tool>.

Tool Reference

read_file

Read the contents of a file in the workspace.

Parameters:

  • path (string, required) — File path relative to workspace root
  • start_line (integer, optional) — First line to return, 1-based (default 1)
  • end_line (integer, optional) — Last line to return, inclusive (default: up to 2000 lines from start_line)

Behavior: Reads the file asynchronously. The path must resolve within the workspace boundary. A file longer than the returned window starts with a header such as [showing lines 1-2000 of 5000. Pass start_line to continue.]. Each read records the file so later edits can check it (see below).

search_code

Search code using ripgrep and return structured match results.

Parameters:

  • pattern (string, required) — Search pattern (regex by default)
  • path (string, optional) — Directory to search in (default: workspace root)
  • glob (string, optional) — File glob filter (e.g., "*.rs")
  • fixed_strings (bool, optional) — Treat pattern as literal text
  • case_sensitive (bool, optional) — Case-sensitive matching
  • word (bool, optional) — Match whole words only
  • context_before (int, optional) — Lines of context before match
  • context_after (int, optional) — Lines of context after match
  • max_results (int, optional) — Maximum number of results

Behavior: Invokes rg with JSON output. Search root is validated to stay within the workspace.

list_directory

List files and directories at a given path.

Parameters:

  • path (string, optional) — Directory path (default: ., workspace root)

Behavior: Lists entries under the given path. Directories are suffixed with /.

git_status

Show the current git status for the workspace.

Parameters: None (empty object {})

Behavior: Runs git status --short --branch in the workspace.

git_diff

Show git diff for the workspace.

Parameters:

  • staged (bool, optional) — If true, show staged changes (--cached)

web_search

Search the public web and return titles, URLs, and snippets.

Parameters:

  • query (string, required) — Search query
  • limit (int, optional) — Number of results (1–10, default from config)

Behavior: HTTP GET to DuckDuckGo HTML search. Results are parsed and returned as structured text.

fetch_url

Fetch and normalize the text content of a URL.

Parameters:

  • url (string, required) — The URL to fetch

Behavior: Makes an HTTP GET request, strips HTML to text content, and truncates to max_fetch_chars (default 25,000 characters).

write_file

Create or overwrite a file inside the workspace.

Parameters:

  • path (string, required) — File path relative to workspace
  • content (string, required) — File contents

Read before overwrite: writing an existing file requires a read_file of it earlier in the session, and the file must be unchanged since that read. New files need no read.

Behavior: Creates parent directories if needed. Path must resolve within workspace.

create_directory

Create a directory inside the workspace.

Parameters:

  • path (string, required) — Directory path

Behavior: Creates the directory and all parent directories (mkdir -p equivalent).

apply_patch

Apply one or more exact string replacements to a file.

Parameters:

  • path (string, required) — File to patch
  • edits (array, required) — List of edits, each containing:
    • old_text (string, required) — Text to find (must not be empty)
    • new_text (string, required) — Replacement text
    • replace_all (bool, optional) — Replace all occurrences (default: false)

Behavior: For each edit, finds the exact old_text string. If replace_all is false and multiple matches exist, the edit fails with an error.

edit_file

Replace a specific string in an existing file.

Parameters:

  • path (string, required) — File to edit
  • old_text (string, required) — Text to find
  • new_text (string, required) — Replacement text
  • replace_all (bool, optional) — Replace all occurrences

Similar to apply_patch but for a single edit.

Read before edit: an existing file must have been read with read_file earlier in the session, and must be unchanged since. Otherwise the edit is rejected with a message that says to read the file first, or to read it again after an outside change.

replace_match

Precision replacement using exact file path, line number, and column.

Parameters:

  • path (string, required) — File path
  • line (int, required) — Line number (1-based)
  • column (int, required) — Column number (1-based)
  • old_text (string, required) — Text to replace at the specified position
  • new_text (string, required) — Replacement text

Behavior: Anchors the replacement at a specific line and column for maximum precision.

rename_path

Rename a file or directory within the workspace.

Parameters:

  • from (string, required) — Current path
  • to (string, required) — New path

move_path

Move a file or directory within the workspace.

Parameters:

  • from (string, required) — Source path
  • to (string, required) — Destination path

copy_path

Copy a file within the workspace.

Parameters:

  • from (string, required) — Source file
  • to (string, required) — Destination file

delete_path

Delete a file or directory.

Parameters:

  • path (string, required) — Path to delete
  • recursive (bool, optional) — Required for directory deletion

Behavior: Always requires explicit approval under most permission modes (classified as destructive).

execute_bash

Execute a shell command in the workspace.

Parameters:

  • command (string, required) — The shell command to run
  • timeout_secs (int, optional, default: 30) — Command timeout in seconds

Behavior: Runs in a PTY (pseudo-terminal) for full interactive command support. Returns stdout content or status message. Exit code 0 = success.

In safe mode, execute_bash is added to the deny list automatically.

app_input (macOS only)

Act on a running macOS app without bringing it to the front. Registered on macOS only. Prototype: see docs/plans/macos-background-input.md.

Parameters:

  • app (string, required) — Name of a running app with a window, e.g. Calculator. If two instances share the name, the first in window order is used
  • action (string, required) — list, press, type_text, or open_url
  • title (string, press only) — Title, description, or identifier of the control, matched without regard to case
  • text (string, type_text only) — Characters to post
  • url (string, open_url only) — An http or https address. It opens with open -g, so the app is not brought to the front
  • limit (int, list only, default: 200) — Most elements to return

Behavior: list prints the app's accessibility elements with their titles and values. press runs AXPress on the first pressable control that matches. type_text posts one key press and release per character to the app's process. The tool cannot confirm the app received them, so the output says "posted". open_url opens the address in the app and rejects anything that is not http or https. Every result ends with a line saying whether the frontmost app changed.

Requirements: Accessibility permission for the terminal or app that runs nca (System Settings > Privacy & Security > Accessibility).

Approval: Asks in Default and AcceptEdits modes. Denied in Plan and DontAsk.

screen_record (macOS only)

Record one macOS app window to a .mov file, or save a still screenshot of it, including while the window is in the background. Registered on macOS only. Prototype: see docs/plans/macos-window-recording.md.

Parameters:

  • action (string, required) — start, stop, or screenshot
  • app (string, start only, required) — Name of a running app with a window, e.g. Dia
  • seconds (int, start only, default: 60, max: 600) — Time limit. The recording ends by itself at the limit
  • id (string, stop only, required) — The id that start returned
  • delay (int, screenshot only, default: 3, max: 30) — Seconds to wait before the still image is taken

Behavior: start records the app's frontmost on-screen window with screencapture and returns an id. stop ends the recording and waits until the file is written. A stop within the first 2 seconds waits until 2 seconds have passed, because an earlier interrupt can end screencapture without a file. Files go to the project's nca data folder, ~/.local/share/ncacli/workspaces/<workspace-id>/recordings/, unless [recording] dir sets another location. Each start result says whether the frontmost app changed. screenshot saves one still image of the app's window after the delay, to the same recordings folder, and reports the same check. Recordings still running when the session ends are finished.

Requirements: Screen Recording permission for the app that runs nca (System Settings > Privacy & Security > Screen & System Audio Recording). A recording shows what the window shows, including account data.

Approval: Asks in Default and AcceptEdits modes. Denied in Plan and DontAsk.

run_validation

Run a safe build, test, or lint command.

Parameters:

  • command (string, required) — The command to run
  • cwd (string, optional, default: .) — Working directory
  • timeout_secs (int, optional, default: 120) — Command timeout

Behavior: Only executes commands that start with an allowlisted prefix:

  • cargo build, cargo test, cargo check, cargo clippy, cargo fmt
  • npm run, npm test, npx
  • pnpm run, pnpm test
  • pytest, python -m pytest
  • go test, go build, go vet
  • make

Other commands are rejected with an error.

query_symbols

Search for symbol definitions (functions, structs, traits, etc.) in the codebase.

Parameters:

  • query (string, required) — Symbol name or pattern to search
  • glob (string, optional) — File filter

Behavior: Uses fast local code intelligence to find symbol definitions. Returns path:line:text formatted results.

ask_question

Ask the user a structured question with predefined options.

Parameters:

  • prompt (string, required) — The question text
  • options (array, required) — List of options with id and label
  • suggested_answer (string, required) — Default/recommended answer
  • allow_custom (bool, optional, default: true) — Allow freeform custom answer

Behavior: Opens a modal in the TUI (or prompts in REPL) and waits for the user's selection. Blocks up to 3600 seconds.

invoke_skill

Load a skill's full instructions by name.

Parameters:

  • skill_name (string, required) — Name of the skill to invoke

Behavior: Discovers the skill's SKILL.md file from configured skill directories and returns its expanded content. If no match, lists available skills.

spawn_subagent

Spawn a child agent session for parallel task delegation.

Parameters:

  • task (string, required) — Clear description of what the sub-agent should do
  • focus_files (string[], optional) — File paths the sub-agent should focus on
  • use_worktree (bool, optional, default: true) — Run in an isolated git worktree

Behavior: Creates a new child session that inherits conversation context. The child runs with bypass-permissions mode and no interactive approvals. Returns a JSON response with child_session_id, status, output, workspace, branch, and worktree_path. Times out after 600 seconds.

See Sub-Agents for details.

Tool Execution Flow

  1. The LLM decides to call a tool and provides parameters
  2. nca checks permissions for the tool
  3. If permission is Ask, the user is prompted for approval
  4. The tool executes asynchronously
  5. Results are fed back to the LLM for the next turn
  6. Multiple approved tools can execute concurrently within a single turn

Workspace Sandbox

All file tools enforce a workspace boundary:

  • File reads, writes, and edits must resolve to paths within the workspace root
  • Shell commands (execute_bash) run with the workspace as the working directory
  • Attempts to access paths outside the workspace are rejected with an error

This sandbox protects against accidental or malicious file access outside your project.