tilth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

tilth — structural code intelligence (v0.5.1)

tilth — 结构化代码智能工具（v0.5.1）

⚠️ MANDATORY: Use
tilth
instead of
read
,
grep
,
find
,
cat
Every time you reach for
read
, ask: can tilth do this? It almost always can, and does it better — structural outlines, tree-sitter symbol search, and token-aware output in one call.
read
is only acceptable when: tilth is not installed, file is binary/image/PDF, or you need raw bytes.

⚠️ 强制要求：使用
tilth
替代
read
、
grep
、
find
、
cat
每次你想要使用
read
时，请先问自己：tilth能完成这个操作吗？ 它几乎总能做到，而且做得更好——一次调用即可实现结构化大纲、tree-sitter符号搜索和感知令牌的输出。
仅在以下情况可使用
read
： tilth未安装、文件为二进制/图片/PDF格式，或者你需要读取原始字节。

Quick Reference

快速参考

Task	Command
Read a file	`tilth src/foo.py`
Read lines 100–200	`tilth src/foo.py --section 100-200`
Read markdown section	`tilth README.md --section "## API"`
Force full content	`tilth src/foo.py --full`
Find symbol definition	`tilth handleAuth --scope src/`
Search literal text	`tilth "TODO: fix" --scope src/`
Regex search	`tilth "/pattern/" --scope src/`
Case-insensitive regex	`tilth "/pattern/i" --scope src/`
Find files by glob	`tilth "*.test.ts" --scope src/`
Codebase map	`tilth --map --scope src/`
Limit output tokens	`tilth handleAuth --scope src/ --budget 2000`

任务	命令
读取文件	`tilth src/foo.py`
读取100-200行	`tilth src/foo.py --section 100-200`
读取Markdown章节	`tilth README.md --section "## API"`
强制输出完整内容	`tilth src/foo.py --full`
查找符号定义	`tilth handleAuth --scope src/`
搜索文本内容	`tilth "TODO: fix" --scope src/`
正则表达式搜索	`tilth "/pattern/" --scope src/`
不区分大小写的正则搜索	`tilth "/pattern/i" --scope src/`
按通配符查找文件	`tilth "*.test.ts" --scope src/`
生成代码库映射	`tilth --map --scope src/`
限制输出令牌数量	`tilth handleAuth --scope src/ --budget 2000`

Query Auto-Classification

查询自动分类

tilth has a single

<query>

argument. It classifies automatically — no mode flags needed:

Priority	Pattern	Classification
1	`*` , `?` , `{` , `[` (no spaces)	Glob — file search
2	Contains `/` or starts with `./` `../`	File path — read file
3	Starts with `.` and resolves to a file	File path (dotfile)
4	Pure digits ( `404` , `200` )	Content search
5	Looks like a filename (has extension)	File path if exists on disk
6	`/pattern/` or `/pattern/i`	Regex search
7	Identifier (starts with letter/ `_` / `$` / `@` , no spaces)	Symbol search
8	Everything else	Content search

If a path-like query doesn't resolve to a file, tilth falls through to symbol → content search.

tilth仅需一个

<query>

参数，会自动进行分类——无需使用模式标志：

优先级	模式	分类
1	`*` , `?` , `{` , `[` （无空格）	通配符 —— 文件搜索
2	包含 `/` 或以 `./` `../` 开头	文件路径 —— 读取文件
3	以 `.` 开头且可解析为文件	文件路径（隐藏文件）
4	纯数字（如 `404` , `200` ）	内容搜索
5	类似文件名（含扩展名）	文件路径（若磁盘上存在该文件）
6	`/pattern/` 或 `/pattern/i`	正则表达式搜索
7	标识符（以字母/ `_` / `$` / `@` 开头，无空格）	符号搜索
8	其他所有情况	内容搜索

若类路径的查询无法解析为文件，tilth会依次降级为符号搜索→内容搜索。

Commands

命令说明

Read a file

读取文件

bash

tilth <path>                          # smart view: full if small, outline if large
tilth <path> --section 45-89          # exact line range
tilth <path> --section "## Foo"       # markdown heading section
tilth <path> --full                   # force full content even if large

Files < ~6000 tokens: full content with line numbers.
Files > ~6000 tokens: structural outline with line ranges — functions, classes, imports. Use
```
--section
```
to drill into specific ranges.
Outlined files append a
```
> Related: ...
```
hint listing imported/related files.

Example — large file auto-outline:

$ tilth src/server.rs

bash

tilth <path>                          # 智能视图：小文件输出完整内容，大文件输出大纲
tilth <path> --section 45-89          # 读取指定行范围
tilth <path> --section "## Foo"       # 读取Markdown标题对应的章节
tilth <path> --full                   # 强制输出完整内容，忽略智能视图逻辑

文件**< ~6000令牌**：输出带行号的完整内容。
文件**> ~6000令牌**：输出带行范围的结构化大纲——包含函数、类、导入语句。使用
```
--section
```
深入查看特定范围。
大纲形式的文件末尾会附加
```
> 相关文件: ...
```
提示，列出导入的相关文件。

示例 —— 大文件自动生成大纲：

$ tilth src/server.rs

src/server.rs (1,247 lines, ~18.2k tokens) [outline]

src/server.rs（1247行，~18.2k令牌）[大纲]

[1-15] imports: hyper(3), tokio, serde_json, crate::config [17-34] struct ServerConfig [36-89] impl ServerConfig [38-52] fn from_env() -> Result<Self> [54-89] fn validate(&self) -> Result<()> [91-340] struct HttpServer [105-180] async fn start(&self) -> Result<()> [182-260] async fn handle_request(&self, req: Request) -> Response

Related: src/config.rs, src/router.rs


Then drill in: `tilth src/server.rs --section 105-180`

[1-15] 导入语句: hyper(3), tokio, serde_json, crate::config [17-34] 结构体 ServerConfig [36-89] ServerConfig 实现块 [38-52] fn from_env() -> Result<Self> [54-89] fn validate(&self) -> Result<()> [91-340] 结构体 HttpServer [105-180] async fn start(&self) -> Result<()> [182-260] async fn handle_request(&self, req: Request) -> Response

相关文件: src/config.rs, src/router.rs


随后可深入查看：`tilth src/server.rs --section 105-180`

Search for symbols

搜索符号

bash

tilth <symbol> --scope <dir>          # definitions first, then usages

Uses tree-sitter AST to find definitions first, then usages — not just string matching.
Expanded results include the full function/class body inline — often no separate read needed.
Expanded definitions include a
```
── calls ──
```
footer with resolved callees (file, line, signature). Follow these to trace call chains without extra searches.
A
```
── siblings ──
```
footer shows nearby definitions in the same scope.

Example:

$ tilth handleAuth --scope src/

bash

tilth <symbol> --scope <dir>          # 优先查找定义，再查找引用

利用tree-sitter抽象语法树优先查找符号定义，再查找引用——而非简单的字符串匹配。
展开的结果会直接包含完整的函数/类代码——通常无需额外读取文件。
展开的定义末尾会附加
```
── 调用关系 ──
```
脚注，列出已解析的被调用函数（文件、行号、签名）。直接通过这些链接追踪调用链，无需额外搜索。
```
── 同级符号 ──
```
脚注会显示同一作用域内的其他附近定义。

示例：

$ tilth handleAuth --scope src/

Search: "handleAuth" in src/ — 6 matches (2 definitions, 4 usages)

搜索: "handleAuth" 在 src/ 目录下 —— 6个匹配结果（2个定义，4个引用）

src/auth.ts:44-89 [definition]

src/auth.ts:44-89 [定义]

[24-42] fn validateToken(token: string) → [44-89] export fn handleAuth(req, res, next) [91-120] fn refreshSession(req, res)

44 │ export function handleAuth(req, res, next) { 45 │ const token = req.headers.authorization?.split(' ')[1]; ... 89 │ }

── calls ── validateToken src/auth.ts:24-42 fn validateToken(token: string): Claims | null refreshSession src/auth.ts:91-120 fn refreshSession(req, res)

[24-42] fn validateToken(token: string) → [44-89] export fn handleAuth(req, res, next) [91-120] fn refreshSession(req, res)

44 │ export function handleAuth(req, res, next) { 45 │ const token = req.headers.authorization?.split(' ')[1]; ... 89 │ }

── 调用关系 ── validateToken src/auth.ts:24-42 fn validateToken(token: string): Claims | null refreshSession src/auth.ts:91-120 fn refreshSession(req, res)

src/routes/api.ts:34 [usage]

src/routes/api.ts:34 [引用]

→ [34] router.use('/api/protected/*', handleAuth);


**Key:** The `── calls ──` footer gives you the exact file and line range for each callee. Drill directly with `tilth src/auth.ts --section 24-42` instead of searching again.

→ [34] router.use('/api/protected/*', handleAuth);


**关键提示：** `── 调用关系 ──`脚注提供了每个被调用函数的准确文件和行范围。直接使用`tilth src/auth.ts --section 24-42`查看，无需再次搜索。

Content and regex search

内容与正则表达式搜索

bash

tilth "TODO: fix" --scope <dir>       # literal text search
tilth "/<regex>/" --scope <dir>       # regex search (wrap in slashes)
tilth "/<regex>/i" --scope <dir>      # case-insensitive regex

Content search finds literal strings, comments, and text. Regex uses full regex syntax inside

/slashes/

bash

tilth "TODO: fix" --scope <dir>       # 文本内容搜索
tilth "/<regex>/" --scope <dir>       # 正则表达式搜索（用斜杠包裹）
tilth "/<regex>/i" --scope <dir>      # 不区分大小写的正则搜索

内容搜索会查找字面字符串、注释和文本。正则搜索支持在

/斜杠/

内使用完整的正则语法。

Find files by glob

按通配符查找文件

bash

tilth "*.test.ts" --scope src/        # find test files
tilth "**/*.{json,toml}" --scope .    # brace expansion

Glob results include token estimates per file — use these to plan reads.

bash

tilth "*.test.ts" --scope src/        # 查找测试文件
tilth "**/*.{json,toml}" --scope .    # 大括号扩展匹配

通配符搜索结果会包含每个文件的令牌估算值——可用于规划读取操作。

Codebase map

生成代码库映射

bash

tilth --map --scope src/              # structural overview

Shows directory tree with token estimates. Use once per session to orient yourself, then switch to targeted searches.

bash

tilth --map --scope src/              # 生成结构化代码库概览

显示带令牌估算值的目录树。每个会话仅需运行一次来熟悉代码库，之后使用针对性搜索即可。

Flags Reference

参数参考

Flag	Effect
`--scope <dir>`	Directory to search within (default: `.` )
`--section <range>`	Line range ( `45-89` ) or markdown heading ( `"## Foo"` )
`--budget <N>`	Max tokens in response — reduces detail to fit
`--full`	Force full output, override smart view
`--json`	Machine-readable JSON output
`--map`	Generate structural codebase map
`--edit`	Enable edit mode: hashline output + tilth_edit tool

参数	作用
`--scope <dir>`	搜索的目标目录（默认值： `.` ）
`--section <range>`	指定行范围（如 `45-89` ）或Markdown标题（如 `"## Foo"` ）
`--budget <N>`	响应的最大令牌数——自动减少细节以限制输出
`--full`	强制输出完整内容，覆盖智能视图逻辑
`--json`	输出机器可读的JSON格式结果
`--map`	生成结构化代码库映射
`--edit`	启用编辑模式：输出哈希行 + tilth_edit工具

Workflow

工作流程

The optimal pattern

最优使用模式

Search first.
```
tilth handleAuth --scope src/
```
finds definitions with full source inline — often no read needed.
Read outlined files in sections. Note
```
[start-end]
```
line ranges from outlines, drill with
```
--section
```
.
Follow
── calls ──
footers. Don't search for callees — follow the file:line directly.
Don't re-read expanded results. If search showed the full body, answer from that output.

优先搜索。
```
tilth handleAuth --scope src/
```
会直接找到包含完整源代码的符号定义——通常无需额外读取文件。
分章节读取大纲文件。从大纲中记录
```
[起始-结束]
```
行范围，使用
```
--section
```
深入查看。
跟随
── 调用关系 ──
脚注。无需搜索被调用函数——直接跟随文件:行号的链接。
避免重复读取已展开的结果。如果搜索结果已显示完整代码，直接从该输出中获取信息即可。

Replacing grep/find/cat

替代grep/find/cat

Shell command	tilth equivalent
`grep -rn "text" src/`	`tilth "text" --scope src/`
`grep -rnE "a\|b\|c" src/`	`tilth "/a\|b\|c/" --scope src/`
`grep -rni "text" src/`	`tilth "/text/i" --scope src/`
`find src/ -name "*.ts"`	`tilth "*.ts" --scope src/`
`cat src/foo.py`	`tilth src/foo.py`
`head -200 src/big.rs`	`tilth src/big.rs --section 1-200`

Shell命令	tilth等效命令
`grep -rn "text" src/`	`tilth "text" --scope src/`
`grep -rnE "a\|b\|c" src/`	`tilth "/a\|b\|c/" --scope src/`
`grep -rni "text" src/`	`tilth "/text/i" --scope src/`
`find src/ -name "*.ts"`	`tilth "*.ts" --scope src/`
`cat src/foo.py`	`tilth src/foo.py`
`head -200 src/big.rs`	`tilth src/big.rs --section 1-200`

Security

安全说明

tilth reads files directly, including dotfiles like

.env

. Most AI agents have built-in secret redaction — rely on those safeguards. If your agent doesn't auto-redact:

Never output
```
API_KEY
```
,
```
SECRET
```
,
```
PASSWORD
```
,
```
TOKEN
```
values verbatim
Redact with
```
<REDACTED>
```
and note the secret type only

tilth会直接读取文件，包括

.env

等隐藏文件。大多数AI Agent内置了敏感信息自动脱敏功能——依赖这些防护措施即可。如果你的Agent不支持自动脱敏：

切勿直接输出
```
API_KEY
```
、
```
SECRET
```
、
```
PASSWORD
```
、
```
TOKEN
```
等敏感值
使用
```
<REDACTED>
```
替代，并仅注明敏感信息类型

Pitfalls

注意事项

Classification surprises

分类意外情况

Numbers → content search, not symbol.
```
tilth 404
```
searches text.
Spaces → content search.
```
tilth "import { X }"
```
is content, not symbol.
Existing filenames → file read.
```
tilth README
```
reads the file.
Globs with spaces aren't globs.
```
tilth "my file.*"
```
is content search.
Dotfiles → file read.
```
tilth .env
```
reads
```
.env
```
if it exists.

数字 → 内容搜索，而非符号搜索。
```
tilth 404
```
会搜索文本内容。
含空格的查询 → 内容搜索。
```
tilth "import { X }"
```
属于内容搜索，而非符号搜索。
已存在的文件名 → 读取文件。
```
tilth README
```
会读取该文件。
含空格的通配符 不属于通配符查询。
```
tilth "my file.*"
```
属于内容搜索。
隐藏文件 → 读取文件。
```
tilth .env
```
会读取
```
.env
```
（若存在）。

Common mistakes

常见错误

Using
```
--full
```
on a 2000-line file when
```
--section
```
would suffice → wastes tokens.
Re-reading a file already shown in search output → wastes tokens.
Running
```
grep
```
in bash when
```
tilth
```
does the same with structure → wastes calls.
Not using
```
--budget
```
for quick lookups → unbounded output.
Using
```
--map
```
repeatedly → expensive, use once then search.

对2000行的大文件使用
```
--full
```
，而
```
--section
```
即可满足需求 → 浪费令牌。
重复读取已在搜索结果中显示的文件 → 浪费令牌。
当tilth可完成相同操作且提供结构化信息时，仍在bash中使用
```
grep
```
→ 浪费调用次数。
快速查询时未使用
```
--budget
```
→ 输出内容无限制。
重复使用
```
--map
```
→ 开销大，仅需运行一次后改用搜索。

Decision Tree

决策树

What do you need?
├── Understanding a symbol (function, class, variable)?
│   └── tilth <symbol> --scope <dir>
│       └── Follow ── calls ── footers for callees
├── Reading a file?
│   ├── Small/medium → tilth <path>              (auto full)
│   ├── Large file → tilth <path>                (auto outline)
│   │   └── Need specific lines → tilth <path> --section 45-89
│   └── Markdown section → tilth <path> --section "## Heading"
├── Searching for text/patterns?
│   ├── Literal → tilth "text" --scope <dir>
│   ├── Regex → tilth "/pattern/" --scope <dir>
│   └── Case-insensitive → tilth "/pattern/i" --scope <dir>
├── Finding files?
│   ├── By extension → tilth "*.test.ts" --scope src/
│   └── By path → tilth "src/**/*.rs" --scope .
└── First time in codebase?
    └── tilth --map --scope src/    (once, then search)

你需要完成什么操作？
├── 想要了解某个符号（函数、类、变量）？
│   └── 执行 tilth <symbol> --scope <dir>
│       └── 跟随 ── 调用关系 ── 脚注查看被调用函数
├── 想要读取文件？
│   ├── 小/中型文件 → 执行 tilth <path>              （自动输出完整内容）
│   ├── 大型文件 → 执行 tilth <path>                （自动输出大纲）
│   │   └── 需要查看特定行 → 执行 tilth <path> --section 45-89
│   └── 想要读取Markdown章节 → 执行 tilth <path> --section "## Heading"
├── 想要搜索文本/模式？
│   ├── 字面文本 → 执行 tilth "text" --scope <dir>
│   ├── 正则表达式 → 执行 tilth "/pattern/" --scope <dir>
│   └── 不区分大小写 → 执行 tilth "/pattern/i" --scope <dir>
├── 想要查找文件？
│   ├── 按扩展名查找 → 执行 tilth "*.test.ts" --scope src/
│   └── 按路径查找 → 执行 tilth "src/**/*.rs" --scope .
└── 首次进入代码库？
    └── 执行 tilth --map --scope src/    （仅运行一次，之后使用搜索）