kuzushi

v0.20.0

Published

8 days ago

Kuzushi — security-native AI operating environment

Downloads

2,202

0High
0Medium
0Low

snejad123

sast security semgrep ai triage

Kuzushi — Security-Native AI Operating Environment

kuzushi.dev

Kuzushi combines offensive security, defensive operations, and compliance governance into a single interactive platform — powered by LLM agents, backed by a persistent workspace, and delivered through a rich terminal UI.

Find the vulnerability. Prove it's exploitable. Deploy a honeypot to detect it. Check if it violates PCI DSS. Generate the patch. One tool, one conversation.

npm install -g kuzushi
kuzushi

Three Ways to Use It

Shell (default)

Just type kuzushi. The interactive copilot shell starts with your loaded modules, available tools, and any active workspace. Talk naturally or use structured commands.

kuzushi shell                                  # default — just `kuzushi` works
kuzushi shell --workspace acme-pentest         # resume an engagement
kuzushi shell --target ./repo                  # set initial target
kuzushi shell --load randori,vuln-scout,tob    # pre-load specific built-in modules

╭─────────────────────────────────────────────────────────────╮
│  kuzushi shell                      workspace: acme-api     │
│  modules: sast, randori, vuln-scout, tob, variant-hunter    │
│  target: ./acme-api  (Node.js + Express + PostgreSQL)       │
╰─────────────────────────────────────────────────────────────╯

kuzushi> modules
kuzushi> use sast
kuzushi/sast> run scan ./repo preset=deep
kuzushi/sast> back
kuzushi> tools
kuzushi> run verify:finding fingerprint=abc123
kuzushi> exit

Common shell flows

# Catalog / module home / tune
kuzushi> use sast             # focus → module home
kuzushi/sast> findings        # unified list with filter chips + chain boxing
kuzushi/sast> open F-0001     # linear deep page for a finding
kuzushi/sast> tune            # six plain controls + optional "house rules"
kuzushi/sast> back            # step up one level

# Natural-language planner — English → option diff → y/n apply
kuzushi/sast> /plan run harder, focus on auth, stop wasting money
kuzushi/sast> y               # apply the proposed changes

# Prompt editor — per-tool system-prompt override in $EDITOR
kuzushi/sast> /prompt edit triage          # opens .kuzushi/prompts/sast/triage.md
kuzushi/sast> /prompt show verify          # show effective prompt + source
kuzushi/sast> /show prompts                # cross-module audit table

# Replay / trace — re-read the outcome of a past run, no re-exec
kuzushi> /show runs                        # list recent runs
kuzushi> /replay 7f3a                      # re-render a past summary
kuzushi> /trace 7f3a                       # stream the per-event JSONL log

# Threat-model views — five screens over the randori output
kuzushi> /threats dfd                      # ASCII data flow diagram
kuzushi> /threats stride                   # element × STRIDE heat matrix
kuzushi> /threats stories                  # attacker narrative cards
kuzushi> /threats scope                    # criticality + operator edits
kuzushi> /threats summary                  # counts, drives, export paths
# Press 1..5 at any threat view to cycle.

# Short-ID aliases — F-0001 / C-01 resolve through a deterministic map
kuzushi/sast> /show aliases F-             # filter by prefix
kuzushi/sast> open F-0003                  # same as typing the fingerprint

# Diff-aware — pivot to "what changed since <ref>" without restarting
kuzushi> /since main                       # findings + threats scoped to changed files
kuzushi> /since v1.2.0                     # works with any git ref (tags, SHAs, HEAD~5)

Keyboard shortcuts

| Key | While running | At the idle prompt | | -------------- | --------------------------------- | ----------------------------------- | | Ctrl+C | Abort the running tool / turn | First press arms, second exits (2s) | | Ctrl+D | Abort (same as Ctrl+C) | Exits | | Enter | — | Send input | | ↑ / ↓ | — | Previous / next command | | Esc | — | Clear input buffer | | 1–5 | — | Cycle threat-model sub-views |

Ctrl+C aborts through four independent paths (Ink useInput on raw stdin, a byte-level stdin watcher, SIGINT, and a dedicated /dev/tty reader) so long-running LLM tools still cancel cleanly even when a subprocess has grabbed the terminal's foreground group. Under abort every Claude Agent SDK subprocess (and its descendants) receives SIGTERM directly — no relying on the SDK's own signal handling.

Set KUZUSHI_ABORT_DEBUG=1 to trace the abort path to stderr when diagnosing Ctrl+C issues.

On-disk artefacts

Operators can version-control any of these and have them round-trip with the shell — /prompt edit and /tune write here, and randori / scan runs read from here.

| Path | Role | | ------------------------------------------ | ------------------------------------------ | | ~/.kuzushi/config.json | Global config (/config) | | .kuzushi/threat-model.json | Persistent threat model (editable) | | .kuzushi/house-rules/<moduleId>.md | Operator nudges per module (/tune) | | .kuzushi/prompts/<moduleId>/<verb>.md | Per-tool system-prompt override | | .kuzushi/runs/<runId>/summary.json | Run summary (for /replay) | | .kuzushi/runs/<runId>/triage.jsonl | Per-event triage audit log (for /trace) | | .kuzushi/runs/<runId>/verify.jsonl | Per-event verify audit log (for /trace) | | .kuzushi/findings.sqlite3 | Findings + pipeline_runs DB |

Scan (headless pipeline)

The full SAST pipeline — 40+ agent tasks orchestrated as a DAG. Semgrep, CodeQL, 30+ agentic detectors, AI triage, verification, PoC generation, patch synthesis. CI/CD-native with SARIF, quality gates, and exit codes.

kuzushi scan <repo>
kuzushi scan <repo> --preset deep --verify --auto-patch
kuzushi scan <repo> --sarif report.sarif --fail-on-tp --quality-gate
kuzushi scan <repo> --resume

Run (headless module tool)

Execute a single module tool without the interactive shell. Scriptable, composable with unix pipes.

kuzushi run sast:scan ./repo --json
kuzushi run triage:run fingerprint=abc123 --json
kuzushi run verify:finding fingerprint=abc123 --quiet
kuzushi run findings:list severity=critical,high --json

Quick Start

Prereqs: Node 22+, and either an API key or Claude Code OAuth login.

# Install globally
npm install -g kuzushi

# Start the copilot shell (default)
kuzushi

# Or run a headless scan
kuzushi scan /path/to/your/repo

# With specific providers
export ANTHROPIC_API_KEY=sk-ant-...
kuzushi scan /path/to/your/repo

# With OpenAI, Google, Groq, Mistral, or 15+ other providers
kuzushi scan /path/to/repo --model openai:gpt-4o
kuzushi scan /path/to/repo --model google:gemini-2.0-flash

Kuzushi auto-downloads Opengrep if you don't have a scanner installed. Zero dependencies to manage.

Quick Start (Contributors)

Two commands, deterministic, loud on failure:

git clone https://github.com/allsmog/Kuzushi.git
cd Kuzushi
pnpm setup      # verifies Node 22+, pins pnpm via corepack, checks externals, pnpm install
pnpm doctor     # optional: re-verify the environment at any time

Then:

pnpm dev --help       # run the CLI from source via tsx
pnpm test             # unit tests (vitest)
pnpm check:types      # typecheck src + benchmarks + perf (in parallel)
pnpm build            # incremental compile to dist/ — incremental, fast
pnpm build:clean      # wipe dist/ and rebuild from scratch (used by `pnpm prepack`)

Optional benchmark corpuses (clones 3rd-party vulnerable apps on demand):

pnpm setup:benchmarks list          # list available corpuses
pnpm setup:benchmarks govwa         # clone one
pnpm setup:benchmarks all           # clone everything

Prefer a containerised environment? Open the repo in VS Code / Codespaces and "Reopen in Container" — the .devcontainer/devcontainer.json runs pnpm setup --strict automatically and installs semgrep + python for you.

Module System

Kuzushi's capabilities come from CopilotModules that expose tools (for shell and run modes) and optionally pipeline tasks (for scan mode DAG execution), plus a set of Claude Code plugins that are wrapped by built-in modules. Three buckets:

Built-in `CopilotModule`s (always available)

| Module | Category | What It Does | Key Tools | |--------|----------|--------------|-----------| | sast | offense | 40+ task SAST pipeline: Semgrep, CodeQL, agentic detectors, AI triage, verification, PoC, patch | sast:scan plus split-module tools semgrep:scan, codeql:scan, agentic-sast:scan, triage:run, verify:finding, patch:finding, findings:list, context:build, threat-hunt:run, taint-iris:hunt | | randori | intel | PASTA threat modeling via the @kuzushi/randori-plugin — S1–S4 stages plus narrative synthesis, returning a ThreatModelDocument | randori:pasta, randori:threat-model | | vuln-scout | offense | Whitebox pentest via the @kuzushi/vuln-scout plugin — agentic SAST + taint analysis returning normalized Findings | vuln-scout:audit | | tob | offense | Trail of Bits skills audit via @kuzushi/tob-skills — fp-check, sharp-edges, insecure-defaults, static-analysis, variant-analysis, and more | tob:audit, tob:skills | | shinsa | governance | ISO 27001 Annex A + NIST SP 800-53 Rev 5 compliance assessment via shinsa-plugin — evidence-backed controls mapped to file:line citations | shinsa:scan, shinsa:quick-check, shinsa:nist-scan, shinsa:nist-quick-check, shinsa:frameworks | | prompt-armor | offense | LLM red teaming via promptarmor-plugin — 80+ attack plugins, 25+ mutation strategies, code-aware remediation (network commands require authorized: true) | prompt-armor:scan, prompt-armor:analyze, prompt-armor:attack, prompt-armor:diff, prompt-armor:report, prompt-armor:config | | variant | offense | Lifts confirmed findings into portable signatures and hunts for variants across the repo (including vendored deps) | variant:lift-pattern, variant:hunt | | ndiff | offense | CVE-diff-based n-day hunting and variant search against a target | ndiff:fetch-cve, ndiff:search-patch-shape, ndiff:hunt-variants |

Load with the shell or at startup: kuzushi shell --load randori,vuln-scout,tob,shinsa,prompt-armor,variant,ndiff (the bare id works — builtin: prefix is optional). Legacy ids variant-hunter / n-day-diff-hunter still resolve for backward compatibility.

Legacy sast:<action> aliases for split-module tools still resolve for backward compatibility, but new scripts and docs should use the canonical tool names shown above.

External `CopilotModule` packages

| Package | Module ID | Usage | |---------|-----------|-------| | @kuzushi/augur | augur | Neuro-symbolic SAST (IRIS/ICLR 2025 LLM-driven CodeQL taint analysis). Load with --load package:@kuzushi/augur. |

Referenced Claude Code plugins

These are dependencies consumed by the built-in wrappers above, not directly loadable as CopilotModules. Attempting --load package:@kuzushi/randori-plugin (etc.) prints a pointer to the corresponding built-in module.

| Package | Wrapped by | Notes | |---------|------------|-------| | @kuzushi/randori-plugin | built-in randori | PASTA threat-modeling plugin (commands, agents, skills, hooks). | | @kuzushi/vuln-scout | built-in vuln-scout | Whitebox pentest skill pack under whitebox-pentest/. | | @kuzushi/tob-skills | built-in tob | Fork of trailofbits/skills — security-relevant plugins under plugins/. | | shinsa-plugin | built-in shinsa | ISO 27001 + NIST 800-53 compliance assessment (4 commands, 10 assessor agents). | | promptarmor-plugin | built-in prompt-armor | LLM red teaming (6 commands + MCP server under server/). |

Roadmap (not yet shipped)

blackbox, pwn, pentest, honeypot, yokai, revgraph — referenced in the long-term vision but not currently implemented as loadable modules. See VISION.md for direction.

Authoring your own module

kuzushi create-module my-module --template offense   # scaffolds manifest + starter tool + vitest

The scaffolder emits module.manifest.json (with kuzushiSdkVersion and $schema), a TypeScript starter using defineModule/defineTool, and a vitest skeleton using kuzushi/testing. Import surface:

import { defineModule, defineTool, ModuleLoadError } from "kuzushi/modules"
import type { CopilotModule, ToolExecutionContext, ToolResult } from "kuzushi/modules"
import { createMockToolContext, assertToolResult, expectModuleShape } from "kuzushi/testing"

Load a local build with --load file:///abs/path/to/my-module, a published package with --load package:@scope/name, or an MCP server with --load mcp:<spec>. The full authoring guide — manifest, ToolExecutionContext reference, capability probes, load errors, testing, MCP bridging — lives in docs/modules.md.

The SAST Pipeline

The built-in sast module runs a 40+ task DAG pipeline:

  ┌─────────────┐     ┌──────────────┐     ┌──────────────┐     ┌─────────┐     ┌──────────┐
  │  Task DAG    │────>│  AI Triage   │────>│ Verification │────>│  Patch  │────>│  Report  │
  │ Semgrep      │     │ Investigate  │     │ Construct    │     │ Generate │     │ TP only  │
  │ CodeQL       │     │ each finding │     │ PoC exploits │     │ & verify │     │ + export │
  │ 30+ tasks    │     │ with context │     │ (optional)   │     │ (opt-in) │     │ + stream │
  └─────────────┘     └──────────────┘     └──────────────┘     └─────────┘     └──────────┘

Context gathering — auto-detects tech stack, frameworks, auth patterns, ORMs, sanitization
Code graph — builds entry-point-to-sink graph via static analysis + LLM discovery
Threat modeling — Randori PASTA plugin: business objectives, technical scope, DFD decomposition, STRIDE threats with ATT&CK/CAPEC/OWASP mapping and 5-factor probabilistic scoring
Threat-informed hunting — adversarial Claude agents per DFD external entity, CTF-style hunting
Task DAG execution — Semgrep, CodeQL, agentic scanner, 15+ specialized detectors (SSRF, SQLi, XSS, command injection, XXE, deserialization, NoSQL injection, template injection, prototype pollution, race conditions, supply chain, GraphQL, secrets/crypto, auth logic, systems-level deep semantic analysis)
Classifier funnel — cheap single-token pre-filter removes ~80% noise before expensive triage
Deduplication — fingerprints and merges equivalent findings across scanners
AI triage — agent investigates each finding with source context, code graph, evidence chains, threat model, CWE-specific knowledge
Variant analysis — confirmed TPs trigger automatic search for similar patterns
Verification (optional) — constructs concrete PoC exploit payloads
PoC harness (optional) — produces runnable exploit scripts with execution feedback
Dynamic analysis (optional) — executes harnesses in Docker sandbox
Auto-patch (optional) — generates, validates, and re-verifies patches in disposable worktrees
Report — terminal display + SARIF, Markdown, JSON, CSV, JSONL; optional SSE streaming

For each finding, you get: verdict (tp/fp/by_design/needs_review), confidence (0-1), rationale with code references, verification steps, fix suggestion, optional PoC exploit, and cost in USD.

CI Integration

GitHub Actions

name: Security Scan
on: [push, pull_request]
jobs:
  kuzushi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx kuzushi scan . --sarif results.sarif --junit results.xml --quality-gate --fail-on-tp
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

Exit codes: 0 clean, 1 findings (or task failures), 2 usage/config/auth, 3 unexpected crash. See .github/workflows/kuzushi-reference.yml for a reference workflow with SARIF upload, JUnit publish, and PR sticky comment.

`--ci` stream mode

--ci disables the Ink TUI and attaches a plain-text stream formatter that writes one line per meaningful pipeline event. Log-renderer-friendly, grep-friendly, and free of ANSI control codes:

kuzushi scan ./repo --ci --sarif results.sarif

[2026-04-20T14:20:01Z] scan: ./repo started
[2026-04-20T14:20:01Z] phase: (init) → scanning
[2026-04-20T14:20:12Z] stage: scan → done [8.3s]
[2026-04-20T14:20:12Z] stage: triage → active (15 findings)
[2026-04-20T14:20:45Z] finding: abc123def456 tp 92% $0.0041
[2026-04-20T14:21:20Z] summary: 4 tp · 10 fp · $0.87 · 1m 18s

Honoured from a TTY too — kuzushi scan … --ci | tee run.log works.

PR comments

buildPrComment(summary, { repoName, runUrl }) (in src/report-pr-comment.ts) renders a GitHub-markdown block suitable for gh pr comment -F -. Includes verdict counts, exploitable badge, cost + duration, and a top-10 TP table with severity emojis.

Quality Gates

kuzushi scan <repo> --quality-gate         # fail CI on threshold violations
kuzushi scan <repo> --fail-on-tp           # fail if any high/critical TP is found
kuzushi scan <repo> --sarif results.sarif  # export SARIF for GitHub Code Scanning
kuzushi scan <repo> --ci                   # plain-text stream mode (no Ink)

Scan Presets

kuzushi scan <repo> --preset safe        # first-run friendly: context + secrets/crypto, $5 cost cap
kuzushi scan <repo> --preset fast        # semgrep only, no context/enrichment
kuzushi scan <repo> --preset standard    # semgrep + IRIS taint + secrets/crypto
kuzushi scan <repo> --preset deep        # + verification + threat modeling + systems hunt
kuzushi scan <repo> --preset glasswing   # + PoC + threat-informed hunting + frontier model

Key Features

Vendor-agnostic LLM runtime — Anthropic, OpenAI, Google, Groq, Mistral, and 15+ providers. Swap models at runtime with --model provider:modelId. Runs airgapped with Ollama.

Exploit verification — constructs concrete PoC payloads (SQL injection strings, XSS vectors, etc.) that prove exploitability, not just theoretical possibility.

IRIS-style taint analysis — LLM-driven CodeQL taint analysis (ICLR 2025). LLM selects CWE classes, writes CodeQL queries dynamically, labels candidates, generates TaintTracking configs, iteratively refines on failure.

Randori PASTA threat modeling — 4-stage PASTA analysis (objectives, scope, DFD, STRIDE threats) via Claude Code plugin. Threat leads injected into all detector prompts. ATT&CK, CAPEC, OWASP mapping.

Systems-level deep semantic hunt — finds bugs that survive decades of review: integer overflow, sentinel collisions, signed/unsigned comparison, buffer overflows, use-after-free in protocol state machines, unsafe Rust blocks. LLM writes CodeQL queries using range analysis, not TaintTracking.

Multi-strategy analysis — 2-4 analytical approaches per vulnerability class with confidence boosting when strategies agree. Auto-generates Semgrep rules from confirmed findings.

Auto-patch with closed-loop verification — generates patches in disposable worktrees, validates, re-runs the scanner to confirm the vulnerability is gone.

Crypto behavioral testing — generates and executes behavioral test harnesses in Docker for crypto misuse: timing side-channels, ECB mode, weak hashes, weak PRNGs.

Language-tuned detection — auto-detects languages and frameworks, injects language-specific sinks, safe patterns, few-shot examples, anti-hallucination constraints. 8 ecosystems: C/C++, Java/Kotlin, Python, Go, JS/TS, Rust, PHP, Ruby.

Resumable runs — checkpoints to SQLite. --resume picks up where you left off.

Interactive terminal UI — React+Ink-powered live display with pipeline progress tree, spinners, trophy screen for confirmed exploits. REPL during scans (pause, skip, inspect). First-run setup wizard. Falls back to plain text in non-TTY. Built on a unified primitive library (src/ui/primitives/: SelectList, TextInput, ConfirmDialog, Table, Breadcrumb, KeybindFooter, ExpandableSection, Divider, MultilineText) with shared hooks (src/ui/hooks/: useBoundedIndex, useFocusTrap, useTerminalSize, useCursorVisibility, useExpanded, useKeybindings) for consistent focus, keyboard navigation, and resize handling.

Incremental scanning — skips re-triage for unchanged findings. Dependency-aware invalidation via import graph.

Audit logging — JSONL audit trail of every agent decision.

Scan

kuzushi scan <repo>                        # scan with defaults
kuzushi scan <repo> --tasks codeql
kuzushi scan <repo> --tasks semgrep,codeql
kuzushi scan <repo> --severity ERROR
kuzushi scan <repo> --max 20
kuzushi scan <repo> --model anthropic:claude-sonnet-4-6
kuzushi scan <repo> --task-model triage=openai:gpt-4o
kuzushi scan <repo> --fresh
kuzushi scan <repo> --resume

Verification & PoC

kuzushi scan <repo> --verify
kuzushi scan <repo> --verify --poc-harness
kuzushi scan <repo> --verify --poc-harness --dynamic-analysis

Multi-Strategy & Code Graph

kuzushi scan <repo> --multi-strategy
kuzushi scan <repo> --multi-strategy-full
kuzushi scan <repo> --code-graph

Auto-Patch

kuzushi scan <repo> --verify --auto-patch
kuzushi scan <repo> --auto-patch --patch-verify-depth full

Diff-Aware & Crypto

kuzushi scan <repo> --taint-diff-base main
kuzushi scan <repo> --crypto-behavioral-test

Output

kuzushi scan <repo> --output report.md
kuzushi scan <repo> --sarif results.sarif
kuzushi scan <repo> --json results.json
kuzushi scan <repo> --csv results.csv
kuzushi scan <repo> --junit results.xml
kuzushi scan <repo> --stream
kuzushi scan <repo> --audit-log

Run History

kuzushi runs list                          # 50 most recent runs
kuzushi runs list --status interrupted     # only resumable runs
kuzushi runs show <runId> --costs          # details + cost breakdown
kuzushi runs show <runId> --json           # JSON output for tooling

Run Mode

kuzushi run sast:scan ./repo --json
kuzushi run triage:run fingerprint=abc123 --json
kuzushi run verify:finding fingerprint=abc123 --quiet
kuzushi run findings:list severity=critical,high --json

Patch

kuzushi patch <repo> --fingerprint <fp>
kuzushi patch <repo> --fingerprint <fp> --build-cmd "npm run build" --test-cmd "npm test"

Config

kuzushi config get
kuzushi config set model anthropic:claude-sonnet-4-6
kuzushi config set tasks semgrep,agentic
kuzushi config validate --repo .
kuzushi config path

| Key | Default | Description | | --- | --- | --- | | model | anthropic:claude-sonnet-4-6 | Default LLM model for all tasks and stages | | tasks | ["semgrep"] | Enabled task IDs, in execution order | | taskConfig | { semgrep: {...}, triage: {...}, ... } | Per-task config blocks keyed by task ID or stage ID | | severity | ["ERROR","WARNING"] | Semgrep severity filter | | excludePatterns | ["test","tests","node_modules",...] | Directories/globs to skip | | triageConcurrency | 5 | Parallel LLM triage calls | | scanMode | "concurrent" | Task execution mode | | verify | false | Enable proof-of-exploitability verification | | pocHarness | false | Enable PoC harness generation | | cryptoBehavioralTestEnabled | false | Enable crypto behavioral testing | | codeGraphEnabled | true | Enable LLM code graph | | multiStrategyMode | "off" | Multi-strategy analysis (off, adaptive, full) | | autoPatchEnabled | false | Enable auto-patch generation | | incrementalCache | true | Enable incremental scanning | | auditLog | false | Write JSONL audit files |

Stage model overrides via taskConfig:

| Key | Purpose | | --- | --- | | taskConfig.triage.model | Model for triage agents | | taskConfig.verify.model | Model for verification agents | | taskConfig.poc-harness.model | Model for PoC harness generation |

Global config: ~/.kuzushi/config.json. Project overrides: <repo>/.kuzushi/config.json. CLI flags override config.

Environment Variables

| Variable | Required | Description | | --- | --- | --- | | ANTHROPIC_API_KEY | When using anthropic:* models | Anthropic API key | | OPENAI_API_KEY | When using openai:* models | OpenAI API key | | GEMINI_API_KEY / GOOGLE_API_KEY | When using google:* models | Google API key |

The codeql scanner requires the CodeQL CLI installed separately (not auto-downloaded).

# Via GitHub CLI (recommended):
gh extension install github/gh-codeql && gh codeql install-stub

# Or download directly from:
# https://github.com/github/codeql-cli-binaries/releases

CodeQL is opt-in. Enable it:

kuzushi scan <repo> --tasks codeql
kuzushi scan <repo> --tasks semgrep,codeql
kuzushi config set tasks semgrep,codeql

Architecture

See VISION.md for the full architecture vision, module system design, workspace/knowledge graph, intel layer, governance model, and implementation roadmap.

Terminal UI layer

The Ink React frontend lives in src/ui/:

| Path | Role | | --- | --- | | src/ui/App.tsx | Root Ink component; dispatches on UIState.mode (preflight, running, summary, review, done, shell). | | src/ui/state.ts | UIStore — observer-pattern state + useSyncExternalStore binding. | | src/ui/render.ts | Entry point; TTY detection and Ink mount / plain fallback. | | src/ui/plain-renderer.ts | Non-TTY subscriber that prints delta-based updates. | | src/ui/tokens.ts | Semantic color/typography tokens + SPACING / COLUMN_WIDTHS constants. | | src/ui/format.ts | Terminal formatting utilities — progress bars, cost/duration, column padding, ANSI-aware truncation (truncateEnd, truncateMiddle, padCell, visibleWidth). | | src/ui/error-format.ts | Ink-free error classification (classifyError, formatError, suggestNextStep) consumed by ErrorCard. | | src/ui/primitives/ | Reusable building blocks: SelectList, TextInput, ConfirmDialog, Table, Breadcrumb, KeybindFooter, ExpandableSection, Divider, MultilineText. | | src/ui/hooks/ | Behavioral hooks: useBoundedIndex, useFocusTrap, useTerminalSize (SIGWINCH-aware), useCursorVisibility, useExpanded, useKeybindings. | | src/ui/components/ | Feature components (pipeline, findings, setup wizard, copilot shell) composed from the primitives above. |

Styling discipline: components import from tokens (never chalk directly) and lay out with Ink <Box> flexbox properties (flexDirection, justifyContent, gap, padding, margin) rather than string-padding tricks.

License

MIT