Tools — Nyzhi Docs

Nyzhi ships with over 50 built-in tools, organized into categories. Each tool has a permission level that determines whether it can run automatically or needs your approval.

Permission Levels

Level	Behavior
Read-only	Runs automatically, can execute in parallel
Needs approval	Requires confirmation (based on your trust mode)

Read-only tools never modify your files or system. Approval-required tools always run sequentially — never in parallel.

File and Code Tools

These are the core tools for reading, writing, and searching your codebase.

Tool	Permission	What it does
`read`	Read-only	Read file contents (with optional line ranges)
`write`	Approval	Create or overwrite a file
`edit`	Approval	Replace a specific string in a file
`multi_edit`	Approval	Transactional string replacements across multiple files
`apply_patch`	Approval	Apply a unified diff atomically
`batch_apply`	Approval	Run an operation across many files
`glob`	Read-only	Find files by glob pattern
`grep`	Read-only	Search file contents with regex
`fuzzy_find`	Read-only	Fuzzy filename search
`tail_file`	Read-only	Read the last N lines of a file
`bash`	Approval	Execute shell commands

Example: The Agent Edits a File

When you ask Nyzhi to fix a bug, it typically:

Uses grep or glob to find the relevant file
Uses read to examine the code
Uses edit to make the change
Uses bash to run tests

Git Tools

Full Git integration without leaving Nyzhi:

Tool	Permission	What it does
`git_status`	Read-only	Show working tree status
`git_diff`	Read-only	Show staged/unstaged changes
`git_log`	Read-only	View commit history
`git_show`	Read-only	Inspect a specific commit
`git_branch`	Read-only	List branches
`git_commit`	Approval	Stage and commit changes
`git_checkout`	Approval	Switch or create branches

Filesystem Tools

Lower-level file operations:

Tool	Permission	What it does
`list_dir`	Read-only	List directory entries
`directory_tree`	Read-only	Recursive tree view
`file_info`	Read-only	File metadata (size, modified, permissions)
`delete_file`	Approval	Delete a file or empty directory
`move_file`	Approval	Move or rename a path
`copy_file`	Approval	Copy a file
`create_dir`	Approval	Create a directory

Code Intelligence

Tools that understand code structure, not just text:

Tool	Permission	What it does
`verify`	Read-only	Run verification checks (tests, lint, typecheck)
`lsp_diagnostics`	Read-only	LSP diagnostics and capabilities
`ast_search`	Read-only	Search using structural patterns
`lsp_goto_definition`	Read-only	Jump to symbol definition
`lsp_find_references`	Read-only	Find all references to a symbol
`lsp_hover`	Read-only	Get type info and docs at a position
`semantic_search`	Read-only	Embedding-based code retrieval (requires index)

Planning and Interaction

Tools the agent uses to organize work and communicate with you:

Tool	Permission	What it does
`todowrite`	Read-only	Create or update a structured todo list
`todoread`	Read-only	Read the current todo list
`create_plan`	Read-only	Create or update a session plan
`think`	Read-only	Side-effect-free reasoning (scratchpad)
`ask_user`	Read-only	Ask a structured multiple-choice question
`tool_search`	Read-only	Discover deferred or MCP tools

Memory and Knowledge

Persistent context across sessions:

Tool	Permission	What it does
`memory_read`	Read-only	Read user or project memory
`memory_write`	Approval	Save knowledge for future sessions
`notepad_read`	Read-only	Read the session notepad
`notepad_write`	Read-only	Record a learning, decision, or issue
`load_skill`	Read-only	Load a named skill file

Web and Browser

Internet access and browser automation:

Tool	Permission	What it does
`web_fetch`	Approval	Fetch a URL and extract text content
`web_search`	Approval	Search the web and return snippets
`browser_open`	Approval	Open a URL in a headless browser
`browser_screenshot`	Approval	Capture a screenshot
`browser_evaluate`	Approval	Run JavaScript in the page context
`create_pr`	Approval	Create a pull request (GitHub/GitLab)
`review_pr`	Read-only	Retrieve and review a PR diff

Team and Task Tools

Multi-agent collaboration (see Teams):

Tool	Permission	What it does
`team_create`	Approval	Create a team with config, inboxes, and task board
`team_delete`	Approval	Delete all team artifacts
`team_list`	Read-only	List all teams
`send_team_message`	Read-only	Message a teammate or broadcast
`read_inbox`	Read-only	Read unread messages
`task_create`	Read-only	Create a shared task
`task_update`	Read-only	Update task status or owner
`task_list`	Read-only	List all team tasks
`spawn_teammate`	Approval	Spawn an agent and register as team member

Subagent Lifecycle

Available in the interactive TUI only:

Tool	Permission	What it does
`spawn_agent`	Read-only	Spawn a child agent with a specific role
`send_input`	Read-only	Send follow-up instructions to a running agent
`wait`	Read-only	Block until agents reach a terminal status
`close_agent`	Read-only	Shut down an agent and free its slot
`resume_agent`	Read-only	Reopen a completed agent for more work

Note: Subagent tools are only registered in the TUI runtime (nyz). They are not available in nyz run or nyz exec.

Deferred Tools and MCP

When you connect many MCP servers, the tool count can grow large. Nyzhi handles this with deferred loading:

When there are more than 15 MCP tools, they’re registered as deferred
The agent uses tool_search to discover them on demand
A deferred index is saved to .nyzhi/context/tools/mcp-index.md

This keeps the initial tool list compact and reduces token usage.

Tool Context

Every tool execution receives a runtime context with:

session_id — current session
cwd — working directory
project_root — detected project root
depth — 0 for main agent, incremented for subagents
allowed_tool_names — role-based tool filtering
sandbox_level — file system access restrictions
team_name, agent_name, is_team_lead — team metadata

This context enables features like role-scoped behavior, sandbox enforcement, and team messaging.

Next Steps

MCP — connect external tool servers
Configuration — trust modes and tool approval settings
Teams — multi-agent collaboration