# Cheez Read

> Smart code reading using tilth MCP. Replaces cat/head/tail with AST-aware file reading. Automatically outlines large files, memorizes hash anchors for efficient editing, and tracks what you've already read to save tokens. Use when: reading files, exploring code structure, understanding modules, checking dependencies, or preparing for edits. Do NOT use for searching symbols or text — use cheez-search. Do NOT use for editing — use cheez-write. Examples: "read src/auth.ts", "show lines 44-89 of handlers.go", "what's in this directory?", "show the dependencies of this file".

- Skill: `paulnsorensen/cheez-read` (Agent Skill)
- Install (CLI): `npx skillmds@latest add paulnsorensen/cheez-read`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulnsorensen/cheez-read/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: paulnsorensen (https://skillmd.com/u/paulnsorensen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paulnsorensen/cheez-read

---


# cheez-read

> **Hard dependency**: If `mcp__tilth__tilth_read` is unavailable, stop immediately and report
> "tilth MCP server is not loaded — cannot proceed." Do NOT fall back to `cat`, `Read`, `Glob`,
> or any host tool.

Smart code reading via **tilth MCP** (`tilth_read`, `tilth_files`, `tilth_deps`).
tilth replaces cat/head/tail with AST-aware file reading that understands code structure.

---

## Core Principle: Read Smart, Not More

tilth decides what to show based on file size and structure:
- **Small files** → full content with line numbers
- **Large files** → structural outline with line ranges
- **Binary/generated** → skipped with type indicator

This means you never waste tokens on a giant lockfile or minified bundle.

---

## MCP Tool Reference

### tilth_read — Smart File Reading

```
tilth_read(path: "src/auth.ts")
```

**Output for small files:**
```
# src/auth.ts (258 lines, ~3.4k tokens) [full]

1 │ import express from 'express';
2 │ import jwt from 'jsonwebtoken';
...
```

**Output for large files (automatic outline):**
```
# src/auth.ts (1240 lines, ~16k tokens) [outline]

[1-12]   imports: express(2), jsonwebtoken, @/config
[14-22]  interface AuthConfig
[24-42]  fn validateToken(token: string): Claims | null
[44-89]  export fn handleAuth(req, res, next)
[91-258] export class AuthManager
  [99-130]  fn authenticate(credentials)
  [132-180] fn authorize(user, resource)
```

**Drilling into sections:**
```
# Line range
tilth_read(path: "src/auth.ts", section: "44-89")

# Markdown heading
tilth_read(path: "docs/guide.md", section: "## Installation")
```

**Multiple files in one call:**
```
tilth_read(paths: ["src/auth.ts", "src/routes.ts", "src/middleware.ts"])
```

---

## Hash Anchors — The Edit Bridge

When reading files, tilth outputs **hash-anchored lines**:

```
42:a3f│  let x = compute();
43:f1b│  return x;
```

The format is `<line>:<hash>│ <content>`.

**Why this matters:**
- These hashes uniquely identify the line content
- They're used by `tilth_edit` (cheez-write) for precise edits
- If the file changes, hashes won't match → edit is rejected safely
- You MUST read before editing to get current hashes

**Memorize anchors for functions you'll edit:**
- Note the start hash of function definitions
- Note the end hash for multi-line replacements
- Pass these to cheez-write later

---

## tilth_files — Directory Listing

Replaces `ls`, `find`, `pwd`, and the Glob tool.

```
tilth_files(glob: "**/*.ts", scope: "src/")
```

**Output:**
```
src/auth.ts  (~3.4k tokens)
src/routes.ts  (~2.1k tokens)
src/middleware.ts  (~1.8k tokens)
```

Token estimates help you decide what to read in full vs outline.

**Common patterns:**
```
# All TypeScript files
tilth_files(glob: "**/*.ts")

# Test files only
tilth_files(glob: "**/*.test.ts")

# Specific directory
tilth_files(glob: "*", scope: "src/handlers/")

# Exclude patterns
tilth_files(glob: "**/*.go", scope: ".", exclude: "*_test.go")
```

---

## tilth_deps — Blast Radius Check

Shows what imports this file and what it imports.

```
tilth_deps(path: "src/auth.ts")
```

**Output:**
```
# Dependencies for src/auth.ts

── imports ──
  express        external
  jsonwebtoken   external
  @/config       src/config/index.ts

── imported by ──
  src/routes/api.ts:5
  src/routes/admin.ts:8
  src/middleware/auth.ts:3
```

**Use ONLY before:**
- Renaming a file or module
- Removing exports
- Changing a function's signature
- Understanding refactoring impact

---

## Session Memory (Deduplication)

tilth tracks what you've read in the current session:
- Re-reading the same section shows `[shown earlier]` instead of full content
- This saves significant tokens over long sessions
- Forces you to reference memorized anchors instead of re-reading

**Implication:** Read once, memorize anchors, reference later.

---

## Reading Protocol

### For Understanding Code

1. **Start with outline** (let tilth auto-decide):
   ```
   tilth_read(path: "src/auth.ts")
   ```

2. **Drill into relevant sections:**
   ```
   tilth_read(path: "src/auth.ts", section: "44-89")
   ```

3. **Check dependencies if needed:**
   ```
   tilth_deps(path: "src/auth.ts")
   ```

### For Preparing Edits

1. **Read the target section to get hash anchors:**
   ```
   tilth_read(path: "src/auth.ts", section: "44-89")
   ```

2. **Memorize:**
   - Start anchor: `44:a3f`
   - End anchor: `89:b7c`

3. **Pass these to cheez-write** (tilth_edit) for the edit.

### For Exploring a Directory

1. **List files with token estimates:**
   ```
   tilth_files(glob: "*", scope: "src/handlers/")
   ```

2. **Read small files fully, outline large ones:**
   ```
   tilth_read(paths: ["small.ts", "large.ts"])
   ```

---

## DO NOT

- **DO NOT use cat/head/tail** — use tilth_read
- **DO NOT use ls/find** — use tilth_files
- **DO NOT re-read files** shown earlier — reference your notes
- **DO NOT use for searching** — use cheez-search (tilth_search)
- **DO NOT use for editing** — use cheez-write (tilth_edit)
- **DO NOT ignore hash anchors** — you'll need them for edits

---

## Output Token Budget

tilth uses ~6000 tokens as the outline threshold. Files under this show in full;
files over this get structural outlines. Use `section` to get hashlined content
for specific ranges when preparing edits on large files.

---

## What This Skill Doesn't Do

- **Search for symbols or text** — use cheez-search
- **Edit files** — use cheez-write
- **Run code or tests** — use appropriate build/test skills
- **Commit changes** — use commit skill