Read a file with token-efficient caching. For 2+ files, use batch_read.

Returns full content on first read, "unchanged": true on re-read of an unchanged file (content already in your context — do NOT re-read), or a unified diff when modified. Use offset/limit to recover line ranges after truncation.

Args: path: File path (absolute or relative to project root). Use absolute paths for files outside the current project root. max_size: Maximum content size to return before summarization. offset: 1-based starting line number for targeted reads. 0 is treated as "from the start" (equivalent to omitting). limit: Number of lines to return from offset.

Read an image file and pass the bytes through to the model.

Returns an MCP image content block (base64-encoded with mime type) plus a JSON metadata sidecar. Use this when the model needs to actually see the image; for any other file type use read.

Images are NOT cached — every call re-reads from disk. Cap is SCMCP_MAX_IMAGE_BYTES (default 5 MiB) to protect both the response budget and Anthropic's ~5 MB upload limit.

Args: path: Image file path (absolute or relative to project root).

Inspect cache health, token savings, and runtime diagnostics.

Use this for debugging or measurement, not as a normal step in routine read/edit loops.

Returns cache occupancy, hit rates, token savings, tool-call counts, embedding model info, and process memory usage.

Clear the semantic cache only; does not modify project files.

Use this rarely, mainly to recover from stale cache state or to force cold re-seeding. Prefer normal read/batch_read refresh behavior when possible.

Returns the number of cached entries removed.

Delete one file or one symlink path and evict cache entries for that path.

Use this for explicit single-path removal instead of shelling out.

Normal statuses:

• deleted: file or symlink path was removed

• would_delete: dry-run preview only

• not_found: path did not exist; this is not an error

Constraints:

• No globs

• No recursive delete

• No real-directory delete

• If path is a symlink, deletes the link itself, not the target

Args: path: File or symlink path (absolute or relative to project root). dry_run: Preview without deleting or evicting cache.

Create or replace a file. Prefer edit/batch_edit for localized changes.

Overwrites the whole file, or appends with append=true. Reports status created for a new path or updated for an existing one; an update also returns a unified diff against the previous content.

Args: path: File path to create or replace. content: Full content to write, or appended content when append=true. create_parents: Create missing parent directories when needed. dry_run: Preview without writing. auto_format: Run formatter after write. show_diff: Return the diff explicitly even for deterministic writes. append: Append instead of overwrite.

Edit one file via exact replacement.

For multiple edits to the same file, use batch_edit (single response, atomic, faster). For full rewrites, use write.

Modes: find/replace (old_string+new_string), scoped (add start_line/end_line), or line-range (omit old_string, provide both lines). Keep old_string short and unique; add line bounds when ambiguous.

Args: path: File path to modify. old_string: Exact text to find. Omit only for line-range replacement. new_string: Replacement text. replace_all: Replace all matches instead of requiring uniqueness. dry_run: Preview without writing. auto_format: Run formatter after editing. show_diff: Return the diff explicitly for successful deterministic edits. start_line: 1-based inclusive start line for scoped or line-range edit. end_line: 1-based inclusive end line for scoped or line-range edit.

Preview where old_string matches in a file without modifying it.

Returns match count, 1-based line numbers, and small snippets so the caller can confirm an anchor is unique before committing to edit. Read-only and intentionally cheap — under ~200 tokens — so it can be called freely as a probe.

Args: path: File path to search. old_string: Anchor text. Must match exactly (whitespace, indentation).

Apply multiple exact edits to one file in a single call.

Preferred over repeated edit calls on the same file: single response, atomic across all edits, and faster on large files. For cross-file work, call the relevant tools per file instead of trying to batch across files.

Supported entry forms:

• [old, new] for full-file exact replacement

• [old, new, start_line, end_line] for scoped replacement

• [null, new, start_line, end_line] for line-range replacement

• {"old": ..., "new": ..., "start_line": ..., "end_line": ...}

Behavior:

• Partial success is allowed.

• Failed edits are returned so you can retry only the misses.

• Prefer line-range entries when you already have line numbers from read.

• Deterministic all-success batches omit full diffs unless show_diff=true or debug mode is enabled.

Args: path: File path to modify. edits: JSON array of edit entries for that file. dry_run: Preview without writing. auto_format: Run formatter after edits. show_diff: Return the diff explicitly for successful deterministic batches.

Find code by meaning when you don't know the exact name to grep for.

Use this first for concept-level questions — "where is rate limiting handled", "what validates the config", "code that retries failed requests" — where you have intent but not a literal string or symbol. Once you know the exact token, grep is the faster, exact follow-up.

Ranks cached files by semantic similarity to the query. Operates on files already seeded via read/batch_read; if results look thin, seed more of the repo with batch_read and retry.

Args: query: Natural-language query, keywords, or a mixture of both. k: Maximum number of matches to return. directory: Optional directory filter applied after retrieval. show_preview: Include match previews explicitly.

Read multiple files under a token budget.

Use to seed cache before search/grep; prefer over repeated read calls. Returns diffs for modified files, full content for new ones; large files skipped when budget exhausted (use read with offset/limit to recover).

Args: paths: Comma-separated paths, JSON array, or glob patterns. max_total_tokens: Token budget across the batch. priority: Optional paths to read first before the remaining files.

Discover files by glob and show which are already cached.

Use before batch_read/search/grep. cached_only=true shows what search/grep can see without more reads.

Args: pattern: Glob pattern to expand. directory: Base directory for the glob. cached_only: Restrict results to already cached files.

Cache-only ripgrep: exact string/regex with line numbers.

Use search for semantic intent. Seed files with batch_read first; empty results often mean files not cached.

Args: pattern: Regex pattern, or a literal if fixed_string=true. path: Optional exact path, suffix, or glob filter. fixed_string: Treat pattern as a literal instead of regex. case_sensitive: Whether matching is case-sensitive. context_lines: Number of context lines to include around matches. max_matches: Maximum total matches across all files. max_files: Maximum number of files to return.