tlc-claude-code 2.6.1 → 2.7.0

package/.claude/commands/tlc/audit.md

@@ -22,7 +22,24 @@ Run a comprehensive audit of the codebase against TLC coding standards.
 /tlc:audit
 ```
 
-## Process
+## CodeDB Acceleration
+
+When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+Use the broadest CodeDB query that covers the audit pass before reading files manually.
+
+| Tool | Usage |
+|------|-------|
+| `codedb_tree` | Analyze folder structure, including file counts per folder and nesting depth. |
+| `codedb_search` | Scan for violation patterns such as hardcoded URLs `https?://`, magic strings, and `process.env` usage outside config. |
+| `codedb_symbol` | Check JSDoc coverage on exported functions before doing line-by-line review. |
+| `codedb_bundle` | Batch the audit checks into one call to reduce repeated repository scans. |
+
+Use CodeDB results to narrow any follow-up reads to the specific files or folders with likely violations.
+
+If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+## Process
 
 ### Step 1: Load Audit Module
 

package/.claude/commands/tlc/autofix.md

@@ -145,7 +145,23 @@ The existing autofix instructions below are the Inline Mode instructions and sho
 /tlc:autofix
 ```
 
-## Process
+## CodeDB Acceleration
+
+When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+Use CodeDB to narrow the failing area before opening files or proposing a fix.
+
+| Tool | Usage |
+|------|-------|
+| `codedb_symbol` | Find test function definitions quickly for the failing cases. |
+| `codedb_deps` | Trace imports and dependents of the broken module before editing. |
+| `codedb_hot` | Focus repair work on recently modified files that likely caused the failure. |
+
+Use these results to choose the smallest verified fix path before rerunning tests.
+
+If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+## Process
 
 ### Step 1: Run Tests
 

package/.claude/commands/tlc/build.md

@@ -395,6 +395,22 @@ This is the core TLC command. Tests before code, one task at a time.
 /tlc:build <phase_number> --agents 5        # Limit parallel agents to 5
 ```
 
+## CodeDB Acceleration
+
+When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+Use CodeDB to inspect nearby code and conventions before creating files or implementing the next step.
+
+| Tool | Usage |
+|------|-------|
+| `codedb_outline` | Inspect files adjacent to the task area for existing patterns, exports, and interfaces. |
+| `codedb_search` | Find similar implementations to follow as the reference path for new work. |
+| `codedb_tree` | Verify the target directory structure before creating or moving files. |
+
+Use these queries to keep new work aligned with surrounding modules and repository layout.
+
+If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
 ## Process
 
 ### Step 0: Create Phase Branch (Mandatory)

package/.claude/commands/tlc/coverage.md

@@ -138,6 +138,22 @@ The existing coverage instructions below are the Inline Mode instructions and sh
 - When joining a project to understand test gaps
 - After "vibe coding" a feature without tests
 
+## CodeDB Acceleration
+
+When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+Prefer a single batched pass to map source files, test files, and exported surfaces before deeper inspection.
+
+| Tool | Usage |
+|------|-------|
+| `codedb_tree` | Identify all source files and test files across the repository. |
+| `codedb_outline` | Find exported functions and signatures per file to compare against existing tests. |
+| `codedb_bundle` | Batch the tree and outline queries into one call for faster coverage mapping. |
+
+Use the returned file and symbol lists to focus manual review on untested or high-risk modules.
+
+If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
 ## Process
 
 ### 1. Detect Test Framework

package/.claude/commands/tlc/discuss.md

@@ -149,6 +149,21 @@ This command is not a blank-page brainstorming prompt. The agent should do the i
 
 If no phase number, auto-detect current phase from `.planning/ROADMAP.md`.
 
+## CodeDB Acceleration
+
+When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+Use structure and module outlines to ground the discussion in the code that the current phase actually touches.
+
+| Tool | Usage |
+|------|-------|
+| `codedb_outline` | Inspect modules relevant to the phase being discussed, including exports and interfaces. |
+| `codedb_tree` | Understand folder organization in the affected area before making recommendations. |
+
+Use CodeDB output to support tradeoff analysis and keep the discussion tied to concrete files.
+
+If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
 ## Process
 
 ### Step 1: Scan Context First

package/.claude/commands/tlc/init.md

@@ -166,6 +166,25 @@ After observability scaffolding, inspect the project's CI/CD posture:
    - Report: `"CI/CD OK"`
    - Include detected platform and workflow file paths in the summary
 
+### 6b. Register CodeDB MCP Server
+
+If `codedb` is installed (`command -v codedb`), create `.mcp.json` in the project root (if it doesn't already exist):
+
+```json
+{
+  "mcpServers": {
+    "codedb": {
+      "command": "codedb",
+      "args": ["mcp", "."]
+    }
+  }
+}
+```
+
+This gives Claude Code sub-millisecond code search, symbol lookup, and project tree — 1600x fewer tokens than grep/read.
+
+If `codedb` is not installed, skip silently (it's optional infrastructure from tlc-core).
+
 ### 7. If Tests Already Exist
 
 - Skip framework setup

package/.claude/commands/tlc/plan.md

@@ -173,6 +173,21 @@ The existing planning instructions below are the Inline Mode instructions and sh
 
 If no phase number, auto-detect current phase from ROADMAP.md.
 
+## CodeDB Acceleration
+
+When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+Start with structure and interface discovery before breaking work into tasks or estimating scope.
+
+| Tool | Usage |
+|------|-------|
+| `codedb_tree` | Understand the project structure before creating the task breakdown. |
+| `codedb_outline` | Inspect key modules for existing patterns, exports, and interfaces to follow. |
+
+Use the CodeDB snapshot to anchor the plan in the actual repository layout instead of assumptions.
+
+If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
 ## Process
 
 ### Step 1: Load Context

package/.claude/commands/tlc/preflight.md

@@ -15,6 +15,22 @@ It also runs:
 - After any multi-file change
 - Before recommending a commit or push
 
+## CodeDB Acceleration
+
+When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+Use dependency and recency data first so the completeness check covers the full blast radius of recent edits.
+
+| Tool | Usage |
+|------|-------|
+| `codedb_deps` | Find all files that import or otherwise reference the changed modules. |
+| `codedb_hot` | Identify recently changed files that should be treated as the primary focus area. |
+| `codedb_search` | Verify registration patterns such as command arrays, route tables, and exports. |
+
+Use the results to confirm registry updates, parallel-system changes, and downstream references before declaring done.
+
+If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
 ## Process
 
 ### Step 1: Inventory What Was Changed

package/.claude/commands/tlc/refactor.md

@@ -17,7 +17,23 @@ Same fixes as `/tlc:cleanup` but:
 /tlc:refactor
 ```
 
-## Process
+## CodeDB Acceleration
+
+When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+Use symbol, usage, and dependency lookups before editing so each refactor step accounts for its full impact.
+
+| Tool | Usage |
+|------|-------|
+| `codedb_symbol` | Find all definitions of the symbols being refactored. |
+| `codedb_word` | Find all usages of identifiers across the codebase before renaming or extracting them. |
+| `codedb_deps` | Trace the file-level impact of moves so imports and references stay consistent. |
+
+Use the CodeDB output to build safer preview steps and reduce missed follow-up edits.
+
+If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+## Process
 
 ### Step 1: Create or Resume Session
 

package/.claude/commands/tlc/review.md

@@ -174,6 +174,22 @@ TLC automatically uses ALL providers configured for the `review` capability in `
 /tlc:review --base dev   # Review vs different base branch
 ```
 
+## CodeDB Acceleration
+
+When CodeDB is available (`.mcp.json` has a `codedb` server), use these tools in the scan/search steps below. If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
+Run the security and change-impact queries early so the manual review starts from the highest-risk files.
+
+| Tool | Usage |
+|------|-------|
+| `codedb_search` | Scan for security patterns such as credentials, SQL injection, XSS, and `eval`. |
+| `codedb_deps` | Check whether changed files have unreviewed dependents elsewhere in the codebase. |
+| `codedb_hot` | Identify recently changed files that deserve extra review focus. |
+
+Use these results to prioritize findings, coverage checks, and any follow-up file reads.
+
+If CodeDB is unavailable, fall back to Grep/Glob/Read.
+
 ## Process
 
 ### Step 1: Load Router State (Persistent)

package/.claude/hooks/tlc-session-init.sh

@@ -72,6 +72,30 @@ else
   fi
 fi
 
+# ─── CodeDB (codebase awareness) ─────────────────────
+if command -v codedb >/dev/null 2>&1; then
+  if curl -sf --max-time 1 "http://localhost:7719/health" > /dev/null 2>&1; then
+    echo "codedb: running"
+  else
+    codedb serve "$PROJECT_DIR" > /dev/null 2>&1 &
+    echo "codedb: started indexing $PROJECT_DIR"
+  fi
+  # Ensure .mcp.json exists for Claude Code MCP discovery
+  if [ ! -f "$PROJECT_DIR/.mcp.json" ]; then
+    cat > "$PROJECT_DIR/.mcp.json" <<'MCPEOF'
+{
+  "mcpServers": {
+    "codedb": {
+      "command": "codedb",
+      "args": ["mcp", "."]
+    }
+  }
+}
+MCPEOF
+    echo "codedb: created .mcp.json"
+  fi
+fi
+
 # ─── Memory System Init ─────────────────────────────
 mkdir -p "$PROJECT_DIR/.tlc/memory/team/decisions" \
          "$PROJECT_DIR/.tlc/memory/team/gotchas" \

package/CLAUDE.md

@@ -11,6 +11,20 @@
 5. **No Co-Authored-By in commits.** The user is the author. Claude is a tool.
 6. **Ask before `git push`.** Never push without explicit approval.
 
+## CodeDB
+
+When `.mcp.json` contains a `codedb` server entry, prefer CodeDB MCP tools over built-in equivalents:
+
+| Prefer | Instead of | Use for |
+|--------|------------|---------|
+| `codedb_tree` | Glob | file/folder discovery |
+| `codedb_search` / `codedb_word` | Grep | text/identifier search |
+| `codedb_outline` | Read | understanding file structure (symbols, exports) |
+| `codedb_deps` | manual import tracing | reverse dependency analysis |
+| `codedb_bundle` | multiple separate calls | batch multiple queries into one call (up to 20 ops) |
+
+If CodeDB MCP tools are not available (no `.mcp.json` or server unreachable), fall back to built-in Grep/Glob/Read.
+
 ## Command Dispatch
 
 When the user says X → invoke `Skill(skill="tlc:...")`:

package/bin/install.js

@@ -190,6 +190,9 @@ function install(targetDir, installType) {
     success(`Installed settings template with hook wiring`);
   }
 
+  // Install CodeDB (codebase awareness — sub-ms code search, 1600x token reduction)
+  installCodedb();
+
   // Fix ownership if running under sudo
   if (isRunningAsSudo()) {
     const claudeDir = path.dirname(targetDir);
@@ -215,6 +218,69 @@ function install(targetDir, installType) {
   log('');
 }
 
+function installCodedb() {
+  const { execSync } = require('child_process');
+
+  // Check if already installed
+  try {
+    const version = execSync('codedb --version', { encoding: 'utf8', stdio: 'pipe' }).trim();
+    success(`CodeDB already installed: ${c.cyan}${version}${c.reset}`);
+    return;
+  } catch {
+    // Not installed — continue
+  }
+
+  log(`Installing ${c.cyan}CodeDB${c.reset} (codebase awareness)...`);
+
+  const platform = process.platform;
+  const arch = process.arch;
+
+  let asset;
+  if (platform === 'darwin' && arch === 'arm64') {
+    asset = 'codedb-darwin-arm64';
+  } else if (platform === 'linux' && arch === 'x64') {
+    asset = 'codedb-linux-x86_64';
+  } else {
+    log(`${c.yellow}CodeDB: no binary for ${platform}-${arch}. Skipping.${c.reset}`);
+    return;
+  }
+
+  const url = `https://github.com/justrach/codedb/releases/download/v0.2.4/${asset}`;
+
+  // Find writable bin directory
+  const binDirs = [
+    '/opt/homebrew/bin',
+    '/usr/local/bin',
+    path.join(process.env.HOME || '/root', '.local', 'bin'),
+  ];
+
+  let targetBin;
+  for (const dir of binDirs) {
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.accessSync(dir, fs.constants.W_OK);
+      targetBin = path.join(dir, 'codedb');
+      break;
+    } catch {
+      continue;
+    }
+  }
+
+  if (!targetBin) {
+    log(`${c.yellow}CodeDB: no writable bin directory found. Install manually: curl -fsSL https://codedb.codegraff.com/install.sh | sh${c.reset}`);
+    return;
+  }
+
+  try {
+    execSync(`curl -fsSL -o "${targetBin}" "${url}"`, { stdio: 'pipe' });
+    fs.chmodSync(targetBin, 0o755);
+    const version = execSync(`"${targetBin}" --version`, { encoding: 'utf8', stdio: 'pipe' }).trim();
+    success(`CodeDB installed: ${c.cyan}${version}${c.reset} at ${c.dim}${targetBin}${c.reset}`);
+  } catch (err) {
+    log(`${c.yellow}CodeDB: install failed (${err.message}). Install manually: curl -fsSL https://codedb.codegraff.com/install.sh | sh${c.reset}`);
+  }
+}
+
 function installHooks(targetDir, packageRoot) {
   // For local install: .claude/commands -> go up to .claude/hooks
   // For global install: ~/.claude/commands -> go up to ~/.claude/hooks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc-claude-code": "./bin/install.js",