Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.linksee.app/llms.txt

Use this file to discover all available pages before exploring further.

Read a file with diff-only caching. Use INSTEAD of the standard Read tool for files you have read before — saves 50%+ tokens on re-reads.

​
How it works

Read #File stateResponseTokens
1stNew fileFull content + chunk metadata~900
2ndUnchanged (same mtime)"unchanged" + cached chunk list~50
2ndTouched but identical (mtime changed, sha256 same)"unchanged_content"~50
2ndModifiedChanged chunks with content + unchanged chunks as metadata-only~200

​
Parameters

​
path
string
required
Absolute file path.
​
force
boolean
default:"false"
If true, return full content regardless of cache state.

​
Response statuses

​
first_read

Full file content with chunk metadata. Each chunk includes:
  • name — function name, heading text, or line range
  • hash — sha256 of chunk content
  • lines — line range in the file

​
unchanged

File mtime matches cache. Returns chunk list (names + hashes) without content. Maximum token savings.

​
unchanged_content

File mtime changed but sha256 matches — the file was touched (e.g. git checkout) but content is identical.

​
modified

File actually changed. Returns:
  • Changed chunks: full content included
  • Unchanged chunks: metadata only (name + hash)

​
Chunking strategies

File typeStrategyChunk identity
TS / JS / JSX / TSXAST via @babel/parserTop-level declarations (function name, class name, export)
PythonIndent-basedTop-level def / class blocks
MarkdownHeading-basedh2 / h3 sections
Everything elseFixed windows100-line blocks
AST-aware chunking means that if you add a function at the top of a file, only the new function shows as “changed” — existing functions keep their identity and hash, so they’re returned as metadata-only.

​
Example

{
  "path": "/home/user/project/src/db/connection.ts"
}
First read: 
{
  "status": "first_read",
  "chunks": [
    { "name": "import_block", "lines": "1-5", "hash": "abc123", "content": "import { Pool }..." },
    { "name": "createPool", "lines": "7-25", "hash": "def456", "content": "export function createPool()..." },
    { "name": "getConnection", "lines": "27-45", "hash": "ghi789", "content": "export async function..." }
  ],
  "total_tokens": 890
}
Second read (unchanged): 
{
  "status": "unchanged",
  "chunks": [
    { "name": "import_block", "lines": "1-5", "hash": "abc123" },
    { "name": "createPool", "lines": "7-25", "hash": "def456" },
    { "name": "getConnection", "lines": "27-45", "hash": "ghi789" }
  ],
  "total_tokens": 48
}
94.6% token savings.