tlc-claude-code 2.6.0 → 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

@@ -113,24 +113,99 @@ After `resolveRouting` returns, immediately write `.tlc/.build-routing-active` w
 
 Use this mode only when `models[0]` is **NOT** `claude`.
 
-Claude does not execute the build instructions inline in this path. Claude acts as the orchestrator for the routed provider run:
-
-1. Read the full build plan and break the work into the smallest practical execution slices for Codex-style `exec` dispatches.
-2. For each slice, prepare the exact task context, success criteria, test target, and file scope before dispatch.
-3. Resolve orchestration modules with fallback: try `tlc-claude-code/server/lib/...` first, then `$PROJECT_DIR/server/lib/...`.
-4. Build the full prompt with `buildFullPrompt` from `orchestration/prompt-builder`.
-5. Dispatch through unified CLI routing with `dispatch` from `orchestration/cli-dispatch`.
-6. After each provider response, capture output for memory with `captureFromProvider` from `capture`.
-7. Verify every returned result:
-   - Confirm the requested change was actually made.
-   - Confirm tests relevant to that slice were run or explain why not.
-   - Reject incomplete, unverifiable, or off-plan output.
-8. Handle failures explicitly:
-   - If dispatch fails because of model mismatch, auth, or missing CLI, check `.tlc/.router-state.json` for the provider's actual available model and retry once with the corrected model.
-   - If retry still fails, stop and report the exact failure to the user. Do not silently fall back to Claude inline execution.
-   - If a dispatched task returns partial or broken work, issue a focused follow-up dispatch for the fix instead of continuing blindly.
-9. Continue dispatch/verify/fix until the routed provider work is complete and validated.
-10. When finished, display the provider output summary, persist captured memory, remove `.tlc/.build-routing-active`, and stop. Do **not** execute Inline Mode instructions afterward.
+Claude is the **project manager**. Claude reads the plan, breaks tasks into small prompts, and dispatches each to the tlc-core orchestrator. Claude does NOT write code.
+
+### Step O1: Read the Plan
+
+Read `.planning/phases/{N}-PLAN.md`. Extract each task's goal, files, acceptance criteria, and test cases.
+
+### Step O2: Check Orchestrator Health
+
+```bash
+curl -sf http://localhost:3100/health
+```
+
+If healthy, dispatch via orchestrator (Step O3). If unreachable, fall back to direct Codex dispatch via Bash (Step O3-fallback).
+
+### Step O3: Dispatch Tasks to Orchestrator
+
+For each independent task, dispatch via the orchestrator API:
+
+```bash
+curl -s -X POST http://localhost:3100/sessions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "project": "<project-name>",
+    "pool": "local-tmux",
+    "command": "<provider>",
+    "prompt": "<task prompt — one clear action, explicit file paths, under 500 words>"
+  }'
+```
+
+- `project`: the repo directory name under `/workspace/` (e.g., `Tools/TLC`)
+- `command`: the provider from routing result (e.g., `codex`)
+- `prompt`: small focused prompt for one task — include file paths, acceptance criteria, test command
+
+**Save each returned session ID** to `.tlc/.active-sessions.json`:
+
+```bash
+node -e "
+const fs = require('fs');
+const path = '.tlc/.active-sessions.json';
+const existing = fs.existsSync(path) ? JSON.parse(fs.readFileSync(path, 'utf8')) : [];
+existing.push({ sessionId: '<id>', taskName: '<task>', startedAt: new Date().toISOString() });
+fs.writeFileSync(path, JSON.stringify(existing, null, 2));
+"
+```
+
+### Step O3-fallback: Direct Dispatch (No Orchestrator)
+
+If orchestrator is down, dispatch directly via tmux on the host:
+
+```bash
+tmux new-session -d -s <task-id> -c $(pwd)
+tmux send-keys -t <task-id> "/opt/homebrew/bin/codex --full-auto '<prompt>'" Enter
+```
+
+### Step O4: Report and Free
+
+After dispatching all tasks, report:
+
+```
+Dispatched N tasks to orchestrator:
+  ses_abc123  Task 1: Create schema         codex  running
+  ses_def456  Task 2: Add validation         codex  running
+
+Run /tlc:status to check progress.
+I'm free — what would you like to work on?
+```
+
+**STOP HERE.** Do not write code. Do not execute inline mode. Claude is the PM, not the coder.
+
+### Step O5: Monitor (When User Asks)
+
+When the user asks for status or agents complete, check:
+
+```bash
+# Check all sessions
+curl -s http://localhost:3100/sessions | node -e "
+const d=require('fs').readFileSync('/dev/stdin','utf8');
+JSON.parse(d).forEach(s=>console.log(s.id, s.status, s.project));
+"
+
+# Check specific session output (inside container)
+docker exec tlc-agent-runner tmux capture-pane -t <session_id> -p -S -20
+```
+
+Auto-approve any prompts found in tmux sessions:
+
+```bash
+docker exec tlc-agent-runner tmux send-keys -t <session_id> Enter
+```
+
+### Step O6: Cleanup
+
+When all tasks complete, remove `.tlc/.build-routing-active` and report results.
 
 ## INLINE MODE
 
@@ -320,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

@@ -44,12 +44,56 @@ else
 fi
 
 # --- tlc-core Orchestrator ---
+# Kill switch: export TLC_CORE_AUTOSTART=false to disable auto-start
 TLC_CORE_PORT="${TLC_CORE_PORT:-3100}"
-if curl -sf --max-time 1 "http://localhost:${TLC_CORE_PORT}/health" > /dev/null 2>&1; then
+if [ "${TLC_CORE_AUTOSTART}" = "false" ]; then
+  echo "tlc-core orchestrator: auto-start disabled (TLC_CORE_AUTOSTART=false)"
+elif curl -sf --max-time 1 "http://localhost:${TLC_CORE_PORT}/health" > /dev/null 2>&1; then
   SESSIONS=$(curl -sf --max-time 1 "http://localhost:${TLC_CORE_PORT}/sessions" 2>/dev/null | jq "length" 2>/dev/null || echo "0")
   echo "tlc-core orchestrator: healthy (${SESSIONS} sessions)"
 else
-  echo "tlc-core orchestrator: not running. Agent dispatch will fall back to local mode."
+  # Try to auto-start if tlc-core CLI is available
+  if command -v tlc-core >/dev/null 2>&1; then
+    echo "tlc-core orchestrator: not running — starting..."
+    tlc-core start > /dev/null 2>&1 &
+    # Wait up to 15s for health
+    for i in 1 2 3 4 5; do
+      sleep 3
+      if curl -sf --max-time 1 "http://localhost:${TLC_CORE_PORT}/health" > /dev/null 2>&1; then
+        echo "tlc-core orchestrator: started successfully"
+        break
+      fi
+    done
+    if ! curl -sf --max-time 1 "http://localhost:${TLC_CORE_PORT}/health" > /dev/null 2>&1; then
+      echo "tlc-core orchestrator: failed to start. Run 'tlc-core start' manually."
+    fi
+  else
+    echo "tlc-core orchestrator: not installed. Run: git clone git@github.com:TwentyTwoLabs22/tlc-core.git && cd cli && npm install && npm link"
+  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 ─────────────────────────────

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.0",
+  "version": "2.7.0",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc-claude-code": "./bin/install.js",