Read a file, returning as few tokens as possible. For 2+ files, use batch_read.

The first read returns the file's full content plus a content_hash. Echo it back as known_hash on every later read: an unchanged file then answers "unchanged": true with no body, a changed one returns a unified diff, and without it the file is always sent in full. Reading also caches the file so grep, search, and batch_read can see it.

Use offset/limit to read an exact line range, for example after a large file was summarized. A read that returns only part of a file — a line range, or a summary — reports file_hash (prefixed partial:) rather than content_hash, and it cannot be redeemed as known_hash. A ranged read also returns a coverage_token: pass it back as known_hash on your next ranged read and a window you already hold answers unchanged; once the windows cover the whole file you get a claimable content_hash.

For a large or unfamiliar file, outline=true is the cheap first read: one line per class/function as <line>: <signature>, and every number is an offset you can read next. An outline is a map, not the file, so it comes back as file_hash.

is_diff marks a unified diff and truncated marks a summary. A binary file returns metadata instead of content; for images use read_image.

Read an image file so the model can see it.

Returns an MCP image block (base64 data + mime type) plus a small JSON metadata sidecar (size, mime). Use this only when the model needs to view the image; for text or any other file type use read.

The format is detected from the file's magic bytes, not its extension, so a mis-named image still works and a non-image (e.g. text saved as .png) is rejected. Supports PNG, JPEG, GIF, TIFF, BMP, and WebP. Images are never cached — every call re-reads from disk. Oversized images are rejected before encoding; the cap is SCMCP_MAX_IMAGE_BYTES (default 5 MiB), bounded by Anthropic's ~5 MB upload limit.

Report cache health, token savings, and runtime diagnostics.

Returns storage occupancy (files, tokens, documents, DB size), session and lifetime token savings and cache hit rates, per-tool call counts, and process memory. Use it to measure or debug — not as a routine step in read/edit loops. Takes no arguments.

Empty the cache. Does not touch any project file.

Removes every cached file entry and returns how many were dropped; the next read/batch_read re-seeds from disk. Use rarely — only to recover from stale cache state or force a cold re-seed. Normal reads already refresh changed files on their own, so this is seldom needed. Takes no arguments.

Delete one file or symlink and evict its cache entries.

Use this for explicit single-path removal instead of shelling out. A missing path is reported as status not_found, not an error.

Statuses: deleted (removed), would_delete (dry-run preview only, and dry_run: true comes back with it), not_found (nothing was there). Constraints: one path only — no globs, no recursion, no real-directory deletes. A symlink path deletes the link itself, never its target.

Create a file or replace its entire contents.

Use this for new files or full rewrites; for localized changes prefer edit or batch_edit. Status is created for a new path or updated for an existing one; an update reports diff_state, and includes the diff against the previous content only when you ask with show_diff. A dry_run writes nothing and says so: the status is would_create/would_update and dry_run: true comes back with it. Writing refreshes the cache so later reads, grep, and search see the new text.

A full write supplies the whole file, so the content_hash it returns is claimable. An append only adds a tail: pass known_hash to show you held the rest, or you get file_hash instead. auto_format reports file_hash too — the formatter's output is not what you sent.

Edit one file by exact text replacement.

Three modes:

• find/replace: old_string + new_string (the default).

• scoped: add start_line/end_line to confine the search to a range.

• line-range: omit old_string and give both lines to replace them wholesale.

old_string must match exactly — whitespace and indentation included — and, unless replace_all=true, must be unique, or the edit fails. Use edit_preview first if you're unsure an anchor is unique. Returns the replacement count and the affected line numbers, and refreshes the cache. The diff itself is omitted unless you ask for it with show_diff; diff_state always tells you which you got. A dry_run writes nothing and says so: the status is would_edit and dry_run: true comes back with it. For several edits to one file use batch_edit; for a full rewrite use write.

Pass known_hash and the response carries a claimable content_hash, so no read is needed afterwards. Without it, or with auto_format, you get file_hash instead — editing a file is not the same as having read it.

Show where old_string would match in a file, without editing it.

Returns the match count, 1-based line numbers, and short snippets so you can confirm an anchor is unique before calling edit. Read-only and cheap (kept under ~200 tokens), so use it freely as a probe. Raises an error on a binary file or an empty old_string.

Apply many exact edits to one file in a single atomic call.

Preferred over repeated edit calls on the same file: one response, applied atomically, faster on large files. Partial success is allowed — any failed edits are returned with their reason so you can retry just the misses (status is edited when all apply, partial when some fail, no_changes when none do). A dry_run writes nothing and says so: the status becomes would_edit/would_partial and dry_run: true comes back with it. For edits across different files, call the tool once per file.

edits is a JSON array; each entry is one of:

• [old, new] — exact find/replace.

• [old, new, start_line, end_line] — find/replace confined to a range.

• [null, new, start_line, end_line] — replace that line range wholesale.

• {"old": ..., "new": ..., "start_line": ..., "end_line": ...} — object form.

Prefer line-range entries when you already have line numbers from read. Pass known_hash and the response carries a claimable content_hash, so no read is needed afterwards; without it, or with auto_format, you get file_hash instead.

Find cached files by keyword relevance (BM25 ranking).

Searches only files already in the cache — index them first with warm, which returns counts rather than content (thin results usually mean too few files are cached). Ranks by BM25 term relevance, so multi-word and keyword queries work well; matching is lexical, not embedding-based, so synonyms won't match a word that isn't present. Terms are OR'd — a word the corpus happens not to contain costs you ranking, not the whole result set. For an exact string or regex use grep; to pull more of the repo into the cache use batch_read. Returns matches with a normalized 0–1 relevance score (best match = 1.0) and a short preview. The cache is shared across projects, so a search with no directory ranks the current project only; name one to look elsewhere.

Read several files at once under a shared token budget.

Cheaper than many single read calls. To make files searchable without reading them at all, use warm instead — this tool returns their text. Pass known_hashes and each file you still hold collapses to an unchanged count, or to a diff when it moved on disk; the rest come back in full with their content_hash. A file large enough to come back summarized carries none: a summary is not the file. Smallest files are read first, and a file too big for the remaining budget is listed under skipped while smaller ones keep being read. Recover anything skipped with read using offset/limit. Paths are relative to the root the response names, when there is one worth naming.

Index files into the cache so grep and search can see them, returning counts only.

Costs a few dozen tokens however many files it indexes: no content, no previews, no paths for the files that succeeded — just how many were indexed, how many were already current, and how many were not.

Anything not indexed is counted in skipped, and the first few come back under failures with a reason (not_found, not_a_file, binary, too_large, unreadable, timeout). If a cap stopped the walk early you get truncated or incomplete rather than a short count that looks complete.

Use it before searching an unfamiliar tree, then grep for the exact string or search for the concept, and read only what those name.

List files matching a glob and show which are already cached.

Use it to discover files and see what search/grep can already access before you spend reads. Each match carries a cached flag; set cached_only=true to list only files already in the cache. Pair it with batch_read to pull in whatever isn't cached yet.

Search cached file contents for an exact string or regex.

Fast, exact, line-numbered matching over files already in the cache — it does NOT touch disk, so index files first with warm, which costs a few dozen tokens however many files it covers (empty results usually mean the files aren't cached). A pattern that is not a valid regex is an error, never an empty result, so zero matches always means zero matches. For concept-level questions where you don't know the exact term, use search instead.

Counts are complete unless the response says otherwise: if a cap stops the scan, complete comes back false with limit_reached naming which one, so total_matches is never mistaken for the total that exists.

Each file's hits come back as "<line>:<text>" strings under lines, with context lines using - instead of :. Paths are relative to the root the response names, when there is one worth naming. The cache is shared across projects, so a relative path — or none — searches only the current project; an absolute path reaches files anywhere.

A repeated group wrapping an unbounded quantifier ((a+)+) is rejected rather than run — it can take exponential time and cannot be interrupted once started. Drop the redundant repeat, or pass fixed_string=true.