Reference for all 10 default tools included with supyagent, providing shell access, file operations, code search, Git integration, and more.

Built-in Tools

When you run supyagent init, 10 default tools are copied into your powers/ directory. These cover the most common operations an agent needs to interact with a development environment.

Tool Summary

Tool	Script	Functions	Description
Shell	`shell.py`	4	Run commands, execute scripts, find executables, read environment
Files	`files.py`	9	Read, write, copy, move, delete files and directories
Edit	`edit.py`	5	Search-and-replace, line insertions, multi-edit, regex replace
Search	`search.py`	2	Pattern search across files with context lines and match counts
Find	`find.py`	3	Find files by glob pattern, modification time, or directory tree
Patch	`patch.py`	1	Apply multi-file patches with V4A context-anchored diffs
Git	`git.py`	5	Status, diff, commit, log, branch management
Plan	`plan.py`	3	Create, update, and track multi-step plans
Web	`web.py`	2	Fetch URLs as markdown, make HTTP API requests
Browser	`browser.py`	6	Headless Chromium browsing, screenshots, clicks, form filling

Total Function Count

Across all 10 default tools, agents have access to 40 functions out of the box.

Dependencies

All default tools declare only pydantic as a dependency, except:

Tool	Extra Dependencies
`web.py`	`httpx`, `markdownify`, `beautifulsoup4`
`browser.py`	`playwright`, `markdownify`, `beautifulsoup4`

The browser tool also requires Playwright's Chromium browser to be installed:

playwright install chromium

Customizing Default Tools

Default tools are regular supypowers scripts. You can:

Edit them to change behavior (e.g., adjust max_output in shell, change _SKIP_DIRS in search)
Remove them if you don't need them (delete the .py file)
Replace them with your own implementations

Restricting Tools Per Agent

Use the agent config to control which tools an agent can access:

agents/restricted.yaml

tools:
  allow:
    - "files:read_file"
    - "files:list_directory"
    - "search:*"
    - "find:*"
  deny:
    - "shell:*"         # No shell access
    - "git:git_commit"  # Read-only git

Output Convention

All default tools follow the same output pattern:

{"ok": true, "data": { ... }}

{"ok": false, "error": "Description of what went wrong"}

The outer {"ok": ..., "data": ...} wrapper is added by supypowers itself. The tool's return value becomes the data field.

Auto-Skipped Directories

The search and find tools automatically skip common noise directories:

__pycache__, node_modules, .git, .venv, venv, .tox, .mypy_cache, .pytest_cache, dist, build, .egg-info, .eggs

Built-in Tools Overview