Local tools

Magic Coder runs locally with a small, well-defined set of tools. The agent uses these tools — not arbitrary API calls — to read your code, make changes, and run commands. Knowing what each tool does helps you understand what the agent is actually doing during a session.

All tools are constrained to the configured workspace roots. Operations outside those roots are rejected.

File operations

list_dir

Lists the contents of a directory. Returns names, types (file/dir/symlink), and basic metadata. The agent uses this to discover what’s at the workspace root and to navigate subtrees.

read_file

Reads a file’s contents, optionally a specific line range. The agent uses this aggressively — reading is cheap and grounds its decisions. Most file reads in a session come from this tool.

glob

Finds file or directory paths matching a glob pattern under a search root (e.g., **/*.tsx, src/**/*.{ts,tsx}). Use it for path discovery when you need a list of matching paths, not file contents.

grep

Searches file contents for a pattern using ripgrep semantics. Supports glob filters and file-type filters. The agent uses this to find symbols, references, and patterns across the workspace.

apply_diff

Applies a unified diff to one or more files. The diff format includes file headers (*** Add File:, *** Update File:, *** Delete File:) and standard hunk syntax. The agent generates diffs from its current understanding and submits them through this tool.

apply_diff is also how files get created, moved, and deleted as part of an edit. (Plain deletes use delete_files; see below.)

delete_files

Deletes one or more files by repo-relative path. Used when a clean delete is the goal — for example, removing dead code that lives in standalone files. For deletes that are part of a larger edit, the agent typically uses apply_diff with a *** Delete File: header instead.

Shell

run_shell

Runs a shell command via bash -lc (so pipes, redirection, and your login-shell environment all work). Inherits the environment Magic Coder was launched with — including any active venv, nvm shim, or environment variables. The default working directory is the primary --cwd root; the agent can target other workspace roots when needed.

Two modes:

• Foreground (bg = false, default). The command runs to completion (or hits timeout_seconds, default 30s). Stdout and stderr are captured up to max_output_bytes (default 200,000 bytes / ~200 KB). When output exceeds the cap, it’s cut from the middle — roughly the first 30% and last 70% are kept — so the agent sees both the start and the tail. The agent picks max_output_bytes deliberately per call: smallest reasonable value first, increased only when needed.
• Background (bg = true). The command starts in a long-running shell and the tool returns immediately with a shell ID. timeout_seconds and max_output_bytes are ignored — use read_shell_output and stop_shell for control. Up to 8 background shells can run at once; the 9th call errors out.

read_shell_output

Reads buffered output from a background shell by ID. The agent uses this to check on a dev server, a long-running build, or any process started with bg = true.

stop_shell

Stops a background shell by ID. The agent uses this to clean up a dev server or kill a runaway background job.

Skills and rules

These tools let the agent fetch the body of a Skill or Rule by name. They’re how on-demand rules and locally-authored skills get pulled into a turn.

invoke_skill

Invokes a locally-authored skill by name. Magic Coder reads the matching SKILL.md from <workspace>/.magic/skills/<name>/ (if trusted) or ~/.magic/skills/<name>/ and returns its body. The agent uses this when you trigger a skill via slash command.

read_rule

Reads the body of a rule by name. Used for rules with always_apply: false — only the rule’s name and description are visible up front; the agent calls read_rule to fetch the body when it judges the rule relevant.

Pacing

sleep

Pauses for a number of seconds, with an optional list of background shell IDs to wait on. Useful when the agent needs to give a process time to settle (e.g., wait for a server to start before hitting it).

Constraints:

• Values below 15 seconds clamp to 15 seconds. The agent can’t busy-loop with one-second sleeps.
• Maximum is 275 seconds.
• shell_ids: [] means “just wait — no shell to monitor.”

Permission gates

Every tool that mutates state — run_shell, apply_diff, delete_files — passes through Magic Coder’s approval system before it actually does anything:

• The agent sends the tool call.
• Magic Coder checks the call against your permission rules.
• If rules don’t allow it outright, the TUI prompts you. (In --automagic, the prompt auto-approves.)
• The tool runs only after approval.

Read-only tools (list_dir, read_file, glob, grep, read_shell_output, sleep, invoke_skill, read_rule) don’t go through the approval gate — they don’t change anything.

What the agent doesn’t have

Magic Coder’s tool surface is intentionally small. The agent does not have:

• Direct network access tools. It has shell, so it can curl if you allow it — but no first-class HTTP tool.
• A code execution tool separate from run_shell. Whatever the agent runs, it runs through your shell.
• A separate “package install” tool. Installing dependencies is done via run_shell with npm install, cargo add, etc.
• A separate “git” tool. Git is available through run_shell if your permission rules allow it.

Keeping the surface small is deliberate: every tool is a thing you understand and can audit.