Wythe

Why (?) → Therefore (∴) — Generalizable 3-tier architecture verifier, cross-boundary lineage solver, interactive 3D WebGL latticework visualizer, and fail-closed CI gate built around three masonry wythe invariants:

1. Database holds truth — Relational schemas (PostgreSQL, MySQL, SQLite via SQLAlchemy 2.0 + Alembic, Prisma, Drizzle ORM, Django ORM, Rust sqlx/Diesel/SeaORM, or raw SQL DDL/sqlc + optional read-only catalog probes) own domain policy, thresholds, temporal validity, and write-lane guards, while Redis keyspaces and worker queues are modeled explicitly as ephemeral stores/lanes rather than durable shadow truth.
2. Backend manipulates truth — Services, background workers, solvers, and routers (Python/FastAPI, TypeScript/Node/Express/Hono/Fastify/NestJS/Next.js/SvelteKit, Python/Django/DRF/Ninja, Go net/http/chi/gin/echo, Rust axum/actix-web/rocket/Tauri) execute mechanisms over database rows behind explicit transactional service/SQL doors without embedding shadow policy literals or host-clock drift.
3. Frontend displays truth — UI surfaces (Next.js, React/Vite/TanStack Router/Remix, Vue 3/Nuxt, Svelte 5/SvelteKit, Rust WASM Leptos/Dioxus/Yew + Tauri invoke()) bind to typed contracts, centralized clock utilities, and WCAG-accessible markup without inventing client-side policy maps or unbacked HTTP/IPC calls.

Wythe supports 18 full-stack profiles out of the box via --profile auto, pairs Python's native ast with an optional Tree-sitter CST grammar engine (wythe[treesitter] for TypeScript/TSX, JavaScript, Rust, and Go), traces background worker & scheduled beat queues (Celery / Beat, BullMQ, Asynq), enforces WCAG accessibility semantics (DISP-005), renders both Simple Solids and 120 fps Breathing Atomic Wythe Polyhedra (with adaptive System | Dark | Light polarity and custom user palettes), and self-dogfoods its own 3-tier codebase (wythe gate --strict wythe passes with zero blocking and zero warning findings).

Instant Usage (uvx / uv)

Run Wythe directly against any repository without polluting project dependencies (add [treesitter] to enable prebuilt Tree-sitter CST wheels for TS/TSX, JS, Rust, and Go):

# Instant CLI gate & lineage scan from PyPI (once published) or directly from GitHub
uvx "wythe[treesitter]" gate --strict /path/to/repo
uvx --from "git+https://github.com/Euda1mon1a/wythe[treesitter]" wythe scan /path/to/repo
uvx --from "git+https://github.com/Euda1mon1a/wythe[treesitter]" wythe gate --strict /path/to/repo

# Launch single-port API + interactive 3D WebGL UI on http://127.0.0.1:8780 (no Node.js runtime needed)
uvx --from "git+https://github.com/Euda1mon1a/wythe[treesitter]" wythe serve /path/to/repo

# Or install persistently as an isolated CLI tool
uv tool install "git+https://github.com/Euda1mon1a/wythe[treesitter]"
wythe serve .

GitHub Actions Integration

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- uses: Euda1mon1a/wythe@main
  with:
    mode: diff
    base-ref: origin/main
    sarif-file: wythe.sarif.json

Persisted Rule Catalog (atlas_rule_policies)

Rule severity, enablement, gate-blocking behavior, and effective-date windows live in database truth (atlas_rule_policies) and round-trip cleanly to Git via .wythe/governance.json:

CLI Commands

# Scan any supported full-stack repository (--profile auto)
wythe scan /path/to/repo --json report.json --sarif report.sarif.json

# Optional metadata-only live DB & Redis keyspace probes (zero row or value reads)
wythe scan /path/to/repo \
  --dsn "postgresql://readonly@127.0.0.1:5432/appdb" \
  --redis-dsn "redis://127.0.0.1:6379/0"

# PR diff gate & directional 3-tier blast-radius slice
wythe diff /path/to/repo --base origin/main --sarif diff.sarif.json

# Git-portable governance bundle (.wythe/governance.json) for CI runners
wythe export-config /path/to/repo
wythe gate --sync-config /path/to/repo

# Single-port API + 3D WebGL UI (auto-registers target directory on startup)
wythe serve /path/to/repo --host 127.0.0.1 --port 8780

First-Class LLM & Human ↔ Vision/MCP Bridge (On-Device AI, Streamable HTTP MCP, OpenAPI & WebMCP)

Full JSON scans on large repositories span megabytes; Wythe exposes five zero-copy-paste Human ↔ LLM surfaces spanning bare-minimum on-device models through remote Tailnet agents:

1. Zero-Setup On-Device AI (Ask AI [A] / ⌘J, /api/v1/ask) — Zero-cloud, zero-API-key cascade with real-time Three.js camera-frustum & screen-color telemetry, 1024px WebP vision frames, and rolling multi-turn sessions across:
   • Apple Intelligence (apple): macOS 26+/27 native FoundationModels helper (arm64-apple-macos26.0, serialized with modelmanagerd backoff).
   • Chrome Built-In (chrome): Client-side browser LanguageModel (Gemini Nano via Prompt API, including 1-click download and multimodal WebGL <canvas> vision when enabled).
   • Local OpenAI /v1 (local): Auto-probes browser-host & server loopback /v1/models & /v1/chat/completions (:8080/:8084/:8083 MLX, :11434 Ollama, :1234 LM Studio) without triggering weight reloads.
2. Streamable HTTP MCP (POST /api/v1/mcp & GET /api/v1/mcp) + Stdio MCP (wythe mcp) — Connect local or remote Tailnet coding agents (http://<host>:8780/api/v1/mcp) with zero local install.
3. OpenAPI 3.1 (/openapi.json) + Remote CLI (wythe focus --remote <url>) — Universal HTTP tool/Actions compatibility plus cross-host CLI X-Ray inspection.
4. In-Tab WebMCP (navigator.modelContext & window.wythe) — Exposes whatIsThis(), getLineageCone(query), selectNode(nodeId), and ask(question) directly to browser agents and extensions.
5. Token-Budgeted llms.txt & Lineage Cone Slicer — Deterministic ~2,000-token repo maps and ~300-token 3-tier cones.

# 1. Token-budgeted llms.txt pointer map (~2,000 tokens regardless of repo size)
wythe llms /path/to/repo --max-tokens 2200 --out llms-wythe.txt

# 2. Surgical ~300-token 3-tier Lineage Cone around any table, file, route, or queue
wythe context /path/to/repo audit_exports
wythe context /path/to/repo /api/v1/scans --json

# 3. Zero-copy-paste Human <-> LLM Bridge (local state or remote private/Tailnet server)
wythe focus
wythe focus --remote http://100.64.0.10:8780

# 4. Zero-dependency read-only stdio MCP server (or connect directly to http://127.0.0.1:8780/api/v1/mcp)
wythe mcp

MCP client configuration (Stdio or Streamable HTTP — exposes wythe_what_is_this, wythe_list_targets, wythe_overview, wythe_lineage_cone, wythe_blast_radius, wythe_findings):

{
  "mcpServers": {
    "wythe-http": {
      "url": "http://127.0.0.1:8780/api/v1/mcp"
    },
    "wythe-stdio": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Euda1mon1a/wythe[treesitter]", "wythe", "mcp"]
    }
  }
}

Supported Multi-Language & Multi-DB Adapters

Architecture & Ecosystem Docs

• docs/architecture/ecosystem-and-positioning.md — Ecosystem comparison (tach, import-linter, dependency-cruiser, sqllineage, OpenLineage, CodeCharta, Semgrep) and pairing tach + Wythe in CI.
• docs/architecture/multi-language-extensibility.md — Language-neutral intermediate contract, adapter matrix, read-only DB/Redis probes, and --profile auto detection.

Local Development

make types      # Export OpenAPI 3.1 -> generate TypeScript schema types -> run tsc --noEmit
make build-ui   # Build static Next.js export into backend/app/ui_dist
make lint       # Run ruff check
make test       # Run serial pytest suite
make gate       # Run strict self-dogfood 3-tier + WCAG gate
make package    # Build standalone wheel & sdist containing bundled 3D WebGL UI

License

MIT — see LICENSE.