cheez-read

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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/")

From paulnsorensen/cheese-flow, MIT.

More from paulnsorensen/cheese-flow