Code Toolset¶

Tools for code analysis and manipulation.

Basic Usage¶

agents:
  coder:
    tools:
      - type: code

Available Tools¶

Code Tools

`format_code`

Format and lint a code file, returning a concise summary.

Parameters:

Name	Type	Required	Description
`path`	string	✓	Path to the file to format
`language`	string		Programming language (auto-detected from extension if not provided)

Category: execute

`ast_grep`

Search or transform code in a file using AST patterns.

Uses ast-grep for structural code search and rewriting based on abstract syntax trees. More precise than regex - understands code structure.

Pattern Syntax

$NAME - captures single node (identifier, expression, etc.)
$$$ITEMS - captures multiple nodes (arguments, statements, etc.)
Patterns match structurally, not textually

Rule Keys

Key	Description	Example
pattern	Code pattern with metavars	`"print($MSG)"`
kind	AST node type	`"function_definition"`
regex	Regex on node text	`"^test_"`
inside	Must be inside matching node	`{"kind": "class_definition"}`
has	Must contain matching node	`{"pattern": "return"}`
all	All rules must match	`[{"kind": "call"}, {"has": ...}]`
any	Any rule must match	`[{"pattern": "print"}, {"pattern": "log"}]`

Examples

Find all print calls:

rule={"pattern": "print($MSG)"}

Find and replace console.log:

rule={"pattern": "console.log($MSG)"}
fix="logger.info($MSG)"

Find functions containing await:

rule={
    "kind": "function_definition",
    "has": {"pattern": "await $EXPR"}
}

Parameters:

Name	Type	Required	Description
`path`	string	✓	Path to the file to analyze
`rule`	object	✓	AST matching rule dict (see examples below)
`fix`	string		Optional replacement pattern using $METAVARS from the rule
`dry_run`	boolean		If True, show changes without applying. If False, write changes.

Hints: idempotent

Category: search

`run_diagnostics`

Run LSP diagnostics (type checking, linting) on files.

Uses available CLI diagnostic tools (pyright, mypy, ty, oxlint, biome, etc.) to check code for errors, warnings, and style issues.

Parameters:

Name	Type	Required	Description
`path`	string	✓	Path to file or directory to check. For directories, checks all supported files recursively.

Hints: idempotent

Category: search

Configuration Reference¶

Code Toolset¶

Configuration for code toolset.

Code Toolset (YAML)
toolsets:
- type: code
  tools: null  # Optional tool filter to enable/disable specific tools.
  environment: null  # Optional execution environment. If None, falls back to agent's env at runtime.
  namespace: null  # Optional namespace prefix for tool names