🦴 codebone

Real-time codebase knowledge graph for your macOS menu bar.

Stop dumping dozens of files into your prompt. Let the dog sniff it. 🐾

📉 Why codebone?

AI assistants typically read 10–20 files just to understand your architecture — burning thousands of tokens on boilerplate before writing a single line of code.

codebone runs in your macOS menu bar, watches every file save, and delivers a live architectural snapshot directly to Claude, Cursor, or Gemini via MCP.

Related MCP server: mcp-code-indexer

🚀 Download & Install

⬇️ Download

Drag codebone.app to /Applications — done. A 🦴 appears in your menu bar.

Click it → Select Project Folder... to start your first scan.

💾 ~650 MB total (~390 MB model + ~260 MB venv). Requires macOS 13+ on Apple Silicon.

Homebrew:

brew tap palusc/codebone
brew install codebone

Build from source:

git clone https://github.com/palusc/codebone.git
cd codebone
./install.sh

🐾 How It Works

1. Sniff — Watches your repo on every Cmd + S with battery-aware debouncing.

2. Think — Apple Silicon Metal GPU extracts domains, models, routes, and events in < 1s.

3. Map — Builds a Semantic System Graph linking files by shared business logic — not just imports.

4. Serve — Streams precise architectural context to your AI via MCP or curl.

💬 Usage with AI Assistants

Prompt naturally:

"Implement authentication middleware for billing routes. Use codebone."

The model calls codebone_context() and receives the exact schemas, routes, and relationships it needs — no file dumping required.

codebone auto-registers during ./install.sh. For manual setup, add to claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "codebone": {
      "command": "npx",
      "args": ["-y", "codebone-mcp"]
    }
  }
}

That's it — no Python paths, no manual configuration.

{
  "mcpServers": {
    "codebone": {
      "command": "/Users/YOUR_USERNAME/Library/Application Support/codebone/venv/bin/python3",
      "args": ["-m", "codebone_mcp.server"],
      "env": { "CODEBONE_PORT": "8053" }
    }
  }
}

Replace YOUR_USERNAME with the output of whoami.

# codebone — Codebase Architecture
Project: /Users/you/my_project | Files: 142 | Updated: 2026-09-23

## Business Domains
- Authentication & Identity (12 files: auth/router.py, auth/jwt.py, models/user.py …)
- Payment & Billing (8 files: billing/stripe.py, billing/webhook.py, models/invoice.py …)
- Order Fulfillment (15 files: orders/service.py, events/order_created.py …)

## Focused query: codebone_context(domain="billing")
→ Returns only billing files, models (Invoice, Subscription),
  routes (POST /checkout/session), and events (InvoicePaid, PaymentFailed).

# Full architectural context
curl http://localhost:8053/codebone/context

# Filter by domain, file, or entity
curl 'http://localhost:8053/codebone/context?domain=billing'
curl 'http://localhost:8053/codebone/context?file=payments'
curl 'http://localhost:8053/codebone/context?query=InvoiceCreated'

🗺️ Live Graph UI

open http://localhost:8053/codebone/graph/ui

Interactive node-link diagram of your codebase. Dark glassmorphism theme, real-time search (/), click-to-inspect drawer, and live sync on every file save.

🧠 Brain Options

🦴 ➔ Settings ➔ Model to switch at any time.

🔄 Smart Scan Adoption

Renamed, moved, or branched your project? Never re-scan from scratch.

SHA-256 fingerprinting reuses unchanged files instantly. Only modified files are re-sniffed.

🦴 ➔ Adopt / Link Existing Scan...

🔒 Privacy & Security

• 100% Localhost — Binds to 127.0.0.1:8053 only. Zero cloud, zero telemetry.

• Prompt Injection Defense — Untrusted code is isolated with escaped XML wrappers and strict anti-jailbreak directives.

• Symlink Jail — Symlinks cannot escape the project root into sensitive system paths.

• Full Disk Access Helper — Pre-flight TCC check with 1-click System Settings shortcut.

• Battery-Aware — 0.5s debounce on AC, 15s on battery.

🗑️ Uninstall

Option A — Uninstaller App (recommended): Double-click Uninstall codebone.app → Clean All Data. Removes all processes, databases, models, logs, and MCP entries. Then drag codebone.app to the Trash.

Option B — Terminal:

./uninstall.sh           # full wipe
./uninstall.sh --keep-data  # keep databases & model for fast reinstall

Released under the MIT License.