funcfinder AGENTS.md

funcfinder for AI Agents

Quick Reference: Map codebases, extract functions, trace calls, save 99% tokens.

---

Build First!

./build.sh   # Required before first use (~5 sec)

Builds 5 binaries: funcfinder, stat, deps, complexity, callgraph.

---

The Toolkit at a Glance

Tool	Purpose	Input
funcfinder	Map functions & types, extract bodies	file or dir
deps	Import dependencies + shard graph	dir
callgraph	Who calls whom	file or dir
stat	Call frequency & hotspots	file
complexity	Cognitive complexity per function	file

---

Investigation Workflow

Small project (< 50 files)

# 1. Orient — full map in one shot (~30ms)
funcfinder --dir . --all --json > map.json

# 2. Find the target
grep -i "auth" map.json
# → auth/handler.go:42: AuthenticateUser

# 3. Extract the body
funcfinder --inp auth/handler.go --source go --func AuthenticateUser --extract

# 4. Trace who it calls
callgraph --inp auth/handler.go -l go --func AuthenticateUser

# 5. Trace who calls it (impact)
callgraph --dir . -l go --reverse --func AuthenticateUser

Large project (50+ files)

# 1. Split into shards (one-time, ~100ms)
funcfinder --dir . --all --json --split

# 2. Read manifest — 2KB overview of entire codebase
cat .codemap/manifest.json
# → see shards, function counts, depends_on links

# 3. Load the relevant shard
cat .codemap/internal_auth.json

# 4. Extract the function
funcfinder --inp internal/auth.go --source go --func Authenticate --extract

# 5. Check call graph for impact
callgraph --dir . -l go --reverse --func Authenticate

Incremental update (repeat sessions)

funcfinder --dir . --all --json --split --inc
# INFO: Incremental: 1 shards changed, 32 unchanged

Full architecture index (once per project)

# Build shard map
funcfinder --dir . --all --json --split --no-gitignore

# Add inter-shard dependency graph to manifest
deps . -l go --shards --no-gitignore --update-manifest .codemap/manifest.json

# manifest.json now contains:
# {"path": "cmd_funcfinder.json", "depends_on": ["internal.json"], ...}