Konoha

-CLI-orange?logo=raspberrypi&logoColor=white) -red?logo=kalilinux&logoColor=white)

☕ Support & Buy Me a Coffee

If you find Konoha helpful and want to support ongoing development, maintenance, and coffee-fueled coding sessions, consider buying me a coffee!

📸 Preview

• Latest Release: v2.2.10 — Supply-chain hardening, Playwright Edge script excision, SheetJS CF seed neutralization, hash-js replacement with @noble/hashes, and Socket.dev policy configuration.
• Latest Security Compliance: Google Policy Compliance v2.2.10 — Audited & Certified (2026-10-27)

🌟 Master Architectural Feature Matrix

📖 Setup & Usage Guides

• Konoha Bridge Router Guide
• Web Configuration UI Guide
• Antigravity IDE Setup Guide
• Antigravity CLI Setup Guide
• Cursor IDE & CLI Setup Guide
• Claude Code Setup Guide
• SearXNG Multi-Source Search
• Adding Skills from skills.sh
• Token Savings Benchmarks
• Troubleshooting Guide
• System Architecture

⚠️ The Problem & 💡 The Solution

Architectural Comparison: The Vibe Coding Dilemma vs. Autonomous Agentic Rigor

[!TIP] Optimization Result: Konoha and Semble retrieve bounded, task-relevant context instead of full skill trees. See BENCHMARK.md for historical snapshots and reproducible konoha savings output; latency and cost reductions are environment-dependent and are not guaranteed.

⚙️ How It Works

For a detailed breakdown of Konoha's internal mechanics, including system layers, data flows, and query lifecycle sequence diagrams, please see the System Architecture Guide.

Konoha subagents execute inline via direct structured MCP tool arguments (task, context, constraints, skills, taste_dials) using direct specialist tools (jonin, anbu, kage, genin, etc.):

• Eliminates Scratch Loops: Replaces multi-step disk file reading (delegate.md and result.md) with direct in-memory structured context passing.
• Auto-Checkpointing (report_from_agent): Automatically distills key architectural learnings and records them into persistent project memory upon task completion.

Jonin combines Konoha's 3D component architecture with Taste-Skill v2 (Leonxlnx/taste-skill) design directives:

• Deterministic High-End Typography: Enforces Geist, Cabinet Grotesk, Outfit, Satoshi, and Clash Display. Generic Inter defaults are forbidden.
• Cinematic Chapter Pacing: Enforces generous vertical section rhythm (py-24, py-32, or py-48).
• Strict CSS Grid: Implements CSS Grid (grid-cols-12, bento grids) with bounded max-w-[1400px] containers instead of flaky flexbox percentages.
• Mobile Viewport Stability: Uses min-h-[100dvh] to eliminate layout jumps on mobile address bar resizing.
• Zero-Emoji Policy: Pure SVG vector iconography (Lucide, Radix, Phosphor); zero emojis in production UI.
• Configurable Taste Dials: DESIGN_VARIANCE (1-10), MOTION_INTENSITY (1-10), VISUAL_DENSITY (1-10).

• Workspace Stack Profiler: Automatically detects frameworks (Next.js, SvelteKit, Nuxt 3, Angular), styling engines (Tailwind v4, CSS Modules), and package managers (pnpm).
• Project-Scoped Memory: Persists architectural invariants, rules, and episodic learnings per repository workspace in SQLite (~/.konoha/konoha.db).
• Zero Session Amnesia: Context and invariants are preserved and automatically injected across consecutive sessions.
• CLI Commands: konoha project context, konoha project list, konoha project add, konoha project memory.

Konoha integrates hybrid semantic retrieval combining SQLite FTS5 BM25, IBM Granite 97M Multilingual Embeddings (ONNX), and MS MARCO MiniLM Neural Cross-Encoder Reranker:

• Offline Bundled Models: Both embedding and neural reranker models are pre-bundled directly in assets/models/ (<100 MB each), enabling 100% offline installs and zero-download instant execution.
• Dual-Stage Reranking & RAG Retrieval: Combines sub-millisecond Reciprocal Rank Fusion (RRF, k=60) for candidate ranking with neural cross-encoder passage reranking (searchChunksRAG()) for high-precision RAG context retrieval.
• Cross-Lingual Recall: Queries in multilingual text retrieve the relevant skill documentation with 97.5% Recall@5 and 0.885 MRR@5.
• Zero-Config Default & Opt-in Semantic Search: By default, Konoha runs zero-config with ultra-fast SQLite FTS5. Semantic search and neural reranking are optionally enabled via KONOHA_SEMANTIC_SEARCH=1.
• Graceful Fallback: If models are unavailable, semantic search is toggled off, or the host SQLite binary lacks compiled FTS5 (e.g. Windows), retrieval seamlessly falls back to FTS5 / LIKE search without crashing.
• 4-Tier Embedding Feature Deduplication: Markdown heading-aware chunk hashing, in-memory _EMBED_CACHE (512 entries), database-level binary blob reuse across skills, and candidate nearest-chunk deduplication.
• Persistent Persona & Project Memory: Idempotent memory storage preventing duplicate SQLite rows, zero-hallucination factual extraction, and auto-compact turn-based prompt badges (< 120 tokens on turn >= 2).
• Cross-Platform agent-browser Lifecycle: Automated multi-package-manager detection and self-healing doctor auto-repair across Windows (agent-browser.cmd), Linux, and macOS.

All non-trivial work on a Konoha-configured host MUST flow through the Konoha MCP and Semble MCP tools and be delegated to a konoha subagent — never executed solo by the main orchestrator.

• Skill lookup (konoha.find_skills, konoha.find_skill, konoha.get_skill) — always via konoha MCP, never semble. Project-scoped skills (.agents/skills, skills/, .cursor/skills, .gemini/skills) auto-migrate into skills.db.
• Codebase search (semble.search, semble.find_related) — always via semble MCP, never grep/rg/find.
• Bounded file reads — konoha.read_file_head / read_file_range / file_info / token_efficient_grep, never generic Read / Grep / Glob / shell cat/head/tail.
• Zero-AI-Slop Code Quality — aislop.aislop_scan, aislop.aislop_fix, aislop.aislop_why for code hygiene and Kage review gating.
• Project Knowledge Discovery — inspect project-local README.md, docs/, CONTRIBUTING.md, .cursorrules, .clauderules, and canonical project skills (.agents/skills, skills/) before executing code.
• Package Manager Mandate — ALWAYS use pnpm (never standalone npx or npm) for all JS/TS scaffolding, installs, and builds.
• Subagent routing — match the task domain to a ninja agent:
  • @genin — codebase exploration, codepath tracing, ADHD-friendly output shaping (genin-skill/i-have-adhd)
  • @kage — architecture, security, deep analysis, anti-slop delivery gate (kage-skill/antislop*, kage-skill/drawio-skill)
  • @chunin — web research, documentation synthesis, citations
  • @jonin — UI/frontend across 4 frameworks (SvelteKit, Next.js 16, Nuxt 3, Angular v19+) using pnpm + Tailwind v4, React/Next.js best practices (jonin-skill/react-patterns, react-performance, react-testing), ADHD output shaping (jonin-skill/i-have-adhd); fixes UI bugs found by QA automation (never calls QA tools)
  • @anbu — backend development, bug fixing, QA automation & E2E verification (anbu-skill/qa-automation, agent-browser + Playwright), DevOps & cloud infrastructure, Helm chart scaffolding (anbu-skill/helm-chart-scaffolding), multi-stage Dockerfiles (anbu-skill/multi-stage-dockerfile), ADHD output shaping (anbu-skill/i-have-adhd), & dev/local penetration testing
  • @tokubetsu-jonin — technical writing, docs, runbooks, READMEs

The main orchestrator MUST NOT execute implementation tasks itself — it only coordinates and delegates. Trivial edits on a known file may run inline; everything else routes through a subagent.

🏗️ Multi-Agent Architecture: MCP Tools Orchestrator

Konoha uses an MCP Tools Orchestrator Model (Single-Thread Persona Adoption via MCP Tools), specifically engineered to deliver maximum performance, complete cross-IDE portability, and 83–98% token savings.

Canonical editable diagram: 08 Orchestrator Task Artifact Flow · Complete Workflow Architecture · Diagram manifest.

---
title: Konoha Orchestration and Execution Flow
config:
  theme: base
  themeVariables:
    darkMode: false
    background: '#ffffff'
    mainBkg: '#ffffff'
    primaryColor: '#ffffff'
    primaryTextColor: '#0f172a'
    primaryBorderColor: '#3b82f6'
    lineColor: '#334155'
    arrowheadColor: '#334155'
    secondaryColor: '#f8fafc'
    tertiaryColor: '#ffffff'
    fontFamily: 'Inter, system-ui, -apple-system, sans-serif'
    fontSize: '13px'
  flowchart:
    nodeSpacing: 45
    rankSpacing: 55
    padding: 24
    wrappingWidth: 380
---
flowchart TB
    Prompt["User Prompt / Resume"] --> Orchestrator["Primary Orchestrator<br/>(Main Agent)"]
    Orchestrator --> Context["1. Project Memory & Context<br/>(Detect stack & auto-inject invariants)"]
    Orchestrator --> Discover["2. Discover & Resolve Skills<br/>(konoha.find_skill · konoha.use_skills · semble.search)"]
    Context --> Delegate["3. Structured MCP Delegation<br/>(jonin / anbu / kage)"]
    Discover --> Delegate
    Delegate --> Agent["4. Specialist Ninja Agent<br/>(genin · kage · jonin · anbu · chunin · tokubetsu)"]
    Agent --> Report["5. Structured Result & Checkpoint<br/>(report_from_agent)"]
    Report --> Review["6. Kage Review Gate<br/>(Zero-AI-slop pre-gate: aislop_scan + anti_slop + 100% verification)"]
    Review --> Synthesize["7. Sannin Synthesizes Report<br/>(Final report & response)"]
    Synthesize --> Response["Synthesized Response"]

    linkStyle default stroke:#334155,stroke-width:2px;
    classDef userNode fill:#ffffff,stroke:#3b82f6,color:#0f172a,stroke-width:2px;
    classDef orchNode fill:#ffffff,stroke:#8b5cf6,color:#0f172a,stroke-width:2px;
    classDef mcpNode fill:#ffffff,stroke:#10b981,color:#0f172a,stroke-width:2px;
    classDef reviewNode fill:#ffffff,stroke:#f59e0b,color:#0f172a,stroke-width:2px;
    class Prompt,Response userNode;
    class Orchestrator,Synthesize,Delegate,Agent orchNode;
    class Context,Discover,Report mcpNode;
    class Review reviewNode;

Architectural Comparison

Why Konoha Uses the MCP Tools Orchestrator Model

1. 🚀 Zero Process Cold-Start: Subagents execute in-flight as standard MCP tools without waiting for multi-second process initialization.
2. 💡 Direct Structured Context: Passes tasks, constraints, skills, and taste dials in-memory via MCP tool arguments without filesystem disk-thrashing loops.
3. 🛡️ Seamless Conversation Resumption: Re-evaluates state and enforces subagent delegation workflow on every resume or multi-turn request.

🔄 Structured Delegation and Legacy Task Fallback

Konoha passes task, context, constraints, skills, taste_dials, and project_path directly to subagent MCP tools. Hosts that cannot send structured arguments may use isolated legacy artifacts:

Structured reports use report_from_agent to return summaries, changed files, and project-scoped learnings. Legacy task directories remain outside the project workspace and are cleaned after use.

Skill Resolution

When a subagent runs, run_mcp_agent resolves skills in three layers:

1. Exact match — agents.skills (per-agent YAML) is queried against skills.skill_name and references.name.
2. Fuzzy match — if a skill name has no exact hit, Levenshtein distance ≤ 3 finds close names. Example: devsecops-enginer → devsecops-engineer.
3. Prompt-driven autoload — when the agent's skills list is empty, the prompt is tokenized and matched against skill_name + the first 200 chars of each skill's content. The top 3 token-coverage matches are auto-loaded and embedded into the agent instructions.

The mismatch is reported on stderr (fuzzy-resolved skill 'x' -> 'y') so the orchestrator can spot recurring typos and update the YAML.

Workspace Hygiene

Transient subagent scratch directories (delegate.md, plan.md, result.md, etc.) are written outside the project tree at ~/.konoha/tmp/<client>/<session>/scratch/tasks/<task_id>/. If ~/.konoha is not writable, the resolver falls back to /tmp/konoha-<pid>-<ts>/. The path is never rooted under WORKSPACE_ROOT, so git add . cannot accidentally commit agent scratch files. This is enforced by src/mcp/runtime_state.js and covered by tests/test_scratch_path.js.

🚀 Quick Start

⚡ 1-Command Global Install (Recommended via npm / pnpm)

Install Konoha globally from npm and initialize all 8 agentic coding clients in one command:

# Recommended: Install globally via npm (or pnpm add -g konoha-mcp)
npm install -g konoha-mcp

# Initialize all coding clients, SQLite FTS5 database, and Antigravity bridge extension
konoha init

Or run directly without global installation via npx / pnpm dlx:

npx konoha-mcp init
# or: pnpm dlx konoha-mcp init

[!IMPORTANT] Breaking Changes Notice (Post-v2.1.17):

• Direct Specialist MCP Tools: Deprecated delegate_to_<agent> MCP tool wrappers are removed in favor of direct specialist tools (sannin, genin, kage, chunin, jonin, anbu, tokubetsu_jonin, akatsuki). External callers using legacy delegate prefixes on report_from_agent are rejected.
• Canonical CLI Syntax (27 Removed Aliases): 27 legacy undocumented CLI aliases have been pruned: embeddings, detect_ai, ai-detector, detect_docs, docs-detector, detect-doc, personas, memories, spirit, will-of-fire, projects, tasks, web-search, inbox, install, memory, setup, update, saving, agents, tg, tunnels, prune, context, persona, searxng, sdlc. Canonical subcommands (konoha task, konoha data, konoha skill, konoha tunnel, konoha agent, konoha status, etc.) are strictly enforced.
• Operational Database Management (konoha data): Added canonical subcommands konoha data backup [path], konoha data rebuild-fts, and konoha data prune [--retention <days>]. Note: konoha data prune deletes immediately, with no confirmation and no automatic backup (take konoha data backup first), and "alltime" stats count only data since the last prune.
• Mandatory Ingress PIN & Security: Quick and custom tunnels strictly require an authentication PIN (auth_pin) when Cloudflare Zero Trust headers are absent; unauthenticated named tunnel access (open_named) is removed.
• Session Sandbox Isolation Contract (Decision A): Strict per-session isolation partitions episodic memories by session_id; agent-facing queries without a session ID do not receive foreign episodic memories while retaining workspace project rules. Administrative listings and Web UI pass allSessions: true.

📦 Source / Clone Onboarding

For developers building from source or cloning the Git repository:

# 1. Clone repository and enter directory
git clone https://github.com/andycungkrinx91/konoha.git
cd konoha

# 2. Install dependencies via pnpm
pnpm install

# 3. Execute one-command cross-client initialization
node bin/cli.js init --yes --force

(Optional: Run pnpm link --global or npm link so team members can run konoha status, konoha test, or konoha migrate directly from any terminal).

Automatic Dependency & Environment Provisioning

When installing Konoha, all required Node.js libraries, SQLite FTS5 database schemas, file tools MCP, and client configs are automatically provisioned:

• 📦 Node.js dependencies: Pure zero-native runtime with minimal production dependencies (@bufbuild/protobuf). Built on Node.js built-in node:sqlite (FTS5 + WAL) and native styling/prompting. Zero native compilation, zero build toolchain.
• 🗄️ SQLite FTS5 Skills Database: Automatically compiled and initialized at ~/.konoha/konoha.db (legacy skills.db is auto-migrated on first open).
• 🔮 Semble Codebase Search MCP: Auto-configured via uvx for zero-setup deep code discovery.
• ⚙️ File Tools & Prompt Hooks: Deployed automatically to ~/.konoha/ and registered with client IDE config schemas.
• 🌉 Local LLM Proxy Gateway: Embedded local OpenAI-compatible bridge router on port 19999 for token-efficient model multiplexing.

[!IMPORTANT] Zero-Prompt Auto-Setup:

Cross-Platform: Works on Linux, macOS, and Windows (native and WSL). Supports nvm on all platforms.

Get Konoha up and running in under 2 minutes:

# 1. Zero-install one-liner via npx (or: pnpm dlx konoha-mcp init)
npx konoha-mcp init

# 2. Re-index skills & synchronize vector embeddings (IBM Granite + MS MARCO MiniLM Reranker)
konoha migrate --clean --rebuild-embeddings
# (or simply: konoha embed)

# 3. Verify the MCP server connection works
konoha test

# 4. Check installation status and index database statistics
konoha status

[!NOTE]

📋 Requirements

• Node.js ≥ 22.16.0 (via nvm, Homebrew, or system package; pure Node.js runtime with built-in node:sqlite + FTS5, zero Python dependency)
• Agent skills in ~/.agents/skills/ (with SKILL.md files); Konoha indexes and serves skill content through SQLite FTS5 without filesystem mirrors
• Cross-platform: Linux, macOS, Windows (native and WSL)

🛠️ CLI Commands

To run all commands simply as konoha <command>, install the package globally:

npm install -g konoha-mcp
# or: pnpm add -g konoha-mcp

Once installed, the following CLI commands are available:

🔄 8-Phase Multi-Agent Workflow Engine

Konoha structures every development task into an autonomous 8-phase state machine coordinated by sannin and validated by kage:

1. route (✧ Sannin): Runs Definition-of-Readiness (DoR) validation and registers the root task container in SQLite sdlc_tasks.
2. explore (⚑ Genin): Read-only reconnaissance mapping codepaths, architecture boundaries, and dependencies (findings.md).
3. plan (◎ Kage): Evaluates exploration findings, defines decoupled subtasks (- [agent]: task), registers unit subtasks in SQLite sdlc_tasks, and detects web research needs.
4. research (▫ Chunin): Performs targeted web queries and documentation verification when requested by the Kage plan (needs_research: true).
5. execute (♦ Jonin / ♠ Anbu): Dispatches implementation tasks, executes framework-native builds/lints, runs QA automation loop for browser/E2E tasks owned exclusively by Anbu (see QA Automation Architecture), and records verifiable validation evidence.
6. document (⬡ Tokubetsu-Jonin): Generates human-authentic documentation, API specifications, runbooks, and changelogs (final_docs.md).
7. review (◎ Kage Gate): Mandatory Two-Step Zero-AI-Slop Gate (100/100 target) + SDLC subtask completion check + security audit + ≥98% confidence score. Autonomous remediation loop dispatched to anbu if slop findings exist.
8. synthesize & done (✧ Sannin): Synthesizes final_report.md with full evidence table, marks root container completed, purges transient scratch files, and delivers cleanly.

🏛️ Native SDLC Governance Layer

Konoha includes a built-in, medium-weight Software Development Life Cycle (SDLC) Governance Layer that operates natively without heavy external orchestration engines or external attestation frameworks:

• Definition-of-Readiness (DoR) Gate: Validates task substance, absence of unresolved placeholders (TODO, FIXME, ???), existence of referenced files, and domain alignment before dispatch. Configurable per project (dor_mode: advisory or dor_mode: enforced).
• Cross-Provider Review Independence: Detects when implementing subagents (anbu, jonin) and the reviewing subagent (kage) are served by different underlying LLM models/bridges, ensuring unbiased second-opinion evaluation.
• Two-Step Anti-Slop Delivery Gate: Step 1 aislop_scan (aislop scanner code hygiene) → Step 2 anti-slop rule review via the vendored antislop skill family (miqdadbadjuber/anti-slop), with a mandatory final Delivery Gate verification (ai_slop_clean: true and ai_slop_findings: 0).
• Autonomous Kage → Anbu Remediation Loop: Automatically converts anti-slop findings into actionable fix directives for anbu, re-verifying upon completion and bounded by the delegation-depth circuit breaker (slop_cycles > 7).
• Persistent SQLite Audit Trail (sdlc_tasks): Every task's DoR check, review mode, validation evidence, and anti-slop findings are permanently saved in SQLite WAL mode. Queryable via CLI (konoha task list, konoha task show <id>, konoha task slop <id>) and MCP tools (check_readiness, get_task_evidence, get_slop_findings).
• Web UI SDLC Tasks Dashboard (/tasks): Visual task explorer, interactive Definition-of-Readiness sandbox tester, task evidence & anti-slop audit modal, and live governance mode toggles (/api/v1/sdlc/*).
• Web UI skills.sh Registry & Vector Chunks Inspector (/skills): 3-mode search toggle (🔤 Local FTS5, ⚡ Neural Vector, 🌐 skills.sh Registry), 1-click installation from skills.sh with non-interactive execution (-y --agent '*'), automated multi-directory migration, and dedicated vector chunks inspection modal with 384d Float32 vector samples.

🧪 Token-Efficient QA Automation (agent-browser + Playwright)

Canonical editable diagram: 13 QA Automation Workflow · Full Architecture & Benchmarks · QA Test Checklist Konoha implements a token-efficient, bounded QA automation pipeline owned exclusively by anbu. By combining agent-browser interactive exploration (snapshot -i -c taking <500 tokens) with declarative flow specifications (tests/e2e/flows/*.json), deterministic qa_codify Playwright compilation, and bounded qa_e2e_run test execution (<2,000 characters output cap), Konoha achieves 92% token savings over traditional unconstrained browser trace dumps while completely eliminating fake-green test claims. Working artifacts are directed outside the workspace with automated retention (default 20 newest runs) and managed .gitignore isolation in git repositories (opt out via KONOHA_QA_GITIGNORE=0).

---
title: QA Automation Workflow
config:
  theme: base
  themeVariables:
    darkMode: false
    background: '#ffffff'
    mainBkg: '#ffffff'
    primaryColor: '#ffffff'
    primaryTextColor: '#0f172a'
    primaryBorderColor: '#8b5cf6'
    lineColor: '#334155'
    arrowheadColor: '#334155'
    secondaryColor: '#f8fafc'
    tertiaryColor: '#ffffff'
    fontFamily: 'Inter, system-ui, -apple-system, sans-serif'
    fontSize: '13px'
  flowchart:
    nodeSpacing: 45
    rankSpacing: 55
    padding: 24
    wrappingWidth: 380
---
flowchart TD
  P1["1 Route: Sannin, DoR, delegates"] --> P2["2 Explore: Genin, cites file:line"]
  P2 --> P3["3 Plan: Kage, task list per agent"]
  P3 -. needs_research .-> P4["4 Research: Chunin"]
  P3 --> Q1
  P4 --> Q1

  subgraph P5["5 Execute: QA loop, Anbu owns all evidence"]
    Q1["Anbu: explore with scoped snapshots"] --> Q2["Anbu: write flow file"]
    Q2 --> QV{"batch --bail passes?"}
    QV -- no --> Q2
    QV -- yes --> Q3["Anbu: qa_codify + qa_e2e_run = RED"]
    Q3 --> QF{"Where is the bug?"}
    QF -- backend or API --> QFB["Anbu: fix"]
    QF -- UI --> QFU["Jonin: fix UI code"]
    QFB --> Q4["Anbu: qa_e2e_run same test = GREEN"]
    QFU --> Q4
    Q4 --> Q5["Anbu: aislop_scan + aislop_fix"]
    Q5 -- "findings > 0" --> Q5
    Q5 -- clean --> Q6["Anbu: QA report + record run_id as evidence"]
  end

  Q6 --> P6["6 Document: Tokubetsu-jonin"]
  P6 --> P7["7 Review: Kage gate"]
  P7 --> G{"gate passes?"}
  G -- yes --> P8["8 Synthesize: Sannin final report"]
  G -- no --> RD["Workflow engine re-delegates: slop to Anbu or Jonin for UI files, QA failure to the fix owner"]
  RD --> QF
  RD -. "depth 7 or slop_cycles > 7" .-> STOP["Stop and ask the user"]

  linkStyle default stroke:#334155,stroke-width:2px;
  style P5 fill:#f8fafc,stroke:#cbd5e1,stroke-width:1.5px,color:#0f172a;

📱 Remote Access & Dual-Mode Telegram Automation

Canonical editable diagrams: 14 Remote Access & Telegram Inbound/Outbound · 15 Cloudflare Zero Trust Ingress & Prompt Queue
Dedicated Guides: Telegram Integration Guide · Cloudflare Tunnel Guide

Konoha features an autonomous Remote Access & Telegram Automation Engine that enables remote interaction, task dispatch, and real-time execution reporting directly from your mobile device or chat client without opening inbound firewall ports:

1. Dual-Mode Telegram Bot Engine (src/telegram/)

• One-Way Notification Mode: Automatically delivers structured task completion reports, execution duration, token reduction telemetry (83%-98%), and Kage Reviewer confidence scores over outbound HTTPS (getUpdates & sendMessage). When prompting locally on a workstation (laptop, terminal, IDE), any session passing Kage Final Gate Review (APPROVED with 100/100 score and ≥98% confidence) immediately dispatches an outbound Telegram notification to keep the developer updated remotely.
• Two-Way Remote Prompting Mode: Accepts commands directly from Telegram:
  • /session [number] — View and switch active target client sessions across Antigravity, Claude Code, Codex, Pi, OpenCode, and Command Code.
  • /session create <client> <path> — Register and immediately target a remote project directory.
  • /sh <cmd> — Execute shell commands directly in the active target workspace via interactive shell (bash -i -c) with full support for ~/.bashrc aliases (kubectl, kc*, helm, etc.) and security guardrails (isDangerousCommand blocking destructive patterns).
  • /kage, /anbu, /jonin, /genin, /chunin, /tokubetsu-jonin, /sannin — Direct subagent dispatch bypassing general triage.
  • /run <prompt> or plain text — Enqueue coding tasks into the unified prompt inbox.
  • /status, /savings, /cancel, /help — Live daemon telemetry, token savings metrics, and queue cancellation.
• Strict Security Invariant: Enforces a strict numeric chat_id whitelist (telegram_config.chat_id) dropping unauthorized messages immediately.
• Zero Emojis Standard: All notifications use clean bracketed tags ([KONOHA TASK REPORT], [SUCCESS], [QUEUED], [KAGE REVIEW GATE PASSED]).

2. Cloudflare Zero Trust Ingress Tunnel (src/tunnel/)

• Zero Inbound Ports: Background supervisor managing cloudflared (or ngrok) targeting Web UI port 1404 with automated binary provisioning and live URL detection (trycloudflare.com or custom domains).
• Mode A: Cloudflare Zero Trust Edge Authentication: Validates Cloudflare Access identity headers (Cf-Access-Authenticated-User-Email) with zero in-app PIN friction while maintaining unauthenticated local access on localhost:1404.

3. Unified Inbound Prompt Queue & Autonomous Worker (src/queue/)

• Atomic SQLite State Machine: Table prompt_queue tracks atomic prompt states (pending -> processing -> completed / failed / cancelled) with filesystem session mirroring (~/.konoha/inbox/<session>.json).
• Autonomous Queue Worker (src/queue/worker.js):
  • Operational Branch (0 LLM Tokens): Deterministic shell commands (kubectl, helm, docker, git, ssh, /sh, etc.) execute via interactive shell (bash -i -c) with 100% token elimination.
  • Autonomous AI Coding Branch: Natural language and complex coding tasks execute via headless agy -p ... with structured task telemetry and Kage Reviewer confidence reporting.

🛰️ Cross-Platform Install

Konoha runs on Linux, macOS, and Windows (native and WSL). Install commands are the same across all platforms:

pnpm add --global github:andycungkrinx91/konoha
konoha init

If konoha is not found after install:

• nvm on Linux/macOS: source ~/.nvm/nvm.sh then nvm use stable
• nvm-windows: nvm use <version> then pnpm add --global github:andycungkrinx91/konoha
• Windows without nvm: Reinstall Node.js from nodejs.org and ensure PATH is set

Full platform-specific guides: SETUP-CLI.md, SETUP-IDE.md, SETUP-CURSOR.md, SETUP-MCP-CLIENTS.md.

RTK (Rust Token Killer)

If rtk is installed on your system, Konoha auto-deploys RTK rules to all detected supported clients during konoha init:

RTK is installed automatically by konoha init when missing — no Rust toolchain required. The installer resolves the official rtk-ai/rtk binary via: cargo (cargo install --git https://github.com/rtk-ai/rtk), the official quick-install script (~/.local/bin, Linux/macOS), or the prebuilt Windows release. Konoha never uses the plain cargo install rtk crates.io package — that name belongs to an unrelated project (Rust Type Kit).

This instructs agents to prefix all shell commands with rtk <command>, reducing token consumption by up to 90% on common operations. If RTK cannot be installed (no network, no package manager), Konoha warns and continues without it.

Automatic Setup: During konoha init, Konoha runs rtk init -g globally to install the Claude Code hook automatically — no manual configuration needed. The RTK rule (~/.claude/rules/rtk.md) and hook are deployed alongside the MCP server setup.

🛰️ Konoha Bridge Router

Konoha ships a local Konoha Bridge Router on port 19999 that multiplexes requests across one or more inner LLM Bridges. The optional Antigravity IDE extension is refreshed from the live master branch into ~/.antigravity-ide/extensions/andycungkrinx91.konoha-bridge-master-universal/ and serves 127.0.0.1:1313; it is never installed on CLI-only hosts. The router forwards requests to a bridge based on the model name prefix <bridge-name>-<model-name>, strips inbound Authorization / x-api-key / x-konoha-gateway-* headers, and forwards to 127.0.0.1:<bridge-port>. Local clients never need to send an API key to the router.

Bridge configuration examples (bridges are registered manually by the user — the bridges table starts empty on install and is persisted in ~/.konoha/konoha.db via src/db_bridges.js):

Bridges are registered manually by the user (the tables start empty on install).

Examples:

• Ollama-compatible endpoint — default http://localhost:11434/v1
• OpenAI-compatible endpoint — provide your own API key

Configure bridges with konoha bridge create (interactive wizard). You can add multiple bridges for different providers:

Note: openai-oauth (device code flow) support was removed in v2.0.0. Use openai (API key) or openai-compatible bridges instead.

Model routing examples:

• my-ollama-llama3 → gateway strips my-ollama-, forwards llama3 to the inner bridge on its designated local port.
• gpt-api-gpt-4o → gateway routes to gpt-api bridge configured with your OpenAI API key.

Routing behavior: the gateway selects one enabled bridge per request and does not perform gateway-level round-robin retry after an error.

Full reference: docs/LLM-BRIDGE-GATEWAY.md

What Gets Installed

~/.gemini/
├── config/
│   └── mcp_config.json   ← konoha + semble + aislop MCP (Antigravity)
└── GEMINI.md              ← Orchestrator + subagent instructions

~/.konoha/
├── file_tools_launcher.js ← cross-platform Node resolver (preferred launcher)
├── file_tools_mcp.js      ← konoha MCP server (core skill+file ops)
├── file_tools_launcher.sh ← Shell wrapper for Cursor CLI sandbox
├── file_tools_router.js   ← In-process tool dispatch router
├── platform_utils.js      ← cross-OS path helpers
├── .node_exec_path        ← recorded Node path (auto)
├── server.js              ← Pure Node.js MCP server implementation
├── migrate.js             ← Pure Node.js migration script
├── vector_search.js       ← Semantic vector search & embedding engine
├── bridge/                ← Proxy Gateway bridge modules
└── skills.db              ← SQLite FTS5 database (+ `agents`, `bridges` tables)

~/.cursor/
├── mcp.json               ← konoha + semble + aislop MCP (Cursor)
├── agents/                ← Official seven ninja subagents; host selects models
├── hooks.json             ← sessionStart → cursor_bootstrap.js
└── cli-config.json        ← Cursor CLI MCP permissions

~/.claude/
├── settings.json          ← MCP permissions (all projects)
├── CLAUDE.md              ← Global orchestrator instructions (Claude Code)
├── agents/                ← Official seven ninja subagents
└── rules/
    └── rtk.md             ← RTK rule (if rtk binary detected)

~/.config/opencode/
├── opencode.json          ← OpenCode `mcp` configuration
├── AGENTS.md              ← Global OpenCode instructions
└── rules/rtk.md           ← RTK rule when installed

~/.commandcode/
├── mcp.json               ← Command Code `mcpServers` configuration
├── settings.json          ← Command Code permissions
└── rules/
    ├── konoha.md          ← Global Command Code instructions
    └── rtk.md             ← RTK rule when installed

~/.codex/
├── config.toml            ← Codex `[mcp_servers]` configuration (TOML)
├── AGENTS.md              ← Global Codex instructions
└── rules/
    └── rtk.md             ← RTK rule when installed

Re-indexing After Skill Changes

Run konoha migrate whenever you add, edit, or remove skills:

konoha migrate

konoha migrate --force

This updates skills.db, refreshes all system instructions, and repairs detected client MCP/rule/subagent integrations automatically. Cursor skill content remains SQLite/Konoha MCP-backed; no .cursor/skills/ mirror is created.

MCP Tools Available

After installation, Konoha registers 2 MCP servers that work together:

konoha — Skill Knowledge Search & Token-Efficient File Operations

The unified konoha server exposes 46 canonical tools for skill retrieval, bounded file operations, validated build specifications, project context, memory, search, migration, AI-website detection, QA automation, native document engineering, and subagent delegation workflows:

sannin(task?, context?, constraints?, skills?, taste_dials?, project_path?, task_dir?)

The Sannin routing workflow tool. Structured arguments are the primary path; task_dir remains a legacy fallback for hosts that require Markdown task artifacts.

Subagent Delegation Tools (kage, jonin, anbu, chunin, tokubetsu_jonin, genin, akatsuki)

Executes the specified subagent inline with structured task context, dynamic skill loading, project context, and optional Taste-Skill dials. In normal SDLC workflows, @akatsuki acts as the Blue-Team Security Review Gate (SAST, secrets leakage audit, dependency CVE verification, and Skill Guardian policy clearance before Kage review). For offensive pentest tasks, Akatsuki executes in isolated unprivileged containers (akatsuki-lab).

web_search(query, num_results?, search_depth?)

Enterprise-grade web search with multi-query decomposition, authoritative domain ranking, and Wikipedia OpenSearch fallback. Automatically invoked by chunin for deep research.

website_ai_detector(target)

Website AI-fingerprint detector (anonymiz.com-style). Scans a site directory, file, or http(s) URL for generator meta tags, Lucide icon packages, shadcn/ui component shapes, Vercel/Netlify hosting signals, AI-tool attribution comments, scaffold boilerplate, and generic template asset names. Returns a 0-100 score with evidence-backed findings — 0-20 = Human-Built (the PLAN_HUMAN_BUILT.md target band). Also available as konoha detect-ai <target> [--json] and in the Web UI at /detector.

website_ai_detector({ target: "./my-portfolio" })        → score, label, findings
website_ai_detector({ target: "package.json" })           → file mode (dependencies & patterns)
website_ai_detector({ target: "https://example.com" })   → URL mode (headers + HTML)

find_skill(keyword, limit?) (alias: find_skills)

Search skills by keyword using SQLite FTS5 full-text search with automatic project-scoped skill discovery and migration.

find_skill("anti-slop review")   → kage-skill/antislop references
find_skill("helm kubernetes")    → anbu-skill/helm-chart-scaffolding references
find_skill("react patterns")     → jonin-skill/react-patterns references
find_skill("adhd output")        → genin, anbu, jonin i-have-adhd references
find_skill("powerpoint")         → tokubetsu-jonin-skill/elite-powerpoint-designer

get_skill(name)

Get full content of a specific skill/reference by exact name.

get_skill("kage-skill/antislop")
get_skill("anbu-skill/helm-chart-scaffolding")
get_skill("jonin-skill/react-patterns")
get_skill("tokubetsu-jonin-skill/elite-powerpoint-designer")
get_skill("genin-skill/i-have-adhd")

use_skills(skills)

Accurately resolve and load skills directly by exact name or array of names from SQLite FTS5 database (konoha.db) with automatic fallback warning to local mirror directories (.agents/skills/ / ~/.agents/skills/). Ensures skill resolution accuracy and prevents skill misattribution.

use_skills({ skills: ["jonin-skill", "antislop-ui"] })

list_skills()

List all indexed skills and references with metadata.

optimize_report(keyword?)

Token-efficient skill discovery report with usage hints.

build_with_image_design(name, source_dir, framework)

Legacy alias for build_from_source, preserved for compatibility with existing clients.

build_from_source(name, source_dir, framework, taste_dials?)

Return a validated, side-effect-free source-fidelity specification for design mockups or reference source files (.png, .html, .tsx, .svelte, .vue, etc.). Supported frameworks are Next.js, Nuxt 3, SvelteKit, and Angular. Jonin implements the returned directives.

build_from_text(name, description, framework, taste_dials?)

Return a validated, side-effect-free premium specification for Next.js, Nuxt 3, SvelteKit, or Angular. Jonin implements the returned directives and runs the framework-native pnpm validation commands. Taste-Skill dials must be numeric values from 1 to 10.

Bounded File Tools

QA Automation Tools (anbu exclusive)

Quality & Governance Tools

[!IMPORTANT] All agents must use konoha for skill lookups, file reads, and line grep — not Cursor Read/Grep/Glob, Antigravity view_file, or shell cat/head/grep. Workflow: semble (semantic code search) → konoha (skills & file operations).

semble — Semantic Code Search (default)

The semble server provides AI-powered semantic code search across the entire codebase. Registered via uvx --from semble[mcp]@latest semble. Use semble instead of built-in grep/glob/find or Cursor Grep/Glob/SemanticSearch for codebase discovery.

Semble by MinishLab — @software{minishlab2026semble}. Uses ~98% fewer tokens than grep+read.

search(query)

Semantic search across the codebase — understands code meaning, not just text matching.

find_related(file_path)

Find files semantically related to a given file — useful for understanding dependencies and impact.

aislop — Zero-AI-Slop Code Quality & Anti-Slop Gate

The aislop server (scanaislop/aislop) provides zero-AI-slop and code hygiene validation, rule explanations, and automated fixes. Registered via npx -y @scanaislop/aislop-mcp@latest.

• Hard Pre-Gate in Kage Review: Enforces ai_slop_findings: 0 and ai_slop_clean: true before any delivery is approved.
• Role Boundaries:
  • genin & kage: Permitted aislop_scan and aislop_why (strictly read-only / diagnostic exploration).
  • jonin & anbu: Permitted aislop_scan, aislop_why, and aislop_fix (execution agents with automated repair capabilities).

🥷 Official Agent Team (Naruto Ninja Ranks)

The installer updates your configuration to define a cohesive, specialized team of 7 Naruto-ranked subagents. Each agent represents a level of ninja hierarchy with clear responsibilities and tool access; the host client controls model selection:

🧠 ADHD-Friendly Output (i-have-adhd): genin, chunin, jonin, anbu, and tokubetsu-jonin shape their final responses with the i-have-adhd skill — action first, numbered steps, one concrete next action, no preamble or closers. Sannin (router) and Kage (reviewer) keep their delivery-gate output contracts.

1. 🍃 Genin (Junior Scout)

• Operational Role: Codebase Reconnaissance & Scout
• Model: Selected by the host client; Konoha does not inject model fields
• Key Responsibilities:
  • Fast, read-only code exploration.
  • Traces codepaths, maps dependencies, and analyzes repository structure.
  • Constraint: Must never write or modify files on the filesystem.
  • Shapes final responses with ADHD-friendly output (i-have-adhd): action-first answers, numbered steps, one concrete next action.
• Skills-DB Keyword: code exploration tracing (invokes scout-level heuristics on startup).

2. 📜 Chunin (Journeyman Intel Gatherer)

• Operational Role: Intel Gathering, Web Research, & Documentation Synthesis
• Model: Selected by the host client; Konoha does not inject model fields
• Key Responsibilities:
  • Researches libraries, API specifications, version histories, and best practices.
  • Leverages semantic search (semble) to discover codebase context before executing web searches.
  • Batches parallel queries and ranks search results by credibility, freshness, and relevance.
  • Compiles comprehensive, citation-backed notes with full reference URLs.
  • Shapes final responses with ADHD-friendly output (i-have-adhd): action-first answers, numbered steps, one concrete next action.
• Skills-DB Keyword: websearch deep research (loads intel gathering methodologies).

3. 🛡️ Jonin (Elite Builder)

• Operational Role: UI/UX Master, Styling, & Component Architecture
• Model: Selected by the host client; Konoha does not inject model fields
• Key Responsibilities:
  • Builds premium, visually stunning frontends (SvelteKit, Next.js, Tailwind v4, Magic UI, 3D web).
  • Enforces design tokens, custom typography, smooth gradients, and glassmorphism.
  • Performs design match comparisons using the agent-browser CLI.
  • Enforces the Zero-Error Guarantee & Verification Loop (running local installs, Svelte/Next syncs, check/lint diagnostics, and production builds to guarantee zero compilation errors/warnings before completion).
  • Shapes final responses with ADHD-friendly output (i-have-adhd): action-first answers, numbered steps, one concrete next action.
• Skills-DB Keyword: sveltekit tailwind nextjs components (fetches design standards).

4. 👥 Anbu (Special Black Ops)

• Operational Role: Backend Specialist, Bug Resolution, DevOps, & Cybersecurity Defense Engineer
• Model: Selected by the host client; Konoha does not inject model fields
• Key Responsibilities:
  • Designs backend systems, database schemas, APIs (Node.js, Express, GraphQL, Laravel, WordPress, Magento, PHP, Ruby, C++).
  • Architectures distributed messaging and caching layers (Kafka, RabbitMQ, Redis, Nginx, HAProxy, Varnish).
  • Implements defensive cybersecurity forensics, threat hunting, OWASP remediation, and authorized penetration testing in dev/local environments (anthropic-cybersecurity-skills).
  • Provisions infrastructure (Terraform, Kubernetes, Helm) and manages secure CI/CD pipelines.
  • Formulates AI prompt engineering strategies (prompt-engineer) and creates/maintains agent skills (skill-creator).
  • Shapes final responses with ADHD-friendly output (i-have-adhd): action-first answers, numbered steps, one concrete next action.
• Skills-DB Keyword: terraform aws kubernetes helm ci-cd security kafka redis prompt (loads backend and defense recipes).

5. 🎯 Tokubetsu-jonin (Specialized Scribe)

• Operational Role: Technical Writing, Documentation, PDF Reporting, & Postmortems
• Model: Selected by the host client; Konoha does not inject model fields
• Key Responsibilities:
  • Authors and maintains README files, API specifications, runbooks, and onboarding guides (documentation-writer).
  • Produces printable professional PDF reports and styled documentation exports (pdf).
  • Drafts incident postmortems, root cause analyses (RCA), and project retrospectives (postmortem-writer).
  • Writes technical blog articles, whitepapers, engineering tutorials, and content (technical-article-writer).
  • Shapes final responses with ADHD-friendly output (i-have-adhd): action-first answers, numbered steps, one concrete next action.
• Skills-DB Keyword: documentation README API runbook postmortem pdf report article (retrieves writing standards).

6. 🌀 Kage (Village Leader)

• Operational Role: Senior Architect, Strategist, & Deep Problem Solver
• Model: Selected by the host client; Konoha does not inject model fields
• Key Responsibilities:
  • Guides high-level architecture decisions, security audits, and risk assessments (risk-assessment, improve-codebase-architecture).
  • Constructs professional architecture diagrams and visualizations (drawio-skill, mermaid-diagrams).
  • Orchestrates the entire subagent team for complex, multi-domain tasks.
• Skills-DB Keyword: code review architecture devsecops drawio mermaid risk (loads advanced architectural frameworks).

🛡️ Default Guardrails

To ensure safety, consistency, and predictable execution, the Antigravity system enforces several strict behavioral guardrails across all subagents:

[!IMPORTANT] Core Safety & Operational Policies:

• Proactive Execution (No commanding back): Subagents must never instruct the user to manually create/edit files or run terminal commands that the agent is equipped to perform itself.
• Protected Configuration & Secrets: All .env, .tfvars, and secrets.yaml files are strictly read-only by default. Subagents must explicitly request user permission before accessing or modifying these files.
• No Git Execution: Subagents are strictly prohibited from executing any git commands (including status, diff, log). Use semble for code search; konoha for targeted reads/grep.
• Locked Subagent Delegation: Subagent delegation is locked to the 7 official Konoha agents (genin, kage, chunin, jonin, anbu, tokubetsu-jonin, sannin). You cannot route tasks to shadow agents or unstructured personas. Never use Antigravity @self / @research. Creating custom subagents dynamically is prohibited.
• Orchestrator Pipeline (Antigravity): User prompt → structured MCP delegation → Konoha subagent → structured result/report. Direct structured MCP tool arguments (task, context, constraints, skills) are mandated cross-client.
• Circuit Breaker: Handoff loops are tracked via depth metadata in structured delegation context. If depth exceeds 7, execution freezes and prompts the user for manual validation.
• Rate Limit Fallback: In the event of API rate limits, the orchestrator falls back to direct tool calls (executing edits, reads, and commands directly) instead of spawning additional subagents.

Hard Guardrail Enforcement (v2.0.0)

The destructive-command, git-safety, secret-protection, and MCP read-bypass guardrails are enforced at the tool-call level, not just in prompts. A shared self-contained checker (src/guardrails.js, checkCommandGuardrails(command)) is deployed flat to ~/.konoha/guardrails.js and inlined verbatim into every client hook:

Blocked command categories: destructive (rm -rf /, mkfs, dd of=/dev/…, DROP DATABASE, chmod 777, recursive chown, curl | sh), destructive-git (git reset --hard, git push --force, git clean -f, git checkout -- ., git rebase -i), secrets (.env*, secrets.yaml, *.tfvars, *.pem, *.key, id_rsa, credentials — never rtk-exempt), and read-bypass (bare cat/grep/find/rg/… — retry with rtk <command> or use the konoha/semble MCP tools).

📊 Benchmark: Token Footprint & Optimization

The following charts demonstrate the context footprint savings per conversation session achieved by moving from full-disk loading to SQLite FTS5 on-demand retrieval:

Context Size Comparison (Lower is Better)

Startup Payload Size (KB)
────────────────────────────────────────────────────────────
Baseline (Disk Load):  ██████████████████████████████  550 KB
Konoha (On-Demand):   █                              12 KB   (97.8% savings)
────────────────────────────────────────────────────────────

Canonical editable diagram: 07 Token Footprint Comparison · Diagram manifest.

---
title: Token Footprint Before and After Konoha
config:
  theme: base
  themeVariables:
    darkMode: false
    background: '#ffffff'
    mainBkg: '#ffffff'
    primaryColor: '#ffffff'
    primaryTextColor: '#0f172a'
    primaryBorderColor: '#3b82f6'
    lineColor: '#334155'
    arrowheadColor: '#334155'
    secondaryColor: '#f8fafc'
    tertiaryColor: '#ffffff'
    fontFamily: 'Inter, system-ui, -apple-system, sans-serif'
    fontSize: '13px'
  flowchart:
    nodeSpacing: 45
    rankSpacing: 55
    padding: 24
    wrappingWidth: 380
---
flowchart TB
    subgraph Before ["Before: Folder-Level Loading"]
        Raw["Raw SKILL.md files"] --> References["All references and scripts"]
        References --> FullContext["Entire context window<br/>(Large repeated payload)"]
    end

    subgraph After ["After: On-Demand Retrieval"]
        Index["SQLite FTS5 index"] --> Query["find_skill(keyword)"]
        Query --> Relevant["Relevant bounded reference<br/>(Preview or full content)"]
    end

    Before --> Compare["Smaller query payload<br/>(97–99% token reduction)"]
    After --> Compare

    linkStyle default stroke:#334155,stroke-width:2px;
    style Before fill:#f8fafc,stroke:#cbd5e1,stroke-width:1.5px,color:#0f172a;
    style After fill:#f8fafc,stroke:#cbd5e1,stroke-width:1.5px,color:#0f172a;

    classDef wasteNode fill:#ffffff,stroke:#ef4444,color:#0f172a,stroke-width:2px;
    classDef optNode fill:#ffffff,stroke:#10b981,color:#0f172a,stroke-width:2px;
    classDef compNode fill:#ffffff,stroke:#3b82f6,color:#0f172a,stroke-width:2px;

    class Raw,References,FullContext wasteNode;
    class Index,Query,Relevant optNode;
    class Compare compNode;

📊 Benchmark Comparison: Antigravity Session Metrics

Live Telemetry Accounting & Benchmark Integrity (v2.0.1):

• Combined Token Savings: **~181M+ tokens sa