Shared AI context cache for software teams. Reduces cold start — every developer after the first gets reduced token usage for files with AI summaries. Static summaries reduce cold-start cost; full savings require AI summaries to exist.
10 developers. Same files. Read by AI every day. Nobody shares what was learned. Monthly token budget exhausted in 10–15 days instead of 20–22.
- Static index —
teamcache indexparses every file in seconds with tree-sitter. No AI, no API key. Every file gets a structural summary immediately. - AI upgrade — When your AI tool reads a file, it calls
cache_summary()to store a richer understanding. That summary is shared with your whole team via git. - Reduced cold start — The next developer gets the AI summary instantly. They never read the raw file. Tokens saved.
Honest limitations
- The static index (built by
teamcache index) gives structural context only: file shapes, symbols, imports. It does not capture intent, patterns, or logic.- The AI tier requires that at least one developer has already read the file with a supported AI tool and had
cache_summary()called. New files and new repos start with static summaries only.- No external AI calls — teamcache itself never calls any AI API. The AI tool you are already using writes summaries back via
cache_summary(). However, the optional semantic search feature downloads an ~80 MB embedding model from HuggingFace on first use (disabled by default; enabled withpip install teamcache[all]).
# 1. Install
pip install teamcache
# 2. Go to your repo
cd your-repo
# 3. Initialize
teamcache init
# 4. Index the whole repo (seconds, no AI, no API key)
teamcache index
# 5. Register with your AI tool
teamcache install # Claude Code (default)
teamcache install --agent cursor # Cursor
teamcache install --agent codex # OpenAI Codex CLI
teamcache install --agent windsurf # Windsurf
teamcache install --agent aider # Aider
teamcache install --agent opencode # OpenCode
# 6. Commit the static index to share with your team
git add .teamcache/objects/
git commit -m "chore: add teamcache static index"
git pushThat's it. Your AI tool now calls get_file_context() before reading any file and cache_summary() after. Every teammate gets the benefit.
| Command | What it does |
|---|---|
teamcache init |
Initialize in the current git repo |
teamcache index |
Parse all files, build static summaries |
teamcache install [--agent NAME] |
Register MCP server with your AI tool |
teamcache serve |
Start the MCP stdio server (called by AI tool) |
teamcache changed [--since BRANCH] |
Re-index files changed since a branch |
teamcache sync |
Rebuild local index from committed objects |
teamcache invalidate [PATH|--stale|--all] |
Mark entries as needing refresh |
teamcache stats |
Show AI vs static coverage, top contributors |
teamcache report |
Write .teamcache/reports/YYYY-MM.md |
teamcache commit |
git add .teamcache/objects/ && git commit |
teamcache uninstall [--agent NAME] |
Remove MCP registration and instructions |
Your AI tool gets these tools via the MCP server:
| Tool | What it does |
|---|---|
repo_overview() |
Directory tree, languages, entry points, coverage |
get_file_context(path) |
Returns AI or static summary; tells AI what to do |
cache_summary(path, summary, lang) |
AI writes its understanding back into the cache |
find_relevant_files(task) |
Semantic + keyword search across all summaries |
get_symbols(path) |
Functions, classes, imports for a file |
find_by_symbol(name) |
Where is UserService defined? Line number included. |
get_changed_context(branch) |
What changed since main, which need AI re-read |
.teamcache/
objects/ ← git committed — shared with team
summaries/ ← AI and static summary objects (immutable JSON)
symbols/ ← tree-sitter symbol index objects
repomap.json ← cross-file import map
config.yaml ← schema_version: v1 (nothing else)
local/ ← gitignored — rebuilt locally
index.sqlite ← fast lookup index
embeddings.sqlite ← semantic search vectors
Cache key: sha256(sha256(file_bytes) + "|" + schema_version)
File changes → new key → old object ignored automatically.
Two-tier summaries:
static— tree-sitter parse, runs in milliseconds, no AI, available from day oneai— written by the AI tool after it reads a file, much richer, preferred when available
No external calls for core indexing. The AI tool already running writes summaries via cache_summary(). teamcache never calls any AI API. No API key. No separate cost. Semantic search (optional, disabled by default) downloads an ~80 MB embedding model from HuggingFace on first use.
Everything under .teamcache/objects/ is committed to your repository and shared with your team. This includes:
- Static summaries — structural snapshots of each file (symbols, imports, file shape), generated by
teamcache indexwith no AI involved. - AI summaries — richer descriptions written by your AI tool via
cache_summary()after it reads a file. These contain whatever the AI chose to write, which may include excerpts or paraphrases of your source code.
Because these objects are immutable and content-addressed, old summaries accumulate in git history even after the source files change. To audit what is stored:
# List all summary objects committed to the repo
git ls-files .teamcache/objects/summaries/
# Search summary content for a string (e.g. a token or hostname)
grep -r "search_term" .teamcache/objects/summaries/If you need to remove a summary from history entirely, use git filter-repo or BFG Repo-Cleaner — a normal git rm will not expunge it from older commits.
.github/workflows/teamcache-sync.yml is included — keeps static index fresh on every merge to main.
See .gitlab/teamcache-sync.yml. Include it in your pipeline:
include:
- local: .gitlab/teamcache-sync.yml- Python 3.10+
- Git
- No API key required at any point
Optional (installed automatically with pip install teamcache[all]):
tree-sitter— more accurate symbol extraction (falls back to regex without it)sentence-transformers— semantic search (falls back to keyword search without it); downloads an ~80 MB model from HuggingFace on first use
MIT