Tools Reference

Complete reference for CodeBuddy Code's available tools, including permission requirements.

CodeBuddy Code includes a set of built-in tools to help understand and modify your codebase. The tool names in the table below are the identifiers used in permission rules, sub-agent tool lists, and Hook matchers.

Tool	Description	Requires Permission
`Agent`	Spawns a sub-agent with an independent context window to handle tasks	No
`Artifact`	Publishes a local HTML or Markdown file as an artifact and returns a shareable public link (Markdown is rendered server-side into a styled page). Pass `existingShareLink` to update the same link in place (refreshing content only, without changing permissions). Enabled by default; can be disabled via `CODEBUDDY_ARTIFACT_ENABLED` or cloud `productFeatures.Artifact` (legacy switches `CODEBUDDY_SHARE_LINK_ENABLED` / `productFeatures.ShareLink` remain compatible). Formerly named `ShareLink`; the old name is still matched only in permission rules (allow/deny, `disallowedTools`); hooks matchers and `--tools` whitelist only recognize the new name, so update your configuration accordingly. See Environment Variables	Yes
`ArtifactControl`	Performs control actions on artifacts published via `Artifact`; currently supports only unpublish: setting a public link to private. HTML page links are unpublished; Markdown document links have public access disabled and collaborators removed. Accepts a full link or a bare nodeId. Formerly named `ShareLinkUnpublish` (compatibility scope same as `Artifact`)	Yes
`AskUserQuestion`	Asks the user a multiple-choice question to gather requirements or clarify ambiguities	Yes
`AskUserForStructuredInput`	Lets the client render a constrained JSON Schema as a form to collect structured responses (multiple fields, each with its own control). Suitable for scenarios such as multiple MCP authorizations or multi-field forms that cannot be expressed through single- or multiple-choice questions. Requires the `CODEBUDDY_ENABLE_ASK_USER_FOR_STRUCTURED_INPUT=1` environment variable and the client to declare the `elicitation.form` capability; otherwise, the tool is not exposed to the model	Yes
`Bash`	Executes shell commands in your environment. See Bash Tool Behavior	Yes
`CronCreate`	Schedules recurring or one-time tasks. By default, tasks are only valid in the current session (expire on exit); passing `durable: true` persists the task to disk and keeps it running in a dedicated task session, which requires a one-time permission grant. See Scheduled Tasks	Required for durable tasks
`CronDelete`	Cancels a scheduled task by ID	No
`CronList`	Lists all scheduled tasks in the current session	No
`DeferExecuteTool`	Executes a deferred tool discovered via `ToolSearch`	No
`Edit`	Performs precise string replacement edits on files	Yes
`EnterPlanMode`	Switches to plan mode for designing implementation approaches before coding	No
`EnterWorktree`	Creates an isolated git worktree and switches into it	Yes
`ExitPlanMode`	Submits a plan for user approval and exits plan mode	Yes
`Glob`	Finds files using glob patterns	No
`Grep`	Searches file contents using regex patterns	No
`ImageGen`	Generates images from text descriptions, supporting both text-to-image and image-to-image	Yes
`LeaveWorktree`	Exits the worktree session and returns to the original directory	Yes
`ListMcpResources`	Lists all resources/templates exposed by connected MCP servers; optionally filtered by server name	No
`LSP`	Provides code intelligence via Language Server. Automatically reports type errors and warnings after file edits. Also supports navigation operations such as go-to-definition, find references, get type info, list symbols, find implementations, and trace call hierarchies. Requires a Code Intelligence Plugin and its language server binary	No
`MultiEdit`	Performs multiple edits on the same file in a single atomic operation	Yes
`NotebookEdit`	Modifies Jupyter notebook cell contents	Yes
`NotebookRead`	Reads Jupyter notebook cell contents; specify `cell_id` to read a single cell	No
`PowerShell`	Executes PowerShell commands on Windows. Only available on Windows, see PowerShell Tool Behavior	Yes
`PushNotification`	Sends terminal/desktop notifications to alert the user when long-running or background tasks complete. A deferred tool, see Environment Variables	No
`Read`	Reads file contents, supporting images, PDFs, and Jupyter notebooks	No
`REPL`	Runs JavaScript in an isolated sandbox to orchestrate tool calls. In PTC / Minimal this is the model's only direct tool; sandbox Bash returns `{ stdout, stderr, exitCode, signal }`, Agent returns `{ taskId }`, TaskOutput returns `{ status, taskId, content }`. Gated by `CODEBUDDY_CODE_MODE_ENABLED`; see Environment Variables	Yes
`ReadMcpResource`	Reads the content of a specific MCP resource by server + URI; pairs with `ListMcpResources`	Yes
`ReportFindings`	Submits code review findings as structured fields (file, summary, failure scenario, optional category), rendered as a dedicated list component rather than plain text. A deferred tool, see Environment Variables	No
`SendMessage`	Sends messages to teammates in an Agent Team	No
`SendUserMessage`	Sends user-facing messages (supports Markdown, attachments, and `status` intent tags). Only available in Brief mode (`--brief` or `CODEBUDDY_BRIEF`); see Environment Variables	No
`Skill`	Executes a Skill in the main conversation	No
`SlashCommand`	Executes a custom slash command	Yes
`StructuredOutput`	Returns structured output conforming to a JSON Schema	No
`TaskCreate`	Creates a new task in the task list	No
`TaskGet`	Retrieves full details of a specific task	No
`TaskList`	Lists all tasks with their current status	No
`TaskOutput`	Retrieves output from a background task or sub-agent. Parameters: `task_id` (required), `block` (default true), `timeout` (default 60000ms). In REPL returns `{ status, taskId, content }`; `running` is not completion	No
`TaskStop`	Stops a running background task by ID	No
`TaskUpdate`	Updates task status, dependencies, details, or deletes a task	No
`TeamCreate`	Creates an Agent Team for coordinating multiple agents	No
`TeamDelete`	Deletes an Agent Team and its task directory	No
`VideoGen`	Generates videos from text descriptions or input images, supporting both text-to-video and image-to-video	Yes
`ToolSearch`	Searches and loads deferred tools, supporting both built-in tools and MCP tools; can be combined with `Defer(...)`/`NoDefer(...)` modifiers to adjust tool deferred loading status on demand	No
`WaitForMcpServers`	Waits for the specified MCP servers to finish connecting (defaults to all pending servers), with a 5-second timeout	No
`WebFetch`	Fetches content from a specified URL and performs AI analysis	Yes
`WebSearch`	Performs a web search	Yes
`Workflow`	Launches a Dynamic Workflow asynchronously, returns a runId immediately, and runs in the background; pull results via `TaskOutput`	Yes
`Write`	Creates or overwrites files	Yes

Permission rules can be configured via the /permissions command or in permission settings. See also Tool-Specific Permission Rules.

Tool Aliases

Some tools have aliases that can be used interchangeably in permission rules (applicable only to permission rules allow/deny/ask and disallowedTools; hooks matchers and --tools whitelist only match by the tool's real name):

Tool	Alias
`TaskOutput`	`BashOutput`
`TaskStop`	`KillShell`
`PowerShell`	`pwsh`, `ps`
`Artifact`	`ShareLink` (name before rename)
`ArtifactControl`	`ShareLinkUnpublish` (name before rename)

Execution Order of Multiple Tool Calls in One Turn

The model can issue multiple tool calls in a single response. CodeBuddy Code schedules them according to the following rules:

Read-only calls can run concurrently: adjacent read-only calls execute at the same time, for example Read, Glob, Grep, LSP, WebFetch, WebSearch, ToolSearch, TaskGet, TaskList, TaskOutput, Agent, and read-only Bash / PowerShell commands. By default, at most 10 run at the same time, and the rest are queued in order; adjust this with the environment variable CODEBUDDY_MAX_TOOL_USE_CONCURRENCY.
Other calls run sequentially in the order the model issued them: Write, Edit, TaskCreate, Shell commands that modify files or run programs, MCP tools not declared read-only, and so on start only after all preceding calls have finished, and subsequent calls wait for them to finish as well.

So when the model writes a file with Write and then runs it with Bash in the same turn, the command is guaranteed to see the written file.

Calls awaiting approval also block subsequent calls: when a call needs your confirmation, the calls queued after it (including ones like Read that would otherwise need no approval) wait until you handle the approval dialog. For example, if in the same turn Bash runs a script that generates an image and Read reads that image, Read reads it only after you approve and Bash finishes executing.

After approval, subsequent calls continue in order; if any of them also need confirmation, another approval dialog appears.
After rejection, subsequent calls are not executed; the UI shows them as Skipped (an earlier tool call was rejected), and the model is told they were not executed rather than treating them as empty results.

A Bash command runs concurrently with other calls only when it is clearly read-only, for example ls, cat, head, grep, rg, find (without actions such as -exec or -delete), git status, git log, git diff, and commands combining them with |, &&, or ;. Commands containing output redirection (except to /dev/null), command substitution, background execution (& or run_in_background), cd, environment variable prefixes, or unrecognized commands all run sequentially. PowerShell follows the same approach: only commands composed of read-only cmdlets such as Get-* run concurrently.

Whether an MCP tool runs concurrently depends on whether the server declares readOnlyHint: true in the tool annotations; see MCP Integration.

Bash Tool Behavior

The Bash tool executes each command in a separate process with the following persistence characteristics:

Working directory persists across commands. Set CODEBUDDY_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 to reset to the project directory after each command.
Environment variables do not persist. An export in one command will not take effect in the next command.

Activate your virtualenv or conda environment before launching CodeBuddy Code. To persist environment variables across Bash commands, set CODEBUDDY_ENV_FILE to point to a shell script before startup, or use a SessionStart Hook to populate it dynamically.

Sandbox Mode

The Bash tool supports sandbox isolation, which can restrict filesystem and network access. When sandbox is enabled, commands execute in a restricted environment to prevent unauthorized system access.

The dangerouslyDisableSandbox parameter allows bypassing the sandbox on a per-command basis (requires user approval).

Background Execution

Use the run_in_background parameter to run commands in the background, and read output with the TaskOutput tool. This is suitable for long-running builds, tests, and similar scenarios.

Display of Failed Commands

When a command exits with a non-zero exit code, the interactive UI shows Exit code <N> on the first line of the result and displays the command output in the error color, so the failure is visible even when the output is collapsed. The model also receives the exit code and stderr and can adjust its next step accordingly. The PowerShell tool displays failures the same way.

PowerShell Tool Behavior

The PowerShell tool is only available on Windows and provides native PowerShell command execution.

Relationship with Bash Tool

With Git Bash: Both Bash and PowerShell tools are available; the model chooses the appropriate tool based on the scenario
Without Git Bash: The Bash tool is automatically disabled, and the PowerShell tool becomes the only shell tool
The PowerShell tool is not available on macOS/Linux

Version Adaptation

The PowerShell tool automatically detects the PowerShell version, preferring PowerShell 7+ (pwsh) and falling back to Windows PowerShell 5.1. Syntax guidance in prompts adjusts automatically based on version differences (e.g., the && operator is only supported in 7+).

Security Checks

The PowerShell tool includes a built-in security checker covering dangerous patterns such as code injection, download-and-execute, privilege escalation, and system destruction. Dangerous commands (e.g., Invoke-Expression, Add-Type) are blocked, and system-modifying commands require user confirmation.

Environment Variables

Environment Variable	Description
`CODEBUDDY_POWERSHELL_PATH`	Explicitly specify the PowerShell path (takes priority over auto-detection)
`CODEBUDDY_USE_POWERSHELL_TOOL`	Set to `0` to disable the PowerShell tool

Deferred Tool Loading

Some tools (such as those provided via MCP servers, as well as a few built-in tools like PushNotification and ReportFindings) use deferred loading. These tools do not appear in the initial tool list and must be discovered and activated via ToolSearch. Once activated, tools remain available for the rest of the session.

Tools Reference ​

Tool Aliases ​

Execution Order of Multiple Tool Calls in One Turn ​

Bash Tool Behavior ​

Sandbox Mode ​

Background Execution ​

Display of Failed Commands ​

PowerShell Tool Behavior ​

Relationship with Bash Tool ​

Version Adaptation ​

Security Checks ​

Environment Variables ​

Deferred Tool Loading ​

See Also ​