Stop Coding in the Dark. Trace the DNA of your AI-Driven Projects.
The Three-Column Workspace: Prompt list → AI response → Code diff with line numbers
AI-assisted coding is fast, but it's a Black Box.
- The Amnesia Problem — Can't remember the prompt that fixed that complex bug 2 weeks ago?
- The Silo Problem — Great prompts in Cursor can't be reused in Trae or Claude Code.
- The Blackbox Problem — Looking at a git diff but forgot what instructions led to those changes?
OpenBBox is a universal side-car observer. It sniffs your local AI IDE logs and Git diffs to build a permanent, reusable DNA Sequence of your project — the complete lineage from intent to code.
"Don't just code with AI. Direct it. Trace it. Preserve it."
| Feature | Description |
|---|---|
| 🧬 Prompt Lineage | Every prompt captured as a clean, searchable "Genetic Code" — no chat noise |
| 📊 Evolution Mapping | See the "Cause" (Prompt) and "Effect" (Code Diff) in a unified timeline |
| 🔄 Multi-IDE Sync | One dashboard for Cursor, Trae, Claude Code, Antigravity, VS Code, Kiro, Windsurf, Codex |
| 💾 Asset Export | Export your "Director's Scripts" as Markdown or .pulse JSON for reuse |
| 🔒 Privacy First | 100% local. We sniff local logs. Your data never leaves your machine |
| 🌐 Bilingual UI | Full Chinese/English toggle with one click |
Imagine you built a secure auth module in Project A using Cursor. With OpenBBox, you don't just copy the code — you export the .pulse sequence, the exact prompt flow that guided the AI. Then you "replay" the logic in Project B using Trae.
That is true leverage. Code is the result. The lineage is the asset.
| # | Intent (The Prompt) | Evolution (The Code) | Impact |
|---|---|---|---|
| 01 | "Initialize FastAPI skeleton with WebSocket routing" | main.py created, connection pool established |
Foundation |
| 02 | "Add AES-256 encryption middleware for end-to-end security" | security.py with encrypt/decrypt hooks |
Security |
| 03 | "Refactor: move message storage from memory to async Redis" | db.py, config.py updated |
Performance |
| 04 | "Add JWT auth with refresh token rotation" | auth.py injected, 12 files updated |
Auth |
| 05 | "Write comprehensive test suite for auth flow" | tests/test_auth.py with 15 test cases |
Quality |
💡 Share the
.pulsefile and other developers can instantly see how you directed AI through these 5 architectural decisions.
| IDE | Type | Capture Method | Status |
|---|---|---|---|
| Cursor | Native AI IDE | SQLite + JSONL | ✅ Deep Support |
| VS Code | Plugin Ecosystem | Copilot Chat JSONL (incremental) + Extensions DB | ✅ Full Support |
| Trae | Native AI IDE | SQLite | ✅ Supported |
| Antigravity | Google Agent | Brain Artifact Tracking | ✅ Supported |
| Claude Code | CLI Agent | File Watch + PTY | ✅ Supported |
| Kiro | Native AI IDE (Amazon) | Agent Sessions JSON + Q Chat API Logs | ✅ Full Support |
| Cline / Roo Code | VS Code Extension | Extension Storage | ✅ Supported |
| Windsurf | Native AI IDE | SQLite | ✅ Supported |
| Codex | CLI | PTY | ✅ Supported |
| Claude Desktop | Cloud App | API | ☁️ Cloud |
Want to add a new IDE? See the Contributing Guide.
IDE Scanner: Auto-detects Cursor, VS Code, Trae, Codex and more on your machine
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/Chiody/openbbox/main/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/Chiody/openbbox/main/install.ps1 | iexgit clone https://github.com/Chiody/openbbox.git
cd openbbox
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
openbbox start
# Open http://localhost:9966git clone https://github.com/Chiody/openbbox.git
cd openbbox
docker compose up -d
# Open http://localhost:9966make install # Set up venv + install
make start # Start the server
make dev # Dev mode with auto-reload
make scan # One-time scan
make status # Show detected IDEs
make help # Show all commandsDue to the wide variety of operating systems, Python versions, and environment configurations, you may encounter setup issues. The fastest way to resolve them is to let your AI IDE or AI agent handle it.
Simply clone the repo, open it in your AI editor (Cursor, Kiro, VS Code with Copilot, Trae, etc.), and paste one of the following prompts:
Suggested Prompts
First-time setup:
I just cloned the OpenBBox project. Please read the README, install all
dependencies, resolve any environment issues (Python version, missing
packages, etc.), and start the server so I can open http://localhost:9966
If the server fails to start:
The OpenBBox server failed to start. Here is the error: [paste error].
Please diagnose the issue, fix it, and restart the server. The entry
point is `PYTHONPATH=. python3 cli/main.py start` and it should run
on port 9966.
If IDE detection is not working:
OpenBBox is running but it's not detecting my IDE conversations.
I use [Cursor/VS Code/Kiro/Trae/etc.]. Please check the adapter
configuration, verify the expected data paths exist on my system,
and run a manual scan to debug.
Full autopilot:
Read the entire OpenBBox project structure. Set up the Python
environment, install dependencies, start the server, open the
dashboard, trigger a scan of all my local AI IDEs, and report
what conversations were found.
💡 Why this works: OpenBBox is a pure Python project with minimal dependencies. Any modern AI coding assistant can read the codebase, understand the architecture, and fix environment-specific issues in seconds — much faster than manual debugging.
openbbox/
├── adapters/ # IDE-specific data readers (Cursor, Trae, Claude, VS Code...)
├── core/ # Engine: matching algorithm, data models, storage, export
├── server/ # FastAPI + WebSocket + REST API
├── cli/ # Click CLI with Rich output
├── protocol/ # OpenPulse JSON Schema specification
├── dashboard/ # Three-column SPA (zero build dependencies)
├── docs/ # Landing page + technical documentation
├── .github/ # Issue templates
├── Dockerfile # Container support
├── docker-compose.yml # One-command deployment
├── pyproject.toml # pip install support
├── Makefile # Developer shortcuts
├── install.sh # macOS/Linux one-line installer
└── install.ps1 # Windows one-line installer
💡 For the full directory breakdown, see CONTRIBUTING.md.
OpenBBox operates as a Shadow Observer — a side-car process that passively reads local IDE databases without modifying them.
IDE Logs (SQLite/JSONL) ──▶ Adapters ──▶ Temporal Matcher ──▶ PulseNodes ──▶ Dashboard
│
Score = α·(1/ΔT) + β·FileOverlap + γ·Keywords
- Sniff — Read-only access to IDE conversation databases
- Match — Pair prompts with Git diffs using weighted temporal alignment
- Store — Save structured PulseNodes to
~/.openbbox/openbbox.db - Visualize — Three-column dashboard with search, export, and real-time updates
📖 For the full algorithm breakdown, see Technical Architecture.
Kiro — 2-Layer Strategy (Agent Sessions + Q Chat API Logs)
| Layer | Source | Speed | What It Captures |
|---|---|---|---|
| workspace_sessions | kiro.kiroagent/workspace-sessions/{b64path}/sessions.json |
FAST | User prompts from session history; project path decoded from base64 directory name |
| workspace_db | workspaceStorage/{hash}/state.vscdb |
FAST | Fallback: chat/composer keys from VS Code-compatible SQLite |
Key insight: Kiro's session JSON only stores placeholder assistant responses ("On it."). The real AI responses live in Q Chat API.log files under ~/Library/Application Support/Kiro/logs/. OpenBBox parses these logs, extracts fullResponse and assistantResponseEvent content, and correlates them back to sessions via conversationId.
VS Code — 3-Layer Strategy (Workspace Chat + Global Chat + AI Extensions)
| Layer | Source | Speed | What It Captures |
|---|---|---|---|
| workspace_chat | workspaceStorage/{hash}/chatSessions/*.jsonl |
FAST | Copilot Chat conversations per project |
| global_chat | globalStorage/emptyWindowChatSessions/*.jsonl |
FAST | Conversations from windows without a workspace |
| ai_extensions | globalStorage/{ext-id}/ (Cline, Roo Code, Continue, Cody) |
MEDIUM | Third-party AI extension conversations |
Key insight: VS Code Copilot Chat uses an incremental JSONL format — kind=0 initializes the session state, kind=1 patches individual fields, kind=2 replaces entire arrays. OpenBBox reconstructs the full session by replaying these updates, then extracts markdownContent from the response objects.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/health |
Health check |
| GET | /api/adapters |
List IDEs with detection status |
| GET | /api/nodes |
List PulseNodes (paginated) |
| GET | /api/search?q= |
Search prompts by keyword |
| GET | /api/export/markdown |
Export as Markdown |
| GET | /api/export/json |
Export as .pulse JSON |
| WS | /ws |
Real-time node push |
Full interactive docs at http://localhost:9966/docs after starting the server.
- 100% Local — All data stored in
~/.openbbox/openbbox.dbon your machine - No Telemetry — Zero network calls, no analytics, no tracking
- Read-Only Sniffing — IDE databases opened with
?mode=roandPRAGMA query_only = ON - No IDE Modification — No plugins, no extensions, no code injection
- Your Data, Your Control — Delete
~/.openbbox/to remove everything
| Document | Description |
|---|---|
| Technical Architecture | Shadow Listener engine, Temporal Matching algorithm, data pipeline |
| Contributing Guide | How to add new IDE adapters, code style, PR process |
| OpenPulse Protocol | PulseNode JSON Schema, export formats, versioning |
OpenBBox is built for the community. Whether you use Cursor, Trae, or raw CLI, we need your help.
git clone https://github.com/Chiody/openbbox.git
cd openbbox && make install && source .venv/bin/activate
make dev # starts with auto-reloadSee CONTRIBUTING.md for the full guide.
- Core Python sniffer engine with multi-adapter architecture
- Temporal matching algorithm (Prompt → Git Diff)
- Three-column web dashboard with bilingual UI
- Multi-IDE support (Cursor, Trae, Claude Code, VS Code, Kiro, Windsurf, Codex)
- PTY terminal wrapper for CLI tools
- Asset export (Markdown / JSON / prompt list)
- Community "Pulse Hub" for sharing prompt sequences
- GitHub Actions integration for automated lineage tracking
- VS Code extension for in-editor lineage view
- Aider — Git monitoring patterns
- Continue — SQLite ChatHistory structure
- Asciinema — PTY terminal recording architecture
- python-unidiff — Unified diff parsing
Distributed under the MIT License. See LICENSE for details.
Built with ❤️ for the AI Director era.
Open the Box. Trace the Pulse.