karajan-code 1.36.0 → 1.37.0

package/README.md

@@ -22,7 +22,7 @@
 
 ---
 
-You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate — without you babysitting every step.
+You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
 ## What is Karajan?
 
@@ -30,7 +30,7 @@ Karajan is a local coding orchestrator. It runs on your machine, uses your exist
 
 It is not a hosted service. It is not a VS Code extension. It is a tool you install once and use from the terminal or as an MCP server inside your AI agent.
 
-The name comes from Herbert von Karajan — the conductor who believed that the best orchestras are made of great independent musicians who know exactly when to play and when to listen. Same idea here, applied to AI agents.
+The name comes from Herbert von Karajan, the conductor who believed that the best orchestras are made of great independent musicians who know exactly when to play and when to listen. Same idea, applied to AI agents.
 
 ## Why not just use Claude Code?
 
@@ -39,16 +39,16 @@ Claude Code is excellent. Use it for interactive, session-based coding.
 Use Karajan when you want:
 
 - **A repeatable, documented pipeline** that runs the same way every time
-- **TDD by default** — tests are written before implementation, not after
-- **SonarQube integration** — code quality gates as part of the flow, not an afterthought
-- **Solomon as pipeline boss** — every reviewer rejection is evaluated by a supervisor that decides if it's valid or just style noise
-- **Multi-provider routing** — Claude as coder, Codex as reviewer, or any combination
-- **Zero-config operation** — auto-detects test frameworks, starts SonarQube, simplifies pipeline for trivial tasks
-- **Composable role architecture** — define agent behaviors as plain markdown files that travel with your project
-- **Local-first** — your code, your keys, your machine, no data leaves unless you say so
-- **Zero API costs** — Karajan uses AI agent CLIs (Claude Code, Codex, Gemini CLI), not APIs. You pay your existing subscription (Claude Pro, ChatGPT Plus), not per-token API fees. No surprise bills.
+- **TDD by default.** Tests are written before implementation, not after
+- **SonarQube integration.** Code quality gates as part of the flow, not an afterthought
+- **Solomon as pipeline boss.** Every reviewer rejection is evaluated by a supervisor that decides if it's valid or just style noise
+- **Multi-provider routing.** Claude as coder, Codex as reviewer, or any combination
+- **Zero-config operation.** Auto-detects test frameworks, starts SonarQube, simplifies pipeline for trivial tasks
+- **Composable role architecture.** Agent behaviors defined as plain markdown files that travel with your project
+- **Local-first.** Your code, your keys, your machine. No data leaves unless you say so
+- **Zero API costs.** Karajan uses AI agent CLIs (Claude Code, Codex, Gemini CLI), not APIs. You pay your existing subscription (Claude Pro, ChatGPT Plus), not per-token API fees
 
-If Claude Code is a smart pair programmer, Karajan is the CI/CD pipeline for AI-assisted development. They work great together — Karajan is designed to be used as an MCP server inside Claude Code.
+If Claude Code is a smart pair programmer, Karajan is the CI/CD pipeline for AI-assisted development. They work great together: Karajan is designed to be used as an MCP server inside Claude Code.
 
 ## Install
 
@@ -58,31 +58,143 @@ npm install -g karajan-code
 
 That's it. No Docker required (SonarQube uses Docker, but Karajan auto-manages it). No config files to copy. `kj init` auto-detects your installed agents.
 
-## Quick start
+## Three ways to use Karajan
 
-```bash
-# Run a task — Karajan handles the rest
-kj run "Create a utility function that validates Spanish DNI numbers, with tests"
-```
+Karajan installs **three commands**: `kj`, `kj-tail`, and `karajan-mcp`.
 
-[**▶ Watch the full pipeline demo**](https://karajancode.com#demo) — HU certification, triage, architecture, TDD, SonarQube, code review, Solomon arbitration, security audit.
+### 1. CLI: direct from terminal
 
-Karajan will:
-1. Triage the task complexity and activate the right roles
-2. Write tests first (TDD)
-3. Implement code to pass those tests
-4. Run SonarQube analysis (auto-starts Docker if needed)
-5. Review the code (Solomon evaluates every rejection)
-6. Iterate until approved or escalate to you
+Run Karajan directly. You see the full pipeline output in real time.
 
 ```bash
-# More examples
+kj run "Create a utility function that validates Spanish DNI numbers, with tests"
 kj code "Add input validation to the signup form"     # Coder only
 kj review "Check the authentication changes"           # Review current diff
 kj audit "Full health analysis of this codebase"       # Read-only audit
 kj plan "Refactor the database layer"                  # Plan without coding
 ```
 
+### 2. MCP: inside your AI agent
+
+This is the primary use case. Karajan runs as an MCP server inside Claude Code, Codex, or Gemini. You ask your AI agent to do something, and it delegates the heavy lifting to Karajan's pipeline.
+
+```
+You → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
+```
+
+The MCP server auto-registers during `npm install`. Your AI agent sees 20 tools (`kj_run`, `kj_code`, `kj_review`, etc.) and uses them as needed.
+
+**The problem**: when Karajan runs inside an AI agent, you lose visibility. The agent shows you the final result, but not the pipeline stages, iterations, or Solomon decisions happening in real time.
+
+### 3. kj-tail: monitor from a separate terminal
+
+**This is the companion tool.** Open a second terminal in the **same project directory** where your AI agent is working, and run:
+
+```bash
+kj-tail
+```
+
+You'll see the live pipeline output (stages, results, iterations, errors) as they happen. Same view as running `kj run` directly.
+
+```
+kj-tail                  # Follow pipeline in real time (default)
+kj-tail -v               # Verbose: include agent heartbeats and budget
+kj-tail -t               # Show timestamps
+kj-tail -s               # Snapshot: show current log and exit
+kj-tail -n 50            # Show last 50 lines then follow
+kj-tail --help           # Full options
+```
+
+> **Important**: `kj-tail` must run from the same directory where the AI agent is executing. It reads `<project>/.kj/run.log`, which is created when Karajan starts a pipeline via MCP.
+
+**Typical workflow:**
+
+```
+┌─────────────────────────┐    ┌─────────────────────────┐
+│  Terminal 1              │    │  Terminal 2              │
+│                          │    │                          │
+│  $ claude                │    │  $ kj-tail               │
+│  > implement the next    │    │                          │
+│    priority task         │    │  ├─ 📋 Triage: medium    │
+│                          │    │  ├─ 🔬 Researcher ✅     │
+│  (Claude calls kj_run   │    │  ├─ 🧠 Planner ✅        │
+│   via MCP, you see       │    │  ├─ 🔨 Coder ✅          │
+│   only the final result) │    │  ├─ 🔍 Sonar: OK        │
+│                          │    │  ├─ 👁️ Reviewer ❌       │
+│                          │    │  ├─ ⚖️ Solomon: 2 cond.  │
+│                          │    │  ├─ 🔨 Coder (iter 2) ✅ │
+│                          │    │  ├─ ✅ Review: APPROVED   │
+│                          │    │  ├─ 🧪 Tester: passed    │
+│                          │    │  └─ 🏁 Result: APPROVED  │
+└─────────────────────────┘    └─────────────────────────┘
+```
+
+**Full pipeline example**, a complex task with all roles:
+
+```
+┌─ Terminal 1 ─────────────────────────────────────────────────────────────────┐
+│                                                                              │
+│  $ claude                                                                    │
+│                                                                              │
+│  > Build a REST API for a booking system. Requirements:                      │
+│  > - Express + TypeScript with Zod validation on every endpoint              │
+│  > - Endpoints: POST /bookings, GET /bookings/:id, PATCH /bookings/:id/cancel│
+│  > - A booking has: id, guestName, roomType (standard|suite|penthouse),      │
+│  >   checkIn, checkOut, status (confirmed|cancelled)                         │
+│  > - Validate: checkOut must be after checkIn, no past dates,                │
+│  >   roomType must be a valid enum value                                     │
+│  > - Cancel returns 409 if already cancelled                                 │
+│  > - Use TDD. Run it through Karajan with architect and planner enabled,     │
+│  >   paranoid review mode. Coder claude, reviewer codex.                     │
+│                                                                              │
+│  Claude calls kj_run via MCP with:                                           │
+│    --enable-architect --enable-researcher --enable-planner --mode paranoid    │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+
+┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
+│                                                                              │
+│  kj-tail v1.37.0 — .kj/run.log                                              │
+│                                                                              │
+│  ├─ 📋 Triage: medium (sw) — enabling researcher, architect, planner         │
+│  ├─ ⚙️ Preflight passed — all checks OK                                     │
+│  ├─ 🔬 Researcher: 8 files analyzed, 3 patterns, 5 constraints              │
+│  ├─ 🏗️ Architect: 3-layer design (routes → service → validators)            │
+│  ├─ 🧠 Planner: 6 steps — tests first, then routes, service, validators     │
+│  │                                                                           │
+│  ▶ Iteration 1/5                                                             │
+│  ├─ 🔨 Coder (claude): implemented 3 endpoints + 18 tests                   │
+│  ├─ 📋 TDD: PASS (3 src, 2 test files)                                      │
+│  ├─ 🔍 Sonar: Quality gate OK — 0 blockers                                  │
+│  ├─ 👁️ Reviewer (codex): REJECTED (2 blocking)                              │
+│  │   "Missing 404 for GET nonexistent booking"                               │
+│  │   "Cancel endpoint lacks idempotency test"                                │
+│  ├─ ⚖️ Solomon: approve_with_conditions (2 conditions)                      │
+│  │   "Add 404 response and test for GET /bookings/:id with unknown id"       │
+│  │   "Add test: cancel already-cancelled booking returns 409, not 500"       │
+│  │                                                                           │
+│  ▶ Iteration 2/5                                                             │
+│  ├─ 🔨 Coder (claude): fixed — 22 tests now                                 │
+│  ├─ 📋 TDD: PASS                                                            │
+│  ├─ 🔍 Sonar: OK                                                            │
+│  ├─ 👁️ Reviewer (codex): APPROVED                                           │
+│  ├─ 🧪 Tester: passed — coverage 94%, 22 tests                              │
+│  ├─ 🔒 Security: passed — 0 critical, 1 low (helmet recommended)            │
+│  ├─ 📊 Audit: CERTIFIED (with 3 advisory warnings)                          │
+│  │                                                                           │
+│  🏁 Result: APPROVED                                                         │
+│     🔬 Research: 8 files, 3 patterns identified                              │
+│     🗺 Plan: 6 steps (tests first)                                           │
+│     🧪 Coverage: 94%, 22 tests                                               │
+│     🔒 Security: passed                                                      │
+│     🔍 Sonar: OK                                                             │
+│     💰 Budget: $0.42 (claude: $0.38, codex: $0.04)                           │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+[**Watch the full pipeline demo**](https://karajancode.com#demo): triage, architecture, TDD, SonarQube, code review, Solomon arbitration, security audit.
+
 ## The pipeline
 
 ```
@@ -105,7 +217,7 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 | **reviewer** | Code review with configurable strictness profiles | **Always on** |
 | **tester** | Test quality gate and coverage verification | **On** |
 | **security** | OWASP security audit | **On** |
-| **solomon** | Pipeline boss — evaluates every rejection, overrides style-only blocks | **On** |
+| **solomon** | Pipeline boss: evaluates every rejection, overrides style-only blocks | **On** |
 | **commiter** | Git commit, push, and PR automation after approval | Off |
 | **audit** | Read-only codebase health analysis (5 dimensions, A-F scores) | Standalone |
 
@@ -121,21 +233,25 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 
 Mix and match. Use Claude as coder and Codex as reviewer. Karajan auto-detects installed agents during `kj init`.
 
-## MCP server — 20 tools
+## MCP server (20 tools)
 
-Karajan is designed to be used as an MCP server inside your AI agent. After install, it auto-registers in Claude and Codex:
+After `npm install -g karajan-code`, the MCP server auto-registers in Claude and Codex. Manual config if needed:
 
 ```bash
-# Already done by npm install, but manual config if needed:
-# Add to ~/.claude.json → "mcpServers":
+# Claude: add to ~/.claude.json → "mcpServers":
 # { "karajan-mcp": { "command": "karajan-mcp" } }
+
+# Codex: add to ~/.codex/config.toml → [mcp_servers."karajan-mcp"]
+# command = "karajan-mcp"
 ```
 
 **20 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`.
 
+Use `kj-tail` in a separate terminal to see what the pipeline is doing in real time (see [Three ways to use Karajan](#three-ways-to-use-karajan)).
+
 ## The role architecture
 
-Every role in Karajan is defined by a markdown file — a plain document that describes how the agent should behave, what to check, and what good output looks like.
+Every role in Karajan is defined by a markdown file: a plain document that describes how the agent should behave, what to check, and what good output looks like.
 
 ```
 .karajan/roles/         # Project overrides (optional)
@@ -143,7 +259,7 @@ Every role in Karajan is defined by a markdown file — a plain document that de
 templates/roles/        # Built-in defaults (shipped with package)
 ```
 
-You can override any built-in role or create new ones. No code required. The agents read the role files and adapt their behavior. This means you can encode your team's conventions, domain rules, and quality standards — and every run of Karajan will apply them automatically.
+You can override any built-in role or create new ones. No code required. The agents read the role files and adapt their behavior. Encode your team's conventions, domain rules, and quality standards, and every run of Karajan applies them automatically.
 
 Use `kj roles show <role>` to inspect any template.
 
@@ -152,7 +268,8 @@ Use `kj roles show <role>` to inspect any template.
 Karajan auto-detects and auto-configures everything it can:
 
 - **TDD**: Detects test framework (vitest, jest, mocha) → auto-enables TDD
-- **Bootstrap gate**: Validates all prerequisites (git repo, remote, config, agents, SonarQube) before any tool runs. Fails hard with actionable fix instructions — never silently degrades
+- **Bootstrap gate**: Validates all prerequisites (git repo, remote, config, agents, SonarQube) before any tool runs. Fails hard with actionable fix instructions, never silently degrades
+- **Injection guard**: Scans diffs for prompt injection before AI review. Detects directive overrides, invisible Unicode, oversized comment payloads. Also runs as a GitHub Action on every PR
 - **SonarQube**: Auto-starts Docker container, generates config if missing
 - **Pipeline complexity**: Triage classifies task → trivial tasks skip reviewer loop
 - **Provider outages**: Retries on 500/502/503/504 with backoff (same as rate limits)
@@ -164,16 +281,16 @@ No per-project configuration required. If you want to customize, config is layer
 
 Because it should be.
 
-Karajan has **1966 tests** across 157 files. It runs on Node.js without a build step. You can read the source, understand it, fork it, and modify it without a TypeScript compiler between you and the code.
+Karajan has **2044 tests** across 161 files. It runs on Node.js without a build step. You can read the source, understand it, fork it, and modify it without a TypeScript compiler between you and the code.
 
-This is a deliberate choice, not a limitation. The tests are the type safety. The legibility is a feature. **55 releases in 26 days** — that velocity is possible precisely because vanilla JS with good tests lets you move fast without fear.
+This is a deliberate choice, not a limitation. The tests are the type safety. The legibility is a feature. 57 releases in 45 days. That velocity is possible precisely because vanilla JS with good tests lets you move fast without fear.
 
 ## Recommended companions
 
 | Tool | Why |
 |------|-----|
 | [**RTK**](https://github.com/rtk-ai/rtk) | Reduces token consumption by 60-90% on Bash command outputs |
-| [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | Agile project management (tasks, sprints, estimation) — XP-native |
+| [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | Agile project management (tasks, sprints, estimation), XP-native |
 | [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Create PRs, manage issues directly from the agent |
 | [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Verify UI changes visually after frontend modifications |
 
@@ -183,11 +300,11 @@ This is a deliberate choice, not a limitation. The tests are the type safety. Th
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 1847 tests with Vitest
+npm test              # Run 2044 tests with Vitest
 npm run validate      # Lint + test
 ```
 
-Issues and pull requests welcome. If something doesn't work as documented, [open an issue](https://github.com/manufosela/karajan-code/issues) — that's the most useful contribution at this stage.
+Issues and pull requests welcome. If something doesn't work as documented, [open an issue](https://github.com/manufosela/karajan-code/issues). That's the most useful contribution at this stage.
 
 ## Links
 
@@ -199,4 +316,4 @@ Issues and pull requests welcome. If something doesn't work as documented, [open
 
 ---
 
-Built by [@manufosela](https://github.com/manufosela) — Head of Engineering at Geniova Technologies, co-organizer of NodeJS Madrid, author of [Liderazgo Afectivo](https://www.amazon.es/dp/B0D7F4C8KC). 90+ npm packages published.
+Built by [@manufosela](https://github.com/manufosela). Head of Engineering at Geniova Technologies, co-organizer of NodeJS Madrid, author of [Liderazgo Afectivo](https://www.amazon.es/dp/B0D7F4C8KC). 90+ npm packages published.

package/bin/kj-tail

@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
-# kj-tail — Colorized, filtered tail for Karajan run logs
-# Usage: kj-tail [project-dir] [-v|--verbose]
+# kj-tail — Real-time pipeline monitor for Karajan Code
+# Follows the run log and displays colorized, filtered output.
 
 set -euo pipefail
 
-# Colors
+VERSION="1.36.0"
+
+# ── Colors ──────────────────────────────────────────────
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[0;33m'
@@ -13,58 +15,309 @@ CYAN='\033[0;36m'
 MAGENTA='\033[0;35m'
 GRAY='\033[0;90m'
 BOLD='\033[1m'
+DIM='\033[2m'
 RESET='\033[0m'
 
+# ── Defaults ────────────────────────────────────────────
 VERBOSE=false
+SHOW_AGENT_OUTPUT=false
+SHOW_TIMESTAMPS=false
+FOLLOW=true
+NUM_LINES=0
 PROJECT_DIR=""
 
-for arg in "$@"; do
-  case "$arg" in
-    -v|--verbose) VERBOSE=true ;;
-    *) PROJECT_DIR="$arg" ;;
+# ── Help ────────────────────────────────────────────────
+show_help() {
+  cat <<EOF
+${BOLD}kj-tail${RESET} — Real-time pipeline monitor for Karajan Code
+
+${BOLD}USAGE${RESET}
+  kj-tail [options] [project-dir]
+
+${BOLD}DESCRIPTION${RESET}
+  Follows the Karajan run log (<project>/.kj/run.log) and displays
+  colorized, filtered output. By default shows the same pipeline
+  progress view as 'kj run': stages, results, iterations, and errors.
+
+  Run this in a separate terminal while kj executes via MCP/CLI.
+
+${BOLD}OPTIONS${RESET}
+  -v, --verbose       Show agent heartbeats, budget, and metadata
+  -a, --agent-output  Show raw agent output lines (very noisy)
+  -t, --timestamps    Show timestamps on each line
+  -n, --lines <N>     Show last N lines then follow (default: follow only new)
+  -s, --snapshot      Show current log (no follow) — like 'cat' with colors
+  -h, --help          Show this help
+  --version           Show version
+
+${BOLD}EXAMPLES${RESET}
+  kj-tail                  # Follow current directory's run log
+  kj-tail /path/to/project # Follow a specific project's log
+  kj-tail -v               # Verbose: include heartbeats and budget
+  kj-tail -a               # Show everything including agent output
+  kj-tail -n 50            # Show last 50 lines then follow
+  kj-tail -s               # Snapshot: show full log and exit
+  kj-tail -t               # Show timestamps
+
+${BOLD}LOG LOCATION${RESET}
+  <project-dir>/.kj/run.log
+  Created automatically when kj_run, kj_code, or kj_review starts.
+
+EOF
+  exit 0
+}
+
+# ── Parse args ──────────────────────────────────────────
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help) show_help ;;
+    --version) echo "kj-tail $VERSION"; exit 0 ;;
+    -v|--verbose) VERBOSE=true; shift ;;
+    -a|--agent-output) SHOW_AGENT_OUTPUT=true; VERBOSE=true; shift ;;
+    -t|--timestamps) SHOW_TIMESTAMPS=true; shift ;;
+    -s|--snapshot) FOLLOW=false; shift ;;
+    -n|--lines)
+      shift
+      NUM_LINES="${1:-50}"
+      shift
+      ;;
+    -*)
+      echo -e "${RED}Unknown option: $1${RESET}" >&2
+      echo "Run 'kj-tail --help' for usage." >&2
+      exit 1
+      ;;
+    *) PROJECT_DIR="$1"; shift ;;
   esac
 done
 
 PROJECT_DIR="${PROJECT_DIR:-$(pwd)}"
 LOG_FILE="${PROJECT_DIR}/.kj/run.log"
 
+# ── Locate log ──────────────────────────────────────────
 if [[ ! -f "$LOG_FILE" ]]; then
-  echo -e "${RED}No run.log found at ${LOG_FILE}${RESET}"
-  echo "Usage: kj-tail [project-dir] [-v|--verbose]"
+  echo -e "${RED}No run log found at ${LOG_FILE}${RESET}"
+  echo ""
+  echo "The run log is created when Karajan starts a pipeline."
+  echo "Make sure you're in the project directory, or pass it as argument:"
+  echo ""
+  echo "  kj-tail /path/to/project"
+  echo ""
   exit 1
 fi
 
-echo -e "${BOLD}${CYAN}Karajan tail${RESET} ${GRAY}— ${LOG_FILE}${RESET}"
-echo -e "${GRAY}Ctrl+C to stop. Use -v to include agent output.${RESET}"
-echo ""
+# ── Filter & colorize ──────────────────────────────────
+filter_line() {
+  local line="$1"
+  local ts=""
+  local clean="$line"
 
-tail -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
-  # Strip timestamp (HH:MM:SS.mmm)
-  clean="${line#[0-9][0-9]:[0-9][0-9]:[0-9][0-9].[0-9][0-9][0-9] }"
-
-  # Strip [agent:output] tag — it's the default, no need to show it
-  clean="${clean/\[agent:output\] /}"
-
-  # Colorize by content
-  if [[ "$clean" == *"[coder:start]"* ]] || [[ "$clean" == *"[coder:done]"* ]] || [[ "$clean" == *"[coder]"* ]]; then
-    echo -e "${GREEN}${clean}${RESET}"
-  elif [[ "$clean" == *"[reviewer"* ]]; then
-    echo -e "${YELLOW}${clean}${RESET}"
-  elif [[ "$clean" == *"[sonar"* ]]; then
-    echo -e "${BLUE}${clean}${RESET}"
-  elif [[ "$clean" == *"[solomon"* ]]; then
-    echo -e "${MAGENTA}${clean}${RESET}"
-  elif [[ "$clean" == *"[iteration"* ]] || [[ "$clean" == *"[session"* ]] || [[ "$clean" == *"[kj_run]"* ]] || [[ "$clean" == *"[kj_code]"* ]]; then
-    echo -e "${BOLD}${CYAN}${clean}${RESET}"
-  elif [[ "$clean" == *"fail"* ]] || [[ "$clean" == *"error"* ]] || [[ "$clean" == *"FAIL"* ]] || [[ "$clean" == *"ERROR"* ]]; then
-    echo -e "${RED}${clean}${RESET}"
-  elif [[ "$clean" == *"[agent:heartbeat]"* ]]; then
-    echo -e "${GRAY}${clean}${RESET}"
-  elif [[ "$clean" == *"[standby]"* ]] || [[ "$clean" == *"standby"* ]]; then
-    echo -e "${YELLOW}${clean}${RESET}"
-  elif [[ "$clean" == "---"* ]]; then
-    echo -e "${BOLD}${clean}${RESET}"
-  else
-    echo "$clean"
+  # Extract and optionally strip timestamp (HH:MM:SS.mmm)
+  if [[ "$clean" =~ ^([0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3})\ (.*) ]]; then
+    ts="${BASH_REMATCH[1]}"
+    clean="${BASH_REMATCH[2]}"
   fi
-done
+
+  # Skip noise in default mode
+  if [[ "$VERBOSE" == "false" ]]; then
+    # Skip agent heartbeats
+    [[ "$clean" == *"[agent:heartbeat]"* ]] && return
+    [[ "$clean" == *"heartbeat"* ]] && return
+    # Skip budget lines
+    [[ "$clean" == *"Budget:"* ]] && return
+    # Skip agent raw output
+    [[ "$clean" == *"[agent:output]"* ]] && return
+    # Skip internal metadata
+    [[ "$clean" == *"[agent:start]"* ]] && return
+    [[ "$clean" == *"[agent:end]"* ]] && return
+    # Skip noisy JSON dumps (system init, tool lists, etc.)
+    [[ "${#clean}" -gt 500 ]] && return
+  fi
+
+  if [[ "$SHOW_AGENT_OUTPUT" == "false" ]]; then
+    # Skip raw agent output (often JSON/stream data)
+    [[ "$clean" == "{"* ]] && [[ "$clean" == *"}" ]] && return
+    [[ "$clean" == *'"type":'* ]] && [[ "${#clean}" -gt 200 ]] && return
+  fi
+
+  # Build prefix
+  local prefix=""
+  if [[ "$SHOW_TIMESTAMPS" == "true" ]] && [[ -n "$ts" ]]; then
+    prefix="${DIM}${ts}${RESET} "
+  fi
+
+  # ── Colorize by content ──────────────────────────────
+  # Session markers
+  if [[ "$clean" == "---"* ]]; then
+    echo -e "${prefix}${BOLD}${CYAN}${clean}${RESET}"
+    return
+  fi
+
+  # Stage: started/finished
+  if [[ "$clean" == *"started"* ]] && [[ "$clean" == *"[kj_"* ]]; then
+    echo -e "${prefix}${BOLD}${CYAN}▶ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"finished"* ]] && [[ "$clean" == *"[kj_"* ]]; then
+    echo -e "${prefix}${BOLD}${GREEN}✓ ${clean}${RESET}"
+    return
+  fi
+
+  # Iterations
+  if [[ "$clean" == *"[iteration]"* ]] || [[ "$clean" == *"Iteration "* ]]; then
+    echo -e "${prefix}${BOLD}${clean}${RESET}"
+    return
+  fi
+
+  # Coder
+  if [[ "$clean" == *"[coder"* ]] || [[ "$clean" == *"Coder"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ 🔨 ${clean}${RESET}"
+    return
+  fi
+
+  # Reviewer
+  if [[ "$clean" == *"APPROVED"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ ✅ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"REJECTED"* ]]; then
+    echo -e "${prefix}${RED}  ├─ ❌ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"[reviewer"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ 👁️  ${clean}${RESET}"
+    return
+  fi
+
+  # Solomon
+  if [[ "$clean" == *"[solomon"* ]] || [[ "$clean" == *"Solomon"* ]]; then
+    echo -e "${prefix}${MAGENTA}  ├─ ⚖️  ${clean}${RESET}"
+    return
+  fi
+
+  # Sonar
+  if [[ "$clean" == *"[sonar"* ]] || [[ "$clean" == *"SonarQube"* ]] || [[ "$clean" == *"Quality gate"* ]]; then
+    echo -e "${prefix}${BLUE}  ├─ 🔍 ${clean}${RESET}"
+    return
+  fi
+
+  # Tester
+  if [[ "$clean" == *"[tester"* ]] || [[ "$clean" == *"Tester"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🧪 ${clean}${RESET}"
+    return
+  fi
+
+  # Security
+  if [[ "$clean" == *"[security"* ]] || [[ "$clean" == *"Security"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🔒 ${clean}${RESET}"
+    return
+  fi
+
+  # Researcher
+  if [[ "$clean" == *"[researcher"* ]] || [[ "$clean" == *"Researcher"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🔬 ${clean}${RESET}"
+    return
+  fi
+
+  # Architect
+  if [[ "$clean" == *"[architect"* ]] || [[ "$clean" == *"Architect"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🏗️  ${clean}${RESET}"
+    return
+  fi
+
+  # Planner
+  if [[ "$clean" == *"[planner"* ]] || [[ "$clean" == *"Planner"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🧠 ${clean}${RESET}"
+    return
+  fi
+
+  # Triage
+  if [[ "$clean" == *"[triage"* ]] || [[ "$clean" == *"Triage"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 📋 ${clean}${RESET}"
+    return
+  fi
+
+  # Audit
+  if [[ "$clean" == *"[audit"* ]] || [[ "$clean" == *"Audit"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 📊 ${clean}${RESET}"
+    return
+  fi
+
+  # Preflight
+  if [[ "$clean" == *"[preflight"* ]] || [[ "$clean" == *"Preflight"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ ⚙️  ${clean}${RESET}"
+    return
+  fi
+
+  # TDD
+  if [[ "$clean" == *"TDD"* ]] || [[ "$clean" == *"tdd"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ 📋 ${clean}${RESET}"
+    return
+  fi
+
+  # Errors / failures
+  if [[ "$clean" == *"fail"*  || "$clean" == *"FAIL"* || "$clean" == *"error"* || "$clean" == *"ERROR"* ]]; then
+    echo -e "${prefix}${RED}  ├─ ⚠️  ${clean}${RESET}"
+    return
+  fi
+
+  # Standby / rate limit
+  if [[ "$clean" == *"[standby]"* ]] || [[ "$clean" == *"standby"* ]] || [[ "$clean" == *"rate limit"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ ⏸️  ${clean}${RESET}"
+    return
+  fi
+
+  # Model fallback
+  if [[ "$clean" == *"not supported"* ]] || [[ "$clean" == *"retrying with"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ 🔄 ${clean}${RESET}"
+    return
+  fi
+
+  # Result line
+  if [[ "$clean" == *"Result:"* ]]; then
+    echo -e "${prefix}${BOLD}${GREEN}🏁 ${clean}${RESET}"
+    return
+  fi
+
+  # Budget (verbose only — already filtered above)
+  if [[ "$clean" == *"Budget:"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ 💰 ${clean}${RESET}"
+    return
+  fi
+
+  # Agent heartbeat (verbose only)
+  if [[ "$clean" == *"heartbeat"* ]] || [[ "$clean" == *"active —"* ]] || [[ "$clean" == *"elapsed"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ • ${clean}${RESET}"
+    return
+  fi
+
+  # Default
+  echo -e "${prefix}  ├─ ${clean}"
+}
+
+# ── Header ──────────────────────────────────────────────
+echo -e "${BOLD}${CYAN}kj-tail${RESET} ${DIM}v${VERSION} — ${LOG_FILE}${RESET}"
+if [[ "$FOLLOW" == "true" ]]; then
+  echo -e "${GRAY}Ctrl+C to stop${RESET}${VERBOSE:+ ${DIM}(verbose)${RESET}}"
+fi
+echo ""
+
+# ── Run ─────────────────────────────────────────────────
+if [[ "$FOLLOW" == "false" ]]; then
+  # Snapshot mode: show full log and exit
+  while IFS= read -r line; do
+    filter_line "$line"
+  done < "$LOG_FILE"
+  exit 0
+fi
+
+if [[ "$NUM_LINES" -gt 0 ]]; then
+  # Show last N lines then follow
+  tail -n "$NUM_LINES" -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
+    filter_line "$line"
+  done
+else
+  # Follow only new lines
+  tail -n 0 -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
+    filter_line "$line"
+  done
+fi