Metadata-Version: 2.4
Name: teamcache
Version: 0.1.0
Summary: Shared AI context cache for software teams — eliminate the cold start
Project-URL: Homepage, https://github.com/teamcache/teamcache
Project-URL: Documentation, https://github.com/teamcache/teamcache#readme
Project-URL: Repository, https://github.com/teamcache/teamcache
Project-URL: Issues, https://github.com/teamcache/teamcache/issues
Author: TeamCache Contributors
License: MIT
License-File: LICENSE
Keywords: ai,cache,claude,context,developer-tools,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Provides-Extra: all
Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
Requires-Dist: tree-sitter-go>=0.21.0; extra == 'all'
Requires-Dist: tree-sitter-java>=0.21.0; extra == 'all'
Requires-Dist: tree-sitter-javascript>=0.21.0; extra == 'all'
Requires-Dist: tree-sitter-python>=0.21.0; extra == 'all'
Requires-Dist: tree-sitter-rust>=0.21.0; extra == 'all'
Requires-Dist: tree-sitter-typescript>=0.21.0; extra == 'all'
Requires-Dist: tree-sitter>=0.21.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == 'embeddings'
Provides-Extra: symbols
Requires-Dist: tree-sitter-go>=0.21.0; extra == 'symbols'
Requires-Dist: tree-sitter-java>=0.21.0; extra == 'symbols'
Requires-Dist: tree-sitter-javascript>=0.21.0; extra == 'symbols'
Requires-Dist: tree-sitter-python>=0.21.0; extra == 'symbols'
Requires-Dist: tree-sitter-rust>=0.21.0; extra == 'symbols'
Requires-Dist: tree-sitter-typescript>=0.21.0; extra == 'symbols'
Requires-Dist: tree-sitter>=0.21.0; extra == 'symbols'
Description-Content-Type: text/markdown

# TeamCache

Shared AI context cache for software teams. Eliminates the cold start — every developer after the first pays near-zero tokens for files that haven't changed.

## The problem

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.

## How it works

1. **Static index** — `teamcache index` parses every file in seconds with tree-sitter. No AI, no API key. Every file gets a structural summary immediately.
2. **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.
3. **No cold start** — The next developer gets the AI summary instantly. They never read the raw file. Tokens saved.

---

## Quickstart (under 10 steps)

```bash
# 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 push
```

That's it. Your AI tool now calls `get_file_context()` before reading any file and `cache_summary()` after. Every teammate gets the benefit.

---

## Commands

| 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 |

## MCP tools

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 |

## Architecture

```
.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 one
- `ai` — written by the AI tool after it reads a file, much richer, preferred when available

**No external calls from teamcache itself.** The AI tool already running writes summaries via `cache_summary()`. teamcache never calls any AI API. No API key. No separate cost.

## CI integration

### GitHub Actions

`.github/workflows/teamcache-sync.yml` is included — keeps static index fresh on every merge to main.

### GitLab CI

See `.gitlab/teamcache-sync.yml`. Include it in your pipeline:

```yaml
include:
  - local: .gitlab/teamcache-sync.yml
```

## Requirements

- 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)

## License

MIT
