loki-mode 6.66.0 → 6.67.0

package/autonomy/loki

@@ -37,6 +37,13 @@ log_error() { echo -e "${RED}[ERROR]${NC} $*"; }
 log_warn()  { echo -e "${YELLOW}[WARN]${NC} $*"; }
 log_debug() { echo -e "${CYAN}[DEBUG]${NC} $*"; }
 
+# Source TUI library if available (spinners, progress bars, tables, diffs)
+_LOKI_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "$_LOKI_SCRIPT_DIR/tui.sh" ]; then
+    # shellcheck source=tui.sh
+    source "$_LOKI_SCRIPT_DIR/tui.sh"
+fi
+
 # Resolve the script's real path (handles symlinks)
 resolve_script_path() {
     local script="$1"
@@ -421,6 +428,7 @@ show_help() {
     echo "  checkpoint|cp    Save/restore session checkpoints"
     echo "  projects         Multi-project registry management"
     echo "  audit [cmd]      Agent audit log and quality scanning (log|scan)"
+    echo "  heal <path>      Legacy system healing (archaeology, stabilize, modernize)"
     echo "  review [opts]    Standalone code review with quality gates (diff, staged, PR, files)"
     echo "  optimize         Optimize prompts based on session history"
     echo "  enterprise       Enterprise feature management (tokens, OIDC)"
@@ -442,6 +450,8 @@ show_help() {
     echo "  plan <PRD>       Dry-run PRD analysis: complexity, cost, and execution plan"
     echo "  ci [opts]        CI/CD quality gate integration (--pr, --report, --github-comment)"
     echo "  test [opts]      AI-powered test generation (--file, --dir, --changed, --dry-run)"
+    echo "  context [cmd]    Context window management (show|files|tools|add|clear)"
+    echo "  code [cmd]       Codebase intelligence (overview|symbols|deps|hotspots|diff)"
     echo "  report [opts]    Session report generator (--format text|markdown|html, --output)"
     echo "  share [opts]     Share session report as GitHub Gist (--private, --format)"
     echo "  version          Show version"
@@ -1700,13 +1710,40 @@ cmd_status() {
         echo -e "${CYAN}Pending Tasks:${NC} $task_count"
     fi
 
-    # Check budget
+    # Check budget with visual gauge
     if [ -f "$LOKI_DIR/metrics/budget.json" ]; then
         local budget_limit budget_used budget_remaining
         budget_limit=$(LOKI_BUDGET_FILE="$LOKI_DIR/metrics/budget.json" python3 -c "import json,os; d=json.load(open(os.environ['LOKI_BUDGET_FILE'])); print(d.get('budget_limit', 0))" 2>/dev/null || echo "0")
         budget_used=$(LOKI_BUDGET_FILE="$LOKI_DIR/metrics/budget.json" python3 -c "import json,os; d=json.load(open(os.environ['LOKI_BUDGET_FILE'])); print(round(d.get('budget_used', 0), 2))" 2>/dev/null || echo "0")
         if [ "$budget_limit" != "0" ]; then
             echo -e "${CYAN}Budget:${NC} \$$budget_used / \$$budget_limit"
+            # Show budget gauge if TUI is loaded
+            if type context_gauge &>/dev/null; then
+                local used_cents remaining_cents limit_cents
+                used_cents=$(echo "scale=0; $budget_used * 100" | bc 2>/dev/null || echo "0")
+                limit_cents=$(echo "scale=0; $budget_limit * 100" | bc 2>/dev/null || echo "100")
+                # Render as integer cents for the gauge
+                used_cents=${used_cents%.*}
+                limit_cents=${limit_cents%.*}
+                [ -z "$used_cents" ] && used_cents=0
+                [ -z "$limit_cents" ] && limit_cents=100
+                context_gauge "$used_cents" "$limit_cents" "Budget"
+            fi
+        else
+            echo -e "${CYAN}Cost:${NC} \$$budget_used (no limit)"
+        fi
+    fi
+
+    # Context window usage (token tracking)
+    if [ -f "$LOKI_DIR/state/context-usage.json" ]; then
+        local ctx_used ctx_total
+        ctx_total=$(python3 -c "import json; d=json.load(open('$LOKI_DIR/state/context-usage.json')); print(d.get('window_size', 200000))" 2>/dev/null || echo "200000")
+        ctx_used=$(python3 -c "import json; d=json.load(open('$LOKI_DIR/state/context-usage.json')); print(d.get('used_tokens', 0))" 2>/dev/null || echo "0")
+        if type context_gauge &>/dev/null; then
+            context_gauge "$ctx_used" "$ctx_total" "Context"
+        else
+            local ctx_pct=$((ctx_used * 100 / ctx_total))
+            echo -e "${CYAN}Context:${NC} ${ctx_pct}% (${ctx_used} / ${ctx_total} tokens)"
         fi
     fi
 
@@ -1718,6 +1755,10 @@ cmd_status() {
             echo -e "${CYAN}Dashboard:${NC} http://127.0.0.1:$port/"
         fi
     fi
+
+    echo ""
+    echo -e "${DIM}  Tip: loki context show   - detailed token breakdown${NC}"
+    echo -e "${DIM}  Tip: loki code overview   - codebase intelligence${NC}"
 }
 
 # JSON output for loki status --json
@@ -8600,6 +8641,418 @@ with open(manifest_path, 'w') as f:
     echo -e "View details: loki migrate --status ${migration_id}"
 }
 
+#===============================================================================
+# loki heal - Legacy System Healing (v6.67.0)
+# Inspired by Amazon AGI Lab's "How Agentic AI Helps Heal Systems We Can't Replace"
+# Modernize legacy codebases incrementally without breaking existing behavior.
+#===============================================================================
+
+cmd_heal_help() {
+    echo -e "${BOLD}loki heal${NC} - Legacy system healing (v6.67.0)"
+    echo ""
+    echo "Heal legacy codebases by understanding their real behaviors -- the quirks,"
+    echo "delays, error states, and invisible dependencies -- then modernizing"
+    echo "incrementally while preserving institutional logic."
+    echo ""
+    echo "Usage: loki heal <path-to-codebase> [options]"
+    echo ""
+    echo "Phases:"
+    echo "  archaeology    Extract knowledge, map dependencies, catalog friction"
+    echo "  stabilize      Add observability and tests without changing behavior"
+    echo "  isolate        Create adapter boundaries between components"
+    echo "  modernize      Replace components one at a time behind adapters"
+    echo "  validate       Verify behavioral equivalence with baseline"
+    echo ""
+    echo "Options:"
+    echo "  --phase PHASE        Start from specific phase (default: archaeology)"
+    echo "  --resume             Resume healing from last checkpoint"
+    echo "  --status             Show healing progress"
+    echo "  --report             Generate healing report"
+    echo "  --strict             Block ALL behavioral changes without approval"
+    echo "  --archaeology-only   Extract knowledge only, don't modify code"
+    echo "  --friction-map       Show friction map for target codebase"
+    echo "  --compliance PRESET  Compliance mode (healthcare|fintech|government)"
+    echo "  --provider NAME      AI provider (default: claude)"
+    echo "  --parallel N         Parallel healing agents (default: 1)"
+    echo "  --no-dashboard       Disable web dashboard"
+    echo "  --dry-run            Show healing plan without executing"
+    echo ""
+    echo "Environment Variables:"
+    echo "  LOKI_HEAL_MODE              Enable healing mode (auto-set by 'loki heal')"
+    echo "  LOKI_HEAL_PHASE             Override starting phase"
+    echo "  LOKI_HEAL_PRESERVE_FRICTION Warn before removing friction points (default: true)"
+    echo "  LOKI_HEAL_STRICT            Block all behavioral changes (default: false)"
+    echo ""
+    echo "Examples:"
+    echo "  loki heal ./legacy-app                        # Full healing pipeline"
+    echo "  loki heal ./legacy-app --phase archaeology     # Knowledge extraction only"
+    echo "  loki heal ./legacy-app --archaeology-only      # Extract without modifying"
+    echo "  loki heal ./legacy-app --resume                # Resume from checkpoint"
+    echo "  loki heal ./legacy-app --strict                # Strict behavioral preservation"
+    echo "  loki heal --status                             # Show healing progress"
+    echo "  loki heal --friction-map ./legacy-app          # View friction map"
+}
+
+cmd_heal() {
+    local codebase_path=""
+    local phase="${LOKI_HEAL_PHASE:-archaeology}"
+    local do_resume="false"
+    local do_status="false"
+    local do_report="false"
+    local do_friction_map="false"
+    local archaeology_only="false"
+    local strict="${LOKI_HEAL_STRICT:-false}"
+    local compliance=""
+    local provider="${LOKI_PROVIDER:-claude}"
+    local parallel="1"
+    local no_dashboard="false"
+    local dry_run="false"
+
+    if [ $# -eq 0 ]; then
+        cmd_heal_help
+        return 0
+    fi
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h)
+                cmd_heal_help
+                return 0
+                ;;
+            --status)
+                do_status="true"
+                shift
+                ;;
+            --report)
+                do_report="true"
+                shift
+                ;;
+            --friction-map)
+                do_friction_map="true"
+                shift
+                ;;
+            --phase)
+                if [[ -z "${2:-}" ]]; then
+                    echo -e "${RED}Error: --phase requires a value (archaeology|stabilize|isolate|modernize|validate)${NC}"
+                    return 1
+                fi
+                phase="$2"
+                shift 2
+                ;;
+            --phase=*)
+                phase="${1#*=}"
+                shift
+                ;;
+            --resume)
+                do_resume="true"
+                shift
+                ;;
+            --strict)
+                strict="true"
+                shift
+                ;;
+            --archaeology-only)
+                archaeology_only="true"
+                phase="archaeology"
+                shift
+                ;;
+            --compliance)
+                if [[ -z "${2:-}" ]]; then
+                    echo -e "${RED}Error: --compliance requires a value${NC}"
+                    return 1
+                fi
+                compliance="$2"
+                shift 2
+                ;;
+            --provider)
+                if [[ -z "${2:-}" ]]; then
+                    echo -e "${RED}Error: --provider requires a value${NC}"
+                    return 1
+                fi
+                provider="$2"
+                shift 2
+                ;;
+            --parallel)
+                if [[ -z "${2:-}" ]]; then
+                    echo -e "${RED}Error: --parallel requires a value${NC}"
+                    return 1
+                fi
+                parallel="$2"
+                shift 2
+                ;;
+            --no-dashboard)
+                no_dashboard="true"
+                shift
+                ;;
+            --dry-run)
+                dry_run="true"
+                shift
+                ;;
+            -*)
+                echo -e "${RED}Unknown option: $1${NC}"
+                echo "Run 'loki heal --help' for usage."
+                return 1
+                ;;
+            *)
+                if [ -z "$codebase_path" ]; then
+                    codebase_path="$1"
+                else
+                    echo -e "${RED}Error: Unexpected argument: $1${NC}"
+                    return 1
+                fi
+                shift
+                ;;
+        esac
+    done
+
+    # Route to subcommands
+    if [ "$do_status" = "true" ]; then
+        local heal_dir="${codebase_path:-.}/.loki/healing"
+        if [[ ! -d "$heal_dir" ]]; then
+            echo -e "${YELLOW}No healing session found.${NC}"
+            echo "Start one with: loki heal <path-to-codebase>"
+            return 0
+        fi
+        local progress_file="$heal_dir/healing-progress.json"
+        if [[ -f "$progress_file" ]]; then
+            echo -e "${BOLD}Healing Progress${NC}"
+            echo ""
+            python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    data = json.load(f)
+print(f\"  Codebase:       {data.get('codebase', '?')}\")
+print(f\"  Started:        {data.get('started', '?')}\")
+print(f\"  Overall Health:  {data.get('overall_health', 0):.0%}\")
+print()
+for c in data.get('components', []):
+    pct = c.get('characterization_passing', 0) / max(c.get('characterization_tests', 1), 1)
+    print(f\"  [{c.get('phase', '?'):12s}] {c.get('name', '?')}\")
+    print(f\"               Friction: {c.get('friction_resolved', 0)}/{c.get('friction_points', 0)} resolved\")
+    print(f\"               Tests:    {c.get('characterization_passing', 0)}/{c.get('characterization_tests', 0)} passing\")
+    print(f\"               Health:   {c.get('health_score', 0):.0%}\")
+    print()
+" "$progress_file" 2>/dev/null || echo "  Error reading progress file."
+        else
+            echo "  No progress data yet. Healing may still be in archaeology phase."
+        fi
+        return 0
+    fi
+
+    if [ "$do_friction_map" = "true" ]; then
+        local friction_file="${codebase_path:-.}/.loki/healing/friction-map.json"
+        if [[ ! -f "$friction_file" ]]; then
+            echo -e "${YELLOW}No friction map found.${NC}"
+            echo "Run archaeology first: loki heal ${codebase_path:-.} --phase archaeology"
+            return 0
+        fi
+        echo -e "${BOLD}Friction Map${NC}"
+        echo ""
+        python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    data = json.load(f)
+for f in data.get('frictions', []):
+    safe = 'YES' if f.get('safe_to_remove') else 'NO'
+    cls = f.get('classification', 'unknown')
+    print(f\"  [{f.get('id', '?')}] {f.get('location', '?')}\")
+    print(f\"    Behavior:       {f.get('behavior', '?')}\")
+    print(f\"    Classification: {cls}\")
+    print(f\"    Safe to remove: {safe}\")
+    if f.get('evidence'):
+        print(f\"    Evidence:       {f.get('evidence')}\")
+    print()
+" "$friction_file" 2>/dev/null || echo "  Error reading friction map."
+        return 0
+    fi
+
+    if [ "$do_report" = "true" ]; then
+        local heal_dir="${codebase_path:-.}/.loki/healing"
+        if [[ ! -d "$heal_dir" ]]; then
+            echo -e "${YELLOW}No healing session found.${NC}"
+            return 0
+        fi
+        echo -e "${BOLD}Healing Report${NC}"
+        echo ""
+        echo "  Friction map:               $(python3 -c "import json; print(len(json.load(open('$heal_dir/friction-map.json')).get('frictions', [])))" 2>/dev/null || echo '0') points"
+        echo "  Failure modes:              $(python3 -c "import json; print(len(json.load(open('$heal_dir/failure-modes.json')).get('modes', [])))" 2>/dev/null || echo '0') cataloged"
+        echo "  Institutional knowledge:    $(wc -l < "$heal_dir/institutional-knowledge.md" 2>/dev/null || echo '0') lines"
+        echo "  Characterization tests:     $(find "$heal_dir/characterization-tests/" -name "*.json" 2>/dev/null | wc -l | tr -d ' ') tests"
+        echo ""
+        return 0
+    fi
+
+    # Validate codebase path
+    if [ -z "$codebase_path" ]; then
+        echo -e "${RED}Error: Codebase path is required${NC}"
+        echo "Usage: loki heal <path-to-codebase> [options]"
+        return 1
+    fi
+
+    if [[ ! -d "$codebase_path" ]]; then
+        echo -e "${RED}Error: Directory not found: $codebase_path${NC}"
+        return 1
+    fi
+
+    # Validate phase
+    case "$phase" in
+        archaeology|stabilize|isolate|modernize|validate) ;;
+        *)
+            echo -e "${RED}Error: Invalid phase: $phase${NC}"
+            echo "Valid phases: archaeology, stabilize, isolate, modernize, validate"
+            return 1
+            ;;
+    esac
+
+    # Initialize healing directory
+    local heal_dir="$codebase_path/.loki/healing"
+    mkdir -p "$heal_dir"/{behavioral-baseline,characterization-tests}
+
+    # Initialize healing state files if they don't exist
+    [[ ! -f "$heal_dir/friction-map.json" ]] && echo '{"frictions":[]}' > "$heal_dir/friction-map.json"
+    [[ ! -f "$heal_dir/failure-modes.json" ]] && echo '{"modes":[]}' > "$heal_dir/failure-modes.json"
+    [[ ! -f "$heal_dir/institutional-knowledge.md" ]] && echo "# Institutional Knowledge Registry" > "$heal_dir/institutional-knowledge.md"
+
+    # Initialize or update healing progress
+    if [[ ! -f "$heal_dir/healing-progress.json" ]] || [ "$do_resume" != "true" ]; then
+        python3 -c "
+import json
+from datetime import datetime
+progress = {
+    'codebase': '$codebase_path',
+    'started': datetime.now().isoformat(),
+    'current_phase': '$phase',
+    'strict_mode': $( [ "$strict" = "true" ] && echo "True" || echo "False" ),
+    'components': [],
+    'overall_health': 0.0
+}
+with open('$heal_dir/healing-progress.json', 'w') as f:
+    json.dump(progress, f, indent=2)
+" || true
+    fi
+
+    emit_event healing cli start "phase=$phase" "codebase=$codebase_path" "strict=$strict" 2>/dev/null || true
+
+    echo -e "${BOLD}Legacy System Healing${NC}"
+    echo ""
+    echo -e "  Codebase:   $codebase_path"
+    echo -e "  Phase:      $phase"
+    echo -e "  Strict:     $strict"
+    echo -e "  Provider:   $provider"
+    if [ "$archaeology_only" = "true" ]; then
+        echo -e "  Mode:       archaeology-only (no modifications)"
+    fi
+    echo ""
+
+    if [ "$dry_run" = "true" ]; then
+        echo -e "${CYAN}Dry run: Showing healing plan without executing${NC}"
+        echo ""
+        echo "  Phase 1: Archaeology"
+        echo "    - Map dependency graph"
+        echo "    - Scan for friction points (sleeps, retries, magic values)"
+        echo "    - Extract institutional knowledge from comments"
+        echo "    - Write characterization tests for critical paths"
+        echo ""
+        echo "  Phase 2: Stabilize"
+        echo "    - Add logging/observability without behavior changes"
+        echo "    - Extract hardcoded config values"
+        echo "    - Add type annotations where possible"
+        echo ""
+        echo "  Phase 3: Isolate"
+        echo "    - Define component boundaries"
+        echo "    - Create adapter interfaces"
+        echo "    - Add integration tests at boundaries"
+        echo ""
+        echo "  Phase 4: Modernize"
+        echo "    - Replace components one at a time behind adapters"
+        echo "    - Verify characterization tests after each replacement"
+        echo ""
+        echo "  Phase 5: Validate"
+        echo "    - Compare outputs with pre-healing baseline"
+        echo "    - Generate healing report"
+        return 0
+    fi
+
+    # Build healing prompt for the AI provider
+    local heal_prompt="You are performing legacy system healing on the codebase at '${codebase_path}'.
+
+IMPORTANT: Read skills/healing.md for the full healing protocol.
+
+Current phase: ${phase}
+Strict mode: ${strict}
+Archaeology only: ${archaeology_only}
+
+HEALING RULES:
+1. FRICTION IS SEMANTICS: Before removing any 'quirky' code (sleeps, retries, magic values), verify it is not an undocumented business rule. Document all friction in .loki/healing/friction-map.json.
+2. LEARN THROUGH FAILURE: Deliberately probe error paths and edge cases. Catalog every failure mode in .loki/healing/failure-modes.json. Each failure teaches you about the system.
+3. CHARACTERIZE BEFORE MODIFYING: Write tests that capture CURRENT behavior (not intended behavior) before changing anything.
+4. PRESERVE INSTITUTIONAL LOGIC: Extract business rules from comments, git history, error messages, and test fixtures into .loki/healing/institutional-knowledge.md.
+5. INCREMENTAL ONLY: Change ONE component at a time. Verify ALL characterization tests pass after each change.
+
+Phase-specific instructions:
+- archaeology: Map dependencies, catalog friction, extract knowledge, write characterization tests. Do NOT modify source code.
+- stabilize: Add logging and observability. Extract config. Add type hints. Do NOT change behavior.
+- isolate: Create adapter interfaces at component boundaries. Add integration tests.
+- modernize: Replace components behind adapters. Verify characterization tests pass.
+- validate: Compare outputs with behavioral baseline. Generate healing report.
+
+$([ "$strict" = "true" ] && echo "STRICT MODE: You MUST NOT change any observable behavior without creating a .loki/signals/HUMAN_REVIEW_NEEDED signal and waiting for approval.")
+$([ "$archaeology_only" = "true" ] && echo "ARCHAEOLOGY ONLY: Do NOT modify any source files. Only create files in .loki/healing/.")
+
+Begin healing now. Follow the RARV cycle for each action."
+
+    # Execute with the appropriate provider
+    local heal_exit=0
+    case "$provider" in
+        claude)
+            local run_args=(--dangerously-skip-permissions -p "$heal_prompt" --output-format stream-json --verbose)
+            (cd "$codebase_path" && claude "${run_args[@]}" 2>&1) | \
+                while IFS= read -r line; do
+                    if echo "$line" | python3 -c "
+import sys, json
+try:
+    d = json.loads(sys.stdin.read())
+    if d.get('type') == 'assistant':
+        for item in d.get('message', {}).get('content', []):
+            if item.get('type') == 'text':
+                print(item.get('text', ''), end='')
+except Exception: pass
+" 2>/dev/null; then
+                        true
+                    fi
+                done && heal_exit=0 || heal_exit=$?
+            ;;
+        codex)
+            (cd "$codebase_path" && codex exec --full-auto "$heal_prompt" 2>&1) || heal_exit=$?
+            ;;
+        gemini)
+            (cd "$codebase_path" && gemini --approval-mode=yolo "$heal_prompt" 2>&1) || heal_exit=$?
+            ;;
+        cline)
+            (cd "$codebase_path" && cline -y "$heal_prompt" 2>&1) || heal_exit=$?
+            ;;
+        aider)
+            local aider_model="${LOKI_AIDER_MODEL:-claude-3.7-sonnet}"
+            local aider_flags="${LOKI_AIDER_FLAGS:-}"
+            # shellcheck disable=SC2086
+            (cd "$codebase_path" && aider --message "$heal_prompt" --yes-always --no-auto-commits --model "$aider_model" $aider_flags 2>&1) || heal_exit=$?
+            ;;
+    esac
+
+    emit_event healing cli complete "phase=$phase" "exit=$heal_exit" 2>/dev/null || true
+
+    if [ "$heal_exit" -eq 0 ]; then
+        echo ""
+        echo -e "${GREEN}Healing phase '${phase}' complete.${NC}"
+        echo -e "View progress: loki heal --status ${codebase_path}"
+        echo -e "View friction:  loki heal --friction-map ${codebase_path}"
+    else
+        echo ""
+        echo -e "${YELLOW}Healing phase '${phase}' finished with warnings (exit: $heal_exit).${NC}"
+        echo -e "Check: loki heal --status ${codebase_path}"
+    fi
+}
+
 cmd_migrate() {
     local codebase_path=""
     local target=""
@@ -10149,6 +10602,9 @@ main() {
         optimize)
             cmd_optimize "$@"
             ;;
+        heal)
+            cmd_heal "$@"
+            ;;
         migrate)
             cmd_migrate "$@"
             ;;
@@ -10203,6 +10659,12 @@ main() {
         share)
             cmd_share "$@"
             ;;
+        context|ctx)
+            cmd_context "$@"
+            ;;
+        code)
+            cmd_code "$@"
+            ;;
         version|--version|-v)
             cmd_version
             ;;
@@ -14949,6 +15411,561 @@ METRICS_SCRIPT
     fi
 }
 
+# Context window management (inspired by Kiro CLI /context command)
+# Shows token usage breakdown and context window utilization
+cmd_context() {
+    local subcommand="${1:-show}"
+    shift 2>/dev/null || true
+
+    case "$subcommand" in
+        --help|-h|help)
+            echo -e "${BOLD}loki context${NC} - Context window management"
+            echo ""
+            echo "Usage: loki context <subcommand>"
+            echo ""
+            echo "Subcommands:"
+            echo "  show       Show context window usage breakdown (default)"
+            echo "  files      List files currently in context with token estimates"
+            echo "  tools      Show tool token usage per origin (MCP, native)"
+            echo "  add        Add file to context (@file reference expansion)"
+            echo "  clear      Clear accumulated context (start fresh conversation)"
+            echo ""
+            echo "Examples:"
+            echo "  loki context                    # Show context usage"
+            echo "  loki context files              # List context files"
+            echo "  loki context tools              # Show tool token costs"
+            echo "  loki context add src/main.py    # Add file to context"
+            echo ""
+            echo "Inspired by: Kiro CLI /context command (kiro.dev)"
+            return 0
+            ;;
+        show)
+            _context_show "$@"
+            ;;
+        files)
+            _context_files "$@"
+            ;;
+        tools)
+            _context_tools "$@"
+            ;;
+        add)
+            _context_add "$@"
+            ;;
+        clear)
+            _context_clear "$@"
+            ;;
+        *)
+            echo -e "${RED}Unknown subcommand: $subcommand${NC}"
+            echo "Run 'loki context help' for usage."
+            return 1
+            ;;
+    esac
+}
+
+_context_show() {
+    local loki_dir="${LOKI_DIR:-.loki}"
+
+    if [ ! -d "$loki_dir" ]; then
+        echo -e "${YELLOW}No active session.${NC}"
+        return 0
+    fi
+
+    section_header "Context Window Usage" 2>/dev/null || echo -e "\n${BOLD}Context Window Usage${NC}"
+
+    # Read context tracker data if available
+    local ctx_file="$loki_dir/state/context-usage.json"
+    if [ -f "$ctx_file" ]; then
+        local total_tokens used_tokens input_tokens output_tokens cache_tokens
+        total_tokens=$(python3 -c "import json; d=json.load(open('$ctx_file')); print(d.get('window_size', 200000))" 2>/dev/null || echo "200000")
+        used_tokens=$(python3 -c "import json; d=json.load(open('$ctx_file')); print(d.get('used_tokens', 0))" 2>/dev/null || echo "0")
+        input_tokens=$(python3 -c "import json; d=json.load(open('$ctx_file')); print(d.get('input_tokens', 0))" 2>/dev/null || echo "0")
+        output_tokens=$(python3 -c "import json; d=json.load(open('$ctx_file')); print(d.get('output_tokens', 0))" 2>/dev/null || echo "0")
+        cache_tokens=$(python3 -c "import json; d=json.load(open('$ctx_file')); print(d.get('cache_read_tokens', 0))" 2>/dev/null || echo "0")
+
+        # Display gauge
+        if type context_gauge &>/dev/null; then
+            context_gauge "$used_tokens" "$total_tokens" "Window"
+        else
+            local pct=$((used_tokens * 100 / total_tokens))
+            echo -e "  ${CYAN}Context:${NC} ${pct}% used (${used_tokens} / ${total_tokens} tokens)"
+        fi
+        echo ""
+
+        # Breakdown
+        echo -e "  ${BOLD}Breakdown${NC} ${DIM}(estimated)${NC}"
+        echo -e "  ${DIM}Input tokens:${NC}  $(printf '%8s' "$input_tokens")"
+        echo -e "  ${DIM}Output tokens:${NC} $(printf '%8s' "$output_tokens")"
+        echo -e "  ${DIM}Cache reads:${NC}   $(printf '%8s' "$cache_tokens")"
+    else
+        echo -e "  ${DIM}No context tracking data yet.${NC}"
+        echo -e "  ${DIM}Context usage is tracked during active sessions.${NC}"
+    fi
+
+    # Show token costs if budget file exists
+    local budget_file="$loki_dir/metrics/budget.json"
+    if [ -f "$budget_file" ]; then
+        echo ""
+        echo -e "  ${BOLD}Cost${NC}"
+        local budget_used budget_limit
+        budget_used=$(python3 -c "import json; d=json.load(open('$budget_file')); print(round(d.get('budget_used', 0), 4))" 2>/dev/null || echo "0")
+        budget_limit=$(python3 -c "import json; d=json.load(open('$budget_file')); print(d.get('budget_limit', 0))" 2>/dev/null || echo "0")
+
+        if [ "$budget_limit" != "0" ]; then
+            echo -e "  ${DIM}Spent:${NC}     \$${budget_used} / \$${budget_limit}"
+            local remaining
+            remaining=$(echo "scale=4; $budget_limit - $budget_used" | bc 2>/dev/null || echo "0")
+            echo -e "  ${DIM}Remaining:${NC} \$${remaining}"
+        else
+            echo -e "  ${DIM}Spent:${NC} \$${budget_used} (no budget limit set)"
+        fi
+    fi
+    echo ""
+}
+
+_context_files() {
+    local loki_dir="${LOKI_DIR:-.loki}"
+    local ctx_files="$loki_dir/state/context-files.json"
+
+    section_header "Context Files" 2>/dev/null || echo -e "\n${BOLD}Context Files${NC}"
+
+    if [ -f "$ctx_files" ]; then
+        python3 << 'PYEOF'
+import json, os
+
+ctx_file = os.environ.get("LOKI_DIR", ".loki") + "/state/context-files.json"
+try:
+    with open(ctx_file) as f:
+        files = json.load(f)
+    total = 0
+    for entry in files:
+        name = entry.get("path", "unknown")
+        tokens = entry.get("estimated_tokens", 0)
+        total += tokens
+        print(f"  {tokens:>8} tokens  {name}")
+    print(f"\n  {'Total:':>8}  {total} tokens")
+except Exception:
+    print("  No context files tracked yet.")
+PYEOF
+    else
+        echo -e "  ${DIM}No context files tracked.${NC}"
+        echo ""
+        echo "  Add files with: loki context add <file>"
+        echo "  Or use @path syntax in your prompt:"
+        echo "    @src/main.py    - inject file contents"
+        echo "    @src/           - inject directory tree"
+    fi
+    echo ""
+}
+
+_context_tools() {
+    local loki_dir="${LOKI_DIR:-.loki}"
+
+    section_header "Tool Token Usage" 2>/dev/null || echo -e "\n${BOLD}Tool Token Usage${NC}"
+
+    # Read MCP config and estimate tool token usage
+    local mcp_config="$loki_dir/mcp/config.json"
+    if [ -f "$mcp_config" ]; then
+        python3 << 'PYEOF'
+import json, os
+
+config_file = os.environ.get("LOKI_DIR", ".loki") + "/mcp/config.json"
+try:
+    with open(config_file) as f:
+        config = json.load(f)
+    servers = config.get("mcpServers", {})
+    total = 0
+    for name, server in servers.items():
+        tools = server.get("tools", [])
+        # Estimate ~500 tokens per tool definition
+        est = len(tools) * 500 if tools else 500
+        total += est
+        print(f"  {est:>6} tokens  {name} ({len(tools) if tools else '?'} tools)")
+    print(f"\n  Total MCP tool overhead: ~{total} tokens per request")
+except Exception:
+    print("  No MCP servers configured.")
+PYEOF
+    else
+        echo -e "  ${DIM}Native tools only (no MCP servers configured).${NC}"
+    fi
+
+    echo ""
+    echo -e "  ${DIM}Native tools: ~2000 tokens (bash, read, write, glob, grep)${NC}"
+    echo -e "  ${DIM}Tip: Large MCP tool descriptions impact performance.${NC}"
+    echo ""
+}
+
+_context_add() {
+    local file_path="$1"
+    if [ -z "$file_path" ]; then
+        echo -e "${RED}Usage: loki context add <file-or-dir>${NC}"
+        echo ""
+        echo "Adds a file's content (or directory tree) to the context."
+        echo "Equivalent to @path inline reference syntax."
+        return 1
+    fi
+
+    # Strip @ prefix if user types it
+    file_path="${file_path#@}"
+
+    if [ -d "$file_path" ]; then
+        echo -e "${BOLD}Directory tree: ${file_path}${NC}"
+        echo ""
+        if type tree_display &>/dev/null; then
+            tree_display "$file_path"
+        else
+            find "$file_path" -maxdepth 3 -not -path '*/\.*' | head -50
+        fi
+        echo ""
+
+        # Count files and estimate tokens
+        local file_count
+        file_count=$(find "$file_path" -type f -not -path '*/\.*' | wc -l)
+        echo -e "${DIM}$file_count files in directory${NC}"
+    elif [ -f "$file_path" ]; then
+        local size
+        size=$(wc -c < "$file_path")
+        # Rough estimate: 1 token per 4 bytes
+        local est_tokens=$((size / 4))
+        local lines
+        lines=$(wc -l < "$file_path")
+
+        echo -e "${BOLD}File: ${file_path}${NC}"
+        echo -e "  ${DIM}Size:${NC}    $size bytes"
+        echo -e "  ${DIM}Lines:${NC}   $lines"
+        echo -e "  ${DIM}Tokens:${NC}  ~$est_tokens (estimated)"
+
+        # Store in context files list
+        local loki_dir="${LOKI_DIR:-.loki}"
+        mkdir -p "$loki_dir/state"
+        local ctx_files="$loki_dir/state/context-files.json"
+        python3 -c "
+import json, os
+path = '$file_path'
+tokens = $est_tokens
+ctx_file = '$ctx_files'
+try:
+    with open(ctx_file) as f:
+        files = json.load(f)
+except:
+    files = []
+# Avoid duplicates
+files = [f for f in files if f.get('path') != path]
+files.append({'path': path, 'estimated_tokens': tokens, 'size': $size, 'lines': $lines})
+with open(ctx_file, 'w') as f:
+    json.dump(files, f, indent=2)
+" 2>/dev/null
+
+        echo -e "  ${GREEN}Added to context.${NC}"
+    else
+        echo -e "${RED}Not found: $file_path${NC}"
+        return 1
+    fi
+}
+
+_context_clear() {
+    local loki_dir="${LOKI_DIR:-.loki}"
+    rm -f "$loki_dir/state/context-files.json"
+    rm -f "$loki_dir/state/context-usage.json"
+    echo -e "${GREEN}Context cleared.${NC}"
+    echo -e "${DIM}A new conversation will start fresh.${NC}"
+}
+
+# Codebase intelligence (inspired by Kiro CLI /code command)
+# Provides workspace overview, symbol search, and pattern matching
+cmd_code() {
+    local subcommand="${1:-help}"
+    shift 2>/dev/null || true
+
+    case "$subcommand" in
+        --help|-h|help)
+            echo -e "${BOLD}loki code${NC} - Codebase intelligence"
+            echo ""
+            echo "Usage: loki code <subcommand>"
+            echo ""
+            echo "Subcommands:"
+            echo "  overview    Generate workspace overview (file types, LOC, structure)"
+            echo "  symbols     Search for symbols (functions, classes, variables)"
+            echo "  deps        Show dependency graph for a file or module"
+            echo "  hotspots    Find code hotspots (most-changed files, complexity)"
+            echo "  diff        Show colored diff of recent changes"
+            echo ""
+            echo "Examples:"
+            echo "  loki code overview                  # Full codebase overview"
+            echo "  loki code overview --silent          # Compact output"
+            echo "  loki code symbols 'class.*Service'   # Find service classes"
+            echo "  loki code deps src/main.py           # Show dependencies"
+            echo "  loki code hotspots --top 10          # Top 10 changed files"
+            echo "  loki code diff                       # Colored diff of uncommitted changes"
+            echo ""
+            echo "Inspired by: Kiro CLI /code command (kiro.dev)"
+            return 0
+            ;;
+        overview)
+            _code_overview "$@"
+            ;;
+        symbols)
+            _code_symbols "$@"
+            ;;
+        deps)
+            _code_deps "$@"
+            ;;
+        hotspots)
+            _code_hotspots "$@"
+            ;;
+        diff)
+            _code_diff "$@"
+            ;;
+        *)
+            echo -e "${RED}Unknown subcommand: $subcommand${NC}"
+            echo "Run 'loki code help' for usage."
+            return 1
+            ;;
+    esac
+}
+
+_code_overview() {
+    local silent=false
+    local target_dir="."
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --silent|-s) silent=true; shift ;;
+            *) target_dir="$1"; shift ;;
+        esac
+    done
+
+    if $silent; then
+        echo -e "${BOLD}$(basename "$(cd "$target_dir" && pwd)")${NC}"
+    else
+        section_header "Codebase Overview: $(basename "$(cd "$target_dir" && pwd)")" 2>/dev/null || echo -e "\n${BOLD}Codebase Overview${NC}"
+    fi
+
+    # Language breakdown
+    python3 << PYEOF
+import os, collections, sys
+
+target = "$target_dir"
+silent = $( $silent && echo "True" || echo "False" )
+
+# File extension to language mapping
+EXT_MAP = {
+    '.py': 'Python', '.js': 'JavaScript', '.ts': 'TypeScript', '.tsx': 'TypeScript',
+    '.jsx': 'JavaScript', '.go': 'Go', '.rs': 'Rust', '.java': 'Java',
+    '.rb': 'Ruby', '.php': 'PHP', '.c': 'C', '.cpp': 'C++', '.h': 'C/C++ Header',
+    '.cs': 'C#', '.swift': 'Swift', '.kt': 'Kotlin', '.scala': 'Scala',
+    '.sh': 'Shell', '.bash': 'Shell', '.zsh': 'Shell',
+    '.html': 'HTML', '.css': 'CSS', '.scss': 'SCSS', '.vue': 'Vue',
+    '.md': 'Markdown', '.json': 'JSON', '.yaml': 'YAML', '.yml': 'YAML',
+    '.toml': 'TOML', '.xml': 'XML', '.sql': 'SQL',
+    '.dockerfile': 'Docker', '.tf': 'Terraform', '.proto': 'Protobuf',
+}
+
+SKIP_DIRS = {'.git', 'node_modules', '.loki', '__pycache__', '.venv', 'venv',
+             'dist', 'build', '.next', 'target', '.tox', '.mypy_cache',
+             'vendor', '.cargo', 'coverage', '.pytest_cache'}
+
+lang_files = collections.Counter()
+lang_lines = collections.Counter()
+total_files = 0
+total_lines = 0
+dir_count = 0
+
+for root, dirs, files in os.walk(target):
+    # Skip hidden and build directories
+    dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith('.')]
+    dir_count += 1
+    for f in files:
+        ext = os.path.splitext(f)[1].lower()
+        if ext in EXT_MAP:
+            lang = EXT_MAP[ext]
+            lang_files[lang] += 1
+            total_files += 1
+            try:
+                fp = os.path.join(root, f)
+                lines = sum(1 for _ in open(fp, 'rb'))
+                lang_lines[lang] += lines
+                total_lines += lines
+            except:
+                pass
+
+if not silent:
+    print(f"\n  Files: {total_files}  Lines: {total_lines:,}  Dirs: {dir_count}")
+    print()
+
+# Language table
+print("  Language         Files   Lines     %")
+print("  " + "-" * 40)
+for lang, count in lang_lines.most_common(15):
+    pct = (count / total_lines * 100) if total_lines > 0 else 0
+    files = lang_files[lang]
+    bar_len = int(pct / 5)
+    bar = "=" * bar_len
+    print(f"  {lang:<16} {files:>5}  {count:>7,}  {pct:>4.1f}% {bar}")
+
+if not silent:
+    # Show directory structure (top-level)
+    print()
+    print("  Top-level structure:")
+    entries = sorted(os.listdir(target))
+    for entry in entries:
+        if entry.startswith('.') and entry not in ('.github',):
+            continue
+        full = os.path.join(target, entry)
+        if os.path.isdir(full) and entry not in SKIP_DIRS:
+            subcount = sum(1 for _, _, fs in os.walk(full) for f in fs)
+            print(f"    {entry + '/':30s} ({subcount} files)")
+        elif os.path.isfile(full):
+            size = os.path.getsize(full)
+            if size > 1024:
+                print(f"    {entry:30s} ({size // 1024}KB)")
+PYEOF
+    echo ""
+}
+
+_code_symbols() {
+    local pattern="${1:-.}"
+    local file_type="${2:-}"
+
+    section_header "Symbol Search: $pattern" 2>/dev/null || echo -e "\n${BOLD}Symbol Search${NC}"
+
+    # Search for function/class definitions using ripgrep or grep
+    local search_patterns=(
+        "^(def|function|func|fn|pub fn|async def|class|interface|struct|enum|type|export (const|function|class|interface))\s+.*${pattern}"
+    )
+
+    if command -v rg &>/dev/null; then
+        rg -n --no-heading -e "^(def |function |func |fn |pub fn |async def |class |interface |struct |enum |type |export (const|function|class|interface) ).*${pattern}" \
+            --type-add 'code:*.{py,js,ts,tsx,go,rs,java,rb,php,c,cpp,h,cs,swift,kt}' \
+            -t code \
+            --glob '!node_modules' --glob '!.git' --glob '!dist' --glob '!build' \
+            . 2>/dev/null | head -50
+    else
+        grep -rn "^\(def\|function\|func\|fn\|class\|interface\|struct\|enum\|type\).*${pattern}" \
+            --include='*.py' --include='*.js' --include='*.ts' --include='*.go' \
+            --include='*.rs' --include='*.java' --include='*.rb' \
+            --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist \
+            . 2>/dev/null | head -50
+    fi
+    echo ""
+}
+
+_code_deps() {
+    local target_file="$1"
+    if [ -z "$target_file" ]; then
+        echo -e "${RED}Usage: loki code deps <file>${NC}"
+        return 1
+    fi
+
+    section_header "Dependencies: $target_file" 2>/dev/null || echo -e "\n${BOLD}Dependencies${NC}"
+
+    if [ ! -f "$target_file" ]; then
+        echo -e "${RED}File not found: $target_file${NC}"
+        return 1
+    fi
+
+    local ext="${target_file##*.}"
+    echo -e "  ${BOLD}Imports/Requires:${NC}"
+
+    case "$ext" in
+        py)
+            grep -n "^import\|^from.*import" "$target_file" 2>/dev/null | sed 's/^/  /'
+            ;;
+        js|ts|tsx|jsx)
+            grep -n "import\|require(" "$target_file" 2>/dev/null | sed 's/^/  /'
+            ;;
+        go)
+            grep -n "\"" "$target_file" 2>/dev/null | grep -v "//" | sed 's/^/  /'
+            ;;
+        rs)
+            grep -n "^use\|^extern crate" "$target_file" 2>/dev/null | sed 's/^/  /'
+            ;;
+        java)
+            grep -n "^import" "$target_file" 2>/dev/null | sed 's/^/  /'
+            ;;
+        rb)
+            grep -n "^require\|^require_relative" "$target_file" 2>/dev/null | sed 's/^/  /'
+            ;;
+        *)
+            echo -e "  ${DIM}Unsupported file type: .$ext${NC}"
+            ;;
+    esac
+
+    echo ""
+    echo -e "  ${BOLD}Referenced by:${NC}"
+    local basename_file
+    basename_file=$(basename "$target_file" ".$ext")
+    if command -v rg &>/dev/null; then
+        rg -l "$basename_file" --glob '!node_modules' --glob '!.git' --glob '!dist' . 2>/dev/null | \
+            grep -v "^${target_file}$" | head -20 | sed 's/^/  /'
+    else
+        grep -rl "$basename_file" --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null | \
+            grep -v "^${target_file}$" | head -20 | sed 's/^/  /'
+    fi
+    echo ""
+}
+
+_code_hotspots() {
+    local top_n=10
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --top) top_n="${2:-10}"; shift 2 ;;
+            --top=*) top_n="${1#*=}"; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    section_header "Code Hotspots (top $top_n)" 2>/dev/null || echo -e "\n${BOLD}Code Hotspots${NC}"
+
+    if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+        echo -e "  ${RED}Not a git repository.${NC}"
+        return 1
+    fi
+
+    echo -e "  ${BOLD}Most Changed Files (last 90 days):${NC}"
+    echo ""
+    git log --since="90 days ago" --pretty=format: --name-only 2>/dev/null | \
+        sort | uniq -c | sort -rn | head -"$top_n" | \
+        while read -r count file; do
+            [ -z "$file" ] && continue
+            printf "  %4d changes  %s\n" "$count" "$file"
+        done
+
+    echo ""
+    echo -e "  ${BOLD}Largest Files by LOC:${NC}"
+    echo ""
+    find . -type f \( -name '*.py' -o -name '*.js' -o -name '*.ts' -o -name '*.go' \
+        -o -name '*.rs' -o -name '*.java' -o -name '*.sh' \) \
+        -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' \
+        -exec wc -l {} \; 2>/dev/null | sort -rn | head -"$top_n" | \
+        while read -r lines file; do
+            printf "  %6d lines  %s\n" "$lines" "$file"
+        done
+    echo ""
+}
+
+_code_diff() {
+    if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+        echo -e "${RED}Not a git repository.${NC}"
+        return 1
+    fi
+
+    # Use delta if available, otherwise colored diff
+    if command -v delta &>/dev/null; then
+        git diff "$@" | delta
+    else
+        git diff "$@" | while IFS= read -r line; do
+            case "$line" in
+                diff*)     echo -e "${BOLD}${line}${NC}" ;;
+                ---*)      echo -e "${BOLD}${line}${NC}" ;;
+                +++*)      echo -e "${BOLD}${line}${NC}" ;;
+                @@*)       echo -e "${CYAN}${line}${NC}" ;;
+                +*)        echo -e "${GREEN}${line}${NC}" ;;
+                -*)        echo -e "${RED}${line}${NC}" ;;
+                *)         echo "$line" ;;
+            esac
+        done
+    fi
+}
+
 # Output shell completion scripts
 cmd_completions() {
     local shell="${1:-bash}"