Modify Files
synapse_modify_filesPreview and apply atomic file writes with lint checks and automatic rollback, or run global regex find-and-replace across the codebase files.
Instructions
Modifies files in the workspace. For safe agent workflows, first call 'write_safely' with dry_run: true, pre_check: true, and lint: true; review the preview, then call again with dry_run: false only when applying. High-level actions include:
'write_safely': writes content with atomic lint validation, dry-run semantic diff simulation, pre_check blast radius mapping, and automatic rollback on failure.
'find_and_replace': runs global regex find-and-replace across matching indexed files with instant re-indexing.
'delete_chunk': removes a chunk from the index.
REPLACES: write_to_file, replace_file_content, multi_replace_file_content, manual lint + commit cycles. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Preview and apply atomic safe file writes, global find-and-replace, or delete chunks.
Usage (long): Write files safely with automatic lint checks and revert on failure, run workspace-wide find and replace, or purge chunk entries. Always call synapse_get_context (edit) before this tool to understand callers, callees, and tests. For write_safely, first call with dry_run: true, pre_check: true, and lint: true so the agent sees semantic safety, compilation errors, contract warnings, and blast radius without touching disk. Apply with dry_run: false only after reviewing that preview. Validates with Trunk linter — rolls back atomically on lint failure.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter by entity kind (used in 'find_and_replace'). | |
| lint | No | Set false to bypass Trunk validation and write unconditionally (used in 'write_safely'). | |
| path | No | Filter by partial file path (used in 'find_and_replace'). | |
| files | No | List of file write operations (used in 'write_safely'). Each entry requires path and mode. | |
| limit | No | Max number of files to modify (safety limit, 1-100, used in 'find_and_replace'). | |
| query | No | The PCRE regular expression to search for (used in 'find_and_replace'). | |
| action | Yes | The modification action to perform. | |
| dry_run | No | Always set true first to perform a semantic simulation of the proposed changes without writing to disk (used in 'write_safely'). Set false only after reviewing the preview and deciding to apply. | |
| repo_id | No | Repository ID to resolve relative paths or scope filters. | |
| chunk_id | No | The chunk ID to permanently delete (used in 'delete_chunk'). | |
| language | No | Filter by language (used in 'find_and_replace'). | |
| pre_check | No | Set true to run a blast radius analysis before writing (used in 'write_safely'). | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| replacement | No | The replacement string. Supports backreferences like \1, \2, etc (used in 'find_and_replace'). | |
| case_insensitive | No | Set to true to ignore case (used in 'find_and_replace'). | |
| compress_payload | No | Set false to disable lossless response-key compression. | |
| wait_for_ready_ms | No | Optional timeout in ms to wait for the indexer to finish warming up and enter an idle state before executing. Use to ensure stable results. |