cortexkit · nandanugg · Apr 16, 2026 · Apr 16, 2026 · Apr 16, 2026 · Apr 16, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,118 @@
+# AFT - Agent File Tools
+
+Tree-sitter powered code analysis for massive context savings (60-90% token reduction).
+
+## MANDATORY: Always Use AFT First
+
+**CRITICAL**: AFT semantic commands are the DEFAULT, not optional. Grep/Read with limited context (e.g., 3 lines) misses the bigger picture. We want to SEE the full picture, not shoot in the dark.
+
+**AFT applies to ALL file types** — not just code. Markdown, config, docs, JSON, YAML all benefit. Even for "just checking what files are" — outline first.
+
+**Before reading ANY files:**
+1. `aft outline` FIRST - understand structure before diving in
+2. `aft zoom` for symbols - never read full files when you need one function
+3. `aft callers`/`aft call_tree` for flow - grep misses cross-file relationships
+
+## AFT CLI Commands
+
+Use `aft` commands via Bash for code navigation. These provide structured output optimized for LLM consumption.
+
+### Semantic Commands (USE THESE BY DEFAULT)
+
+```bash
+# Get structure without content (~10% of full read tokens)
+aft outline <file|directory>
+
+# Inspect symbol with call-graph annotations
+aft zoom <file> <symbol>
+
+# Forward call graph - what does this function call?
+aft call_tree <file> <symbol>
+
+# Reverse call graph - who calls this function?
+aft callers <file> <symbol>
+
+# Impact analysis - what breaks if this changes?
+aft impact <file> <symbol>
+
+# Trace analysis - how does execution reach this?
+aft trace_to <file> <symbol>
+```
+
+### Basic Commands (fallback only)
+
+```bash
+aft read <file> [start_line] [limit]   # Read with line numbers
+aft grep <pattern> [path]              # Trigram-indexed search
+aft glob <pattern> [path]              # File pattern matching
+```
+
+## Decision Tree
+
+```
+Need to understand files?
+    |
+    +-- Don't know the file structure?
+    |       -> aft outline <dir>
+    |
+    +-- Checking what files contain (docs, config, etc.)?
+    |       -> aft outline <dir>, then selective reads
+    |
+    +-- Know the file, need specific symbol?
+    |       -> aft zoom <file> <symbol>
+    |
+    +-- Need to understand what calls what?
+    |       -> aft call_tree <file> <symbol>
+    |
+    +-- Need to find all usages?
+    |       -> aft callers <file> <symbol>
+    |
+    +-- Planning a change?
+    |       -> aft impact <file> <symbol>
+    |
+    +-- Debugging how execution reaches a point?
+            -> aft trace_to <file> <symbol>
+```
+
+## When to Use What
+
+| Task | Command | Token Savings |
+|------|---------|---------------|
+| Understanding file structure | `aft outline` | ~90% vs full read |
+| Checking what docs/configs contain | `aft outline` + selective read | ~80% vs read all |
+| Finding function definition | `aft zoom file symbol` | Exact code only |
+| Understanding dependencies | `aft call_tree` | Structured graph |
+| Finding usage sites | `aft callers` | All call sites |
+| Planning refactors | `aft impact` | Change propagation |
+| Debugging call paths | `aft trace_to` | Execution paths |
+
+## Rules (NOT suggestions)
+
+1. **ALWAYS start with outline** - Before reading ANY file, use `aft outline` to understand structure
+2. **ALWAYS zoom to symbols** - Never read full files when you need specific functions
+3. **ALWAYS use call graphs** - For understanding code flow, `call_tree` and `callers` reveal what grep cannot
+4. **ALWAYS impact before refactor** - Run `aft impact` before making changes to understand blast radius
+5. **NEVER grep with limited context** - If you need more than the symbol name, use AFT semantic commands
+6. **ALWAYS outline before sampling** - Even for "just checking what files are" tasks, outline first
+7. **ALWAYS outline before delegating** - When briefing a subagent to explore a repo or directory, run `aft outline <path>` yourself first and include the output in the subagent prompt. Never leave outline as a mid-step instruction — subagents don't follow ordering guarantees.
+
+## Context Protection
+
+**Context is finite.** Even when a user explicitly requests "contents" or "read all files":
+
+1. **Directory reads: outline first** - For directories with 5+ files, ALWAYS run `aft outline` and confirm which specific files are needed before reading
+2. **All file types benefit** - AFT applies to markdown, config, docs, and data files — not just code. Documentation directories especially benefit from outline-first
+3. **Batch limit** - Never read more than 3-5 files in a single action without confirming user intent. Context exhaustion breaks the conversation.
+4. **User requests don't override physics** - "Read all files" is a request, not a command to fill context. Propose `aft outline` + selective reads instead.
+
+## Supported Languages
+
+TypeScript, JavaScript, Python, Rust, Go, C/C++, Java, Ruby, Markdown
+
+## Hook Integration
+
+Grep and Glob tools are automatically routed through AFT via hooks for indexed performance.
+
+**Reading files**: Use `aft read` via Bash for indexed reads with token savings.
+
+**Warning**: When you need to Edit a file, use the native Read tool (not `aft read`) because Edit requires a prior Read tool call for validation.
diff --git a/README.md b/README.md
@@ -29,6 +29,39 @@
 
 ## Get Started
 
+### Claude Code
+
+Run the install script to set up AFT hooks for Claude Code:
+
+```bash
+./scripts/install-claude-hooks.sh
+```
+
+This installs:
+- **Tool interception** — Read, Grep, Glob tools route through AFT for indexed performance
+- **CLI wrapper** — `aft` command for semantic commands (outline, zoom, call_tree, callers, etc.)
+- **Instructions** — Claude learns when to use AFT commands for context savings
+
+After installation, restart Claude Code. Then use semantic commands via Bash:
+
+```bash
+aft outline src/              # File structure (~10% of full read tokens)
+aft zoom main.go main         # Inspect function with call graph
+aft callers api.ts handler    # Find all callers
+aft call_tree service.ts run  # What does run() call?
+```
+
+<details>
+<summary>Uninstall</summary>
+
+```bash
+./scripts/uninstall-claude-hooks.sh
+```
+</details>
+
+---
+
+
 ### OpenCode
 
 Run the setup wizard — it registers AFT in your OpenCode and TUI config and asks which experimental features to enable:
@@ -1013,7 +1046,7 @@ opencode-aft/
 
 ## Roadmap
 
-- MCP server for Claude Code, Cursor, and other MCP-compatible hosts
+- Cursor support via hooks
 - LSP integration for type-aware symbol resolution (partially implemented)
 - Streaming responses for large call trees
 - Watch mode for live outline updates

diff --git a/crates/aft/Cargo.toml b/crates/aft/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "agent-file-tools"
-version = "0.12.2"
+version = "0.13.0"
 edition = "2021"
 description = "Agent File Tools — tree-sitter powered code analysis for AI agents"
 license = "MIT"

diff --git a/packages/npm/darwin-arm64/package.json b/packages/npm/darwin-arm64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/aft-darwin-arm64",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "AFT binary for macOS ARM64 (Apple Silicon)",
   "os": [
     "darwin"

diff --git a/packages/npm/darwin-x64/package.json b/packages/npm/darwin-x64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/aft-darwin-x64",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "AFT binary for macOS x64 (Intel)",
   "os": [
     "darwin"

diff --git a/packages/npm/linux-arm64/package.json b/packages/npm/linux-arm64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/aft-linux-arm64",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "AFT binary for Linux ARM64",
   "os": [
     "linux"

diff --git a/packages/npm/linux-x64/package.json b/packages/npm/linux-x64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/aft-linux-x64",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "AFT binary for Linux x64",
   "os": [
     "linux"

diff --git a/packages/npm/win32-x64/package.json b/packages/npm/win32-x64/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/aft-win32-x64",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "AFT binary for Windows x64",
   "os": [
     "win32"

diff --git a/packages/opencode-plugin/package.json b/packages/opencode-plugin/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/aft-opencode",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "type": "module",
   "description": "OpenCode plugin for Agent File Tools (AFT) — tree-sitter and lsp powered code analysis",
   "main": "dist/index.js",
@@ -35,11 +35,11 @@
     "zod": "^4.1.8"
   },
   "optionalDependencies": {
-    "@cortexkit/aft-darwin-arm64": "0.12.2",
-    "@cortexkit/aft-darwin-x64": "0.12.2",
-    "@cortexkit/aft-linux-arm64": "0.12.2",
-    "@cortexkit/aft-linux-x64": "0.12.2",
-    "@cortexkit/aft-win32-x64": "0.12.2"
+    "@cortexkit/aft-darwin-arm64": "0.13.0",
+    "@cortexkit/aft-darwin-x64": "0.13.0",
+    "@cortexkit/aft-linux-arm64": "0.13.0",
+    "@cortexkit/aft-linux-x64": "0.13.0",
+    "@cortexkit/aft-win32-x64": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",