Context Engine for AI Agents
Stop fighting with AI tools that don't understand your codebase. Cappy builds a living knowledge graph of your project so AI agents actually know where things are and how they connect.
You're building with AI tools but:
- 🔄 Constantly copy-pasting code into ChatGPT for context
- 🤷 AI suggests changes in the wrong files
- 😤 Copilot doesn't understand how your modules relate
- ⏰ Spend more time explaining your codebase than coding
Why? LLMs are great at code patterns but terrible at understanding YOUR specific project structure.
Cappy creates two intelligent databases of your codebase:
-
🕸️ Knowledge Graph - Maps entities and relationships
(UserService → UserRepository → Database) -
🔍 Vector Database - Semantic search across code and docs
(Find "where we validate emails" instantly)
When you ask "add CPF validation like we do for email", Cappy knows:
- ✅ Where email validation lives
- ✅ Which files import it
- ✅ The pattern you use
- ✅ Where to put the new validation
Used internally to power autonomous development agents:
| Without Cappy | With Cappy |
|---|---|
| 30% success rate | 70% success rate |
| Generic suggestions | Context-aware solutions |
| Wrong file locations | Knows exact structure |
| Wastes expensive tokens | Efficient, targeted context |
1. 📂 Scans your workspace
↓
2. 🧩 Extracts entities (classes, functions, modules)
↓
3. 🔗 Maps relationships (imports, calls, dependencies)
↓
4. 💾 Builds Graph DB + Vector DB
↓
5. 🤖 AI tools access rich context via MCP
- Visualize your codebase structure
- See how components relate
- Click to navigate code
- Natural language queries
- Find by intent, not just keywords
- Search across code + docs
- MCP (Model Context Protocol) tools
- Enriched context for LLMs
- Automatic todo list generation
- Auto-chunks markdown with overlap
- Extracts entities from docs
- Links docs to code
- Watches file changes
- Incremental graph updates
- Always in sync
# From VSCode Marketplace
code --install-extension eduardocecon.cappyOr search "Cappy" in VSCode Extensions
// settings.json
{
"cappy.openaiApiKey": "sk-..."
}- Open your project in VSCode
- Press
Cmd+Shift+P(Mac) orCtrl+Shift+P(Windows/Linux) - Type "Cappy: Initialize Workspace"
- Cappy creates
.cappy/folder and adds.cappy/data/to.gitignore - Choose to start file processing or run "Cappy: Scan Workspace" later
💡 Note: Cappy only activates in workspaces where you explicitly initialize it. This prevents automatic folder creation in all your projects.
You: "Where do we validate user emails?"
Cappy: Found in src/validators/email.ts, used by UserService and AuthController
You: "Add CPF validation following the same pattern"
Cappy: [generates todo list with exact file locations and relationships]
Cmd+Shift+P → "Cappy: Show Graph"
Navigate your codebase visually - see imports, dependencies, call chains.
Cmd+Shift+P → "Cappy: Search Codebase"
Find code by what it DOES, not what it's named.
New dev? Ask Cappy "how does authentication work?" - get instant architecture overview with code links.
Running agents like OpenHands? Give them Cappy's context - watch success rates jump from 30% to 70%.
"What files will this change affect?" - Cappy shows the dependency graph.
Cappy keeps docs linked to code. Change a function? See which docs reference it.
"Where is this function called?" - instant answer with full context.
{
// Required
"cappy.openaiApiKey": "sk-...",
// Optional
"cappy.model": "gpt-4o-mini",
"cappy.chunkSize": 1000,
"cappy.chunkOverlap": 200,
"cappy.excludePatterns": ["node_modules", "dist", ".git"],
"cappy.graphDepth": 3
}┌─────────────────────────────────────────┐
│ VSCode Extension │
├─────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ File │─────▶│ Entity │ │
│ │ Watcher │ │ Extractor │ │
│ └──────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ Graph DB (Local) │ │
│ │ - Entities │ │
│ │ - Relationships │ │
│ └─────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ Vector DB (Local) │ │
│ │ - Code embeddings │ │
│ │ - Doc embeddings │ │
│ └─────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ MCP Server │ │
│ │ - Expose tools │ │
│ │ - Serve context │ │
│ └─────────────────────────┘ │
│ │
└─────────────────────────────────────────┘
│
▼
┌────────────────────┐
│ AI Agent / Chat │
└────────────────────┘
Key Design Decisions:
- Local-first: All data stays on your machine
- Incremental updates: Only processes changed files
- Multi-DB: Graph for structure, Vector for semantics
- MCP Standard: Works with any MCP-compatible AI tool
- Graph DB with entity extraction
- Vector DB with semantic search
- MCP server integration
- File watcher with incremental updates
- Chat interface with context
- Interactive graph visualization
- Multi-language support (currently optimized for JS/TS)
- Team sync (share graph across team)
- Cloud-hosted graphs (optional)
- Custom entity extractors
- Integration with Jira/Linear
- Analytics dashboard
- Pre-built patterns library
Q: Does my code leave my machine?
A: Only for LLM API calls (OpenAI). The databases are 100% local. You can use local LLMs if preferred.
Q: How big can my project be?
A: Tested on projects up to 500k LOC. Scan time scales linearly (~1 min per 50k LOC).
Q: Which languages are supported?
A: Currently optimized for JavaScript/TypeScript. Python, Go, Java support coming soon.
Q: Can I use this with Cursor/Copilot?
A: Yes! Cappy exposes MCP tools that any AI assistant can use.
Q: Is it free?
A: Extension is free. You pay only for your OpenAI API usage (~$0.01-0.10 per scan depending on project size).
Q: Can I run this on CI/CD?
A: Not yet, but planned. Would enable "graph as documentation" in your repo.
Using Cappy to power autonomous dev agents?
We offer a hosted agent service that uses Cappy's context engine to:
- Pick up tasks from Jira/Linear
- Develop, test, and open PRs
- 70%+ success rate on CRUD/integration tasks
Interested? Email: [seu-email@domain.com] or [link to landing page]
Contributions welcome! This is a passion project that solves a real problem.
- Language parsers (Python, Java, Go, Rust)
- Graph visualization improvements
- Documentation
- Test coverage
See CONTRIBUTING.md
- Extension: TypeScript + VSCode API
- Graph DB: [your choice - Neo4j? Custom?]
- Vector DB: [your choice - ChromaDB? LanceDB?]
- LLM: OpenAI GPT-4o-mini (configurable)
- MCP: Model Context Protocol for tool exposure
MIT - see LICENSE
Built by @cecon to stop copying code into ChatGPT 1000 times a day.
If Cappy saves you time, consider:
- ⭐ Starring the repo
- 🐛 Reporting bugs
- 💡 Suggesting features
- 🔀 Contributing code
Stop explaining your codebase. Let Cappy do it.