Problem
codedb_remote depends on api.wiki.codes, which is frequently unreachable (Cloudflare 530 errors, rate limiting, timeouts). This makes the remote tool unreliable in practice, while the local tools (tree, outline, search, symbol, etc.) work great.
Suggested approach
Add a fallback chain when api.wiki.codes fails:
- Try remote first (current behavior)
- Check local cache:
~/.codedb/remote-cache/<repo-hash>/
- If exists and fresh (TTL), use the cached local index
- If missing or stale,
git clone --depth=1 + codedb index
- Query local index with the same action/params
Cache management
- TTL: auto-delete repos not accessed in ~7-30 days
- LRU: cap at N repos or max disk size (e.g. 2GB)
- Cleanup: run lazily on query or as a background task
- Manual:
codedb remote --clean-cache
Benefits
- Self-healing when the upstream is down
- Fast after first clone (cached locally)
- Shallow clones keep disk usage reasonable
- Works offline after initial clone
Trade-offs
- First query is slow (clone + index, 10-60s for large repos)
- Auth needed for private repos (GitHub token)
This would make codedb_remote genuinely robust instead of a single point of failure.
Problem
codedb_remotedepends onapi.wiki.codes, which is frequently unreachable (Cloudflare 530 errors, rate limiting, timeouts). This makes the remote tool unreliable in practice, while the local tools (tree, outline, search, symbol, etc.) work great.Suggested approach
Add a fallback chain when
api.wiki.codesfails:~/.codedb/remote-cache/<repo-hash>/git clone --depth=1+codedb indexCache management
codedb remote --clean-cacheBenefits
Trade-offs
This would make
codedb_remotegenuinely robust instead of a single point of failure.