☕ 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.5 — Socket supply-chain security remediation (@socketregistry/[email protected]), pure WebAssembly Argon2id, zero-eval timer shims, and centralized queue worker guardrails.
• Latest Security Compliance: Google Policy Compliance v2.2.3 — Audited & Certified (2026-10-19)

🌟 Master Architectural Feature Matrix

| Category | Capability / Feature | Subsystem / Engine | Key Invariant & Contract | Status | |:---|:---|:---|:---|:---:| | Orchestration & Personas | ✧ Sannin Router | src/mcp/tool_dispatch.js | Top-level triage, domain routing, zero inline implementation | ✅ ACTIVE | | | ⚑ Genin Scout | genin-skill | Read-only symbol search, codepath tracing, zero file mutations | ✅ ACTIVE | | | ◎ Kage Governor | kage-skill | Architecture decisions, security auditing, 98% Confidence Gate | ✅ ACTIVE | | | ♦ Jonin Builder | jonin-skill | Taste-Skill UI across Next.js, Nuxt, SvelteKit, Angular | ✅ ACTIVE | | | ♠ Anbu Black Ops | anbu-skill | Backend dev, bug fixes, DevOps, 817 offensive security skills | ✅ ACTIVE | | | ▫ Chunin Intel | chunin-skill | Zero-API-key web research (SearXNG + Wikipedia OpenSearch) | ✅ ACTIVE | | | ⬡ Tokubetsu-Jonin | tokubetsu-jonin-skill | Technical documentation, API specs, runbooks, README sync | ✅ ACTIVE | | Token & Context Optimization | Bounded File I/O | src/file_tools_router.js | read_file_range, read_file_head (50–100 line caps, 83–98% savings) | ✅ ACTIVE | | | Semantic Code Search | semble MCP | Vector embeddings & line spans replace full repository dumps | ✅ ACTIVE | | | Shell Output Compaction | rtk (Rust Token Killer) | Global CLI proxy compresses noisy command outputs (60–95% savings) | ✅ ACTIVE | | | Auto-Compaction | src/mcp/runtime_state.js | Automatic badge compaction on turn ≥ 2 (preserves tech stack) | ✅ ACTIVE | | | Hybrid Vector RAG | src/vector_search.js | IBM Granite multilingual + MS MARCO MiniLM neural reranker | ✅ ACTIVE | | SDLC Quality Gates | Two-Stage HITL Gates | src/mcp/workflow.js | Gate 1 (pending_plan_approval) & Gate 2 (pending_human_signoff) via Desktop IDE / Telegram | ✅ ACTIVE | | | Dual-Track Execution Engine | src/mcp/workflow.js | Direct request fast-track (/kage, /anbu) vs Canonical 8-Phase Master SDLC DAG | ✅ ACTIVE | | | Definition-of-Readiness (DoR) | src/sdlc_dor.js | Enforced/advisory check blocks unready, ambiguous prompts | ✅ ACTIVE | | | Two-Step Zero-AI-Slop Gate | aislop_scan + anti_slop | Mechanically requires 100/100 scan & 0 findings before synthesis | ✅ ACTIVE | | | Kage Confidence Gate | src/workflow_gates.js | Strict ≥ 98% verification score required across all categories | ✅ ACTIVE | | | Supply-Chain Security Gate | Socket CLI (socket ci) | Mechanical blocker on High/Medium dependency vulnerabilities | ✅ ACTIVE | | | Autonomous Remediation Loop| src/sdlc_remediation.js | Bounded circuit breaker (7 cycles) for auto-fixing slop findings | ✅ ACTIVE | | Frontend & UI Engine | Taste-Skill v2 Dials | Leonxlnx/taste-skill | DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY | ✅ ACTIVE | | | 4 Supported Frameworks | src/mcp/build_spec.js | Official CLI scaffolding: Next.js 16, SvelteKit 2, Nuxt 3, Angular 19+ | ✅ ACTIVE | | | 10 Palette Themes × Light/Dark | apps/web/src/ | Pure light-mode first class + dark mode; floating bottom-left theme picker FAB (fixed bottom-6 left-6 z-50) with neon focus | ✅ ACTIVE | | | Image Mockup Replication | build_from_source | 100% exact layout, spacing, typography, and asset replication | ✅ ACTIVE | | | AI-Website Fingerprint Detector| src/ai_detector.js | Heuristic engine detecting AI generators (0–20 = Human-Built band) | ✅ ACTIVE | | Document Engineering | Office Deliverables | src/tools/document_engine.js | DOCX, PDF, XLSX, PPTX with < 3% ZeroGPT AI target & discrete sections | ✅ ACTIVE | | | Animated WebP Pipeline | src/tools/document_engine.js | Canonical .webp export with pure Node.js structural bitstream validation | ✅ ACTIVE | | Remote Operations & Mobile | Cloudflare Zero Trust Ingress| src/tunnel/ | Out-of-band tunnel (/remote) with Edge PIN & Cloudflare Access | ✅ ACTIVE | | | Two-Stage Telegram Approvals | src/telegram/ | Real-time Gate 1 & Gate 2 interactive approval buttons, /approval list, /doctor, /session | ✅ ACTIVE | | | Persistent Prompt Queue | src/queue/ | SQLite atomic state machine (pending -> processing -> completed) | ✅ ACTIVE | | Security & Cryptography | Argon2id Memory-Hard Auth| src/auth.js | Salted Argon2id passphrase verification + CLI reset (konoha auth reset) | ✅ ACTIVE | | | AES-256-GCM Crypto Vault | src/crypto_vault.js | AEAD authenticated encryption at rest for tokens & credentials | ✅ ACTIVE | | | PBKDF2 Key Derivation | src/crypto_vault.js | 100,000 SHA-256 iterations with host-fingerprint salt | ✅ ACTIVE | | | Zero Plaintext Secrets Invariant| Whole repo | Automatic masking (12345***:***abcd) across APIs, logs, and TUI | ✅ ACTIVE | | | Offensive Red-Teaming Skills | anbu-skill | 817 Anthropic cybersecurity skills & MITRE ATT&CK techniques | ✅ ACTIVE | | Cross-Client Ecosystem | 8 Supported Coding Clients | src/mcp_clients_manager.js, src/agent_manager.js | Antigravity, Cursor, Claude Code, OpenCode, Command Code, Codex, Pi, OMP | ✅ ACTIVE | | | Hermetic Session Isolation | src/db.js | Composite PK (client, workspace_root, session_id) with project_hash preventing cross-session leakage | ✅ ACTIVE |

📖 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

| Developer Challenge & Problem | Traditional / Naive Approach | Konoha Enterprise Solution | Key Impact & Metric | |:---|:---|:---|:---| | Vibe Coder Career Dilemma(Newbi Vibe Coder is confused about how to reach the higher level in this AI era so konoha appear as solution for one shot setup) | Casual single-file prompting, copy-pasting code snippets without structure, fragile prototypes, lack of SDLC governance, and inability to architect scalable enterprise systems. | One-Shot Setup (konoha init --force): Turnkey initialization instantly provisioning 7 specialized ninja subagents, 1,027 domain skills, and 40 canonical MCP tools across 8 major IDEs/clients with zero manual glue code. | Elevates casual vibe coding into structured senior engineering rigor with full team delegation from Day 1. | | Context Window Flooding & High API Costs | Dumping entire skill trees, unindexed files, and massive prompt boilerplates at startup (~1.1 MB payload / 800,000+ tokens). | On-Demand SQLite FTS5 Indexing & Bounded File I/O: find_skill and bounded file operations slice context to exact 50–100 line spans. | 83%–98% token reduction; sub-millisecond retrieval (0.61 ms); eliminates context bloat and LLM amnesia. | | Terminal Output Noise & Shell Explosion | Build tools, test runners, and linters dump hundreds of noisy progress bars and logs directly into model context. | RTK (Rust Token Killer) Global CLI Proxy: Transparently intercepts terminal commands, compresses noisy outputs, and preserves critical error signals. | 60%–95% terminal output compression; saves thousands of tokens per command execution. | | Generic AI Slop & Aesthetic Clichés | Generating purple gradients, generic Inter typography, center-aligned hero clutter, broken mobile layouts, and excessive emoji decor. | Jonin + Taste-Skill v2 Anti-Slop Frontend Engine: Strict typography standards (Geist, Cabinet Grotesk), bento CSS grids, 10 four-stop gradient palettes with Light/Dark appearance, bottom mobile dock, and zero emoji policy. | 100/100 aislop scan compliance; production-grade, human-crafted aesthetic fidelity. | | Hallucinated Passes & Broken Builds | Agents claiming tasks are complete without running tests, silently introducing type regressions and breaking dependencies. | Kage Reviewer 98% Minimum Confidence Gate & Playwright QA: Two-step Zero-AI-Slop gate (aislop_scan + anti-slop rules), automated E2E test generation (qa_codify / qa_e2e_run), and strict rejection below 98% confidence. | Mechanical delivery gate; ≥ 98% confidence invariant across architecture, tests, and security. | | Mobile & Remote Workflow Disconnection | Developers chained to their desks; inability to monitor, review, or trigger agent runs remotely; local servers trapped behind NATs. | Dual-Mode Telegram Bot & Cloudflare Tunnel: Full remote control over mobile with two-way conversational prompting and one-way post-Kage completion notifications, secured by Cloudflare Zero Trust public ingress. | Anywhere, anytime autonomous agent interaction with real-time push alerts. | | Plaintext Credential Leaks & Secret Vulnerabilities | Storing sensitive API tokens, bot tokens, and tunnel credentials in plaintext .env files vulnerable to accidental Git commits and logs. | AES-256-GCM AEAD Hardware-Grade Crypto Vault: Machine-bound PBKDF2 (100,000 iterations) key derivation, OS-keyed encryption, automatic redaction in logs, and zero plaintext secret storage. | Zero-knowledge secret management; automated encryption for bot tokens & Cloudflare secrets. | | DevOps & Offensive Security Blindspots | AI models unaware of OWASP vulnerabilities, unable to perform security assessments, and producing insecure cloud deployments. | 817 Anthropic Cybersecurity Skills & Anbu Black Ops: Integrated MITRE ATT&CK techniques, penetration testing, exploit analysis, container hardening, and enterprise defense capabilities in dev/local environments. | End-to-end security hardening; comprehensive vulnerability identification and red teaming. | | Multi-Agent Disk Thrashing & Context Fragmentation | Subagents exchanging files via disk files (delegate.md/result.md), causing I/O lag, disk bloat, and context fragmentation. | Direct Structured MCP Delegation & Zero-Loop Reporting: In-memory argument passing (task, context, constraints, skills, taste_dials) and automatic episodic project memory checkpointing (report_from_agent). | Zero disk file loops; instant subagent dispatch with permanent project memory continuity. | | Fragmented IDE Configuration & Ecosystem Lock-in | Manually configuring skills, MCP servers, and agent prompts across Antigravity, Cursor, Claude Code, OpenCode, Command Code, Codex, Pi, and OMP. | Single Universal Hub & Cross-Client Compatibility: One command (konoha init --force) universally provisions .gemini, .cursor, .claude, .agents, .omp, and project configs simultaneously with automatic skill synchronization. | Write once, run anywhere across all 8 premier AI coding environments. |

[!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

| Dimension | 1. Agent-to-Agent (Process Spawning) | 2. MCP-to-MCP (Server-to-Server RPC) | 3. MCP Tools Orchestrator (Konoha Model) | |:---|:---|:---|:---| | Execution Model | Spawns separate LLM child processes (invoke_subagent). | One MCP Server calls another downstream MCP Server via backend RPC. | Subagents run as MCP Tools (anbu, kage); Orchestrator adopts persona dynamically. | | Token Efficiency | ❌ Poor: High token bloat from duplicating system prompts & context (3x–10x token cost). | ⚠️ Moderate: Depends on RPC serialization payload size. | ✅ Extreme (83–98% Savings): In-flight execution using bounded MCP context. | | Startup Latency | ❌ High: 3–10 seconds of cold-start delay per child process launch. | ⚠️ Moderate: Network/IPC serialization hops between cascading servers. | ✅ Near-Zero Latency: Instant inline tool invocations and persona handoffs. | | Task Auditability | ⚠️ Complex transcript aggregation across detached process trees. | ❌ Hidden backend execution; opaque to the client UI/user. | ✅ Fully Transparent: Human-readable task contracts (delegate.md & result.md). |

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:

| Path | Purpose | |------|---------| | ~/.konoha/tmp/<client>/<session>/scratch/tasks/<task_id>/delegate.md | Legacy task instructions only | | ~/.konoha/tmp/<client>/<session>/scratch/tasks/<task_id>/result.md | Legacy result exchange only |

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). 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:

| Command | Description | |:---|:---| | konoha init | Full install: self-contained CLI runtime (~/.konoha/bin/cli.js) + server + migration + MCP config + GEMINI.md + global konoha command reconciliation (npm/pnpm/yarn shims on Linux, macOS, and Windows) | | konoha migrate | Re-index/migrate skills database into SQLite FTS5 (supports --clean, --rebuild-embeddings, --skip-embeddings, --skills-dir) | | konoha reinstall | Force clean re-installation and configuration replacement (implies --force) | | konoha embed | Rebuild neural vector embeddings for all skill chunks (implies --rebuild-embeddings) | | konoha test | Test MCP server with sample searches | | konoha status | Show installation status and DB stats | | konoha version | Display current local version (2.2.5) and check for updates from npm registry | | konoha upgrade | Upgrade Konoha CLI to latest release with interactive real-time Progress Bar (--yes for headless); also re-reconciles the global konoha command shim | | konoha bridge status | Show bridge router status and Antigravity session liveness (sidecar-gated bridges show AWAITING SIDECAR when IDE is closed) | | konoha bridge list | List all configured bridges with port/provider/enabled state | | konoha savings | Show token savings metrics (Today, 7 days, All time) for Skills-DB and Semble | | konoha data <subcommand> | Database maintenance operations (backup [path], rebuild-fts, prune --retention <days>) | | konoha detect-ai <path-file-or-url> | Website/code AI-fingerprint detector (anonymiz.com-style): scans a site directory, single file, or URL for generator tags, Lucide icons, shadcn/ui shapes, Vercel/Netlify signals, attribution comments, and template assets; scores 0-100 (0-20 = Human-Built). --json for machine-readable output; exit code 1 when AI fingerprints are detected | | konoha detect-docs <path-or-url> | Documentation AI-pattern detector: scans markdown/docs for AI-writing clichés, conversational filler, and structural fingerprints | | konoha doctor | Diagnose environment health, verify agent-browser CLI & Chrome binary readiness, and automatically repair missing files | | konoha ui <subcommand> | Optional Web UI lifecycle management (start, stop, restart, status, open) on port 1404 | | konoha web | Launch the browser-based Web Configuration UI on port 1404 (Svelte 5 + Vite) | | konoha uninstall | Remove Skills-DB (original skills untouched) | | konoha skill <subcommand> | Manage custom skills (list, search, add, remove) | | konoha agent <subcommand> | Manage subagent configurations (list, create, skill, models, delete, status) | | konoha agent models config | Interactively pick a bridge-served model for a subagent (TUI; or --model <id> / --model inherit non-interactive) | | konoha task <subcommand> | SDLC task governance (list, show <id>, slop <id>) with persistent SQLite audit trails | | konoha project set dor-mode <advisory\|enforced> | Configure project Definition-of-Readiness gate mode | | konoha project set review-mode <self\|cross-provider> | Configure project review independence mode | | konoha bridge <subcommand> | Manage Konoha Bridge Router (status, list, models, create, delete, enable, disable) | | konoha telegram <subcommand> | Dual-mode Telegram Bot manager (status, config, test, enable, disable, start-poller, stop-poller, notify-kage, test-gate) | | konoha tunnel <subcommand> | Cloudflare Zero Trust Ingress tunnel manager (status, start, stop, config) | | konoha queue <subcommand> | Unified Inbound Prompt Queue manager (list, enqueue, cancel, complete, status) | | konoha help | Show help |

🔄 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:

| Client | RTK Rule Location | |--------|-------------------| | Antigravity | ~/.gemini/antigravity-cli/rules/rtk.md + ~/.gemini/antigravity-ide/rules/rtk.md | | Cursor | ~/.cursor/rules/rtk.mdc | | Claude Code | ~/.claude/rules/rtk.md | | OpenCode | ~/.config/opencode/rules/rtk.md + ~/.config/opencode/plugins/rtk.ts | | Command Code | ~/.commandcode/rules/rtk.md | | Codex | ~/.codex/rules/rtk.md | | Pi (pi.dev) | ~/.pi/agent/extensions/rtk.ts (official RTK TypeScript extension) | | OMP | ~/.omp/agent/AGENTS.md (runtime workflow contract with RTK mandate) |

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:

| Bridge Name | Default Port | Provider | Behavior | |:---|:---:|:---|:---| | gpt-api | User-defined | openai | Direct proxy to OpenAI-compatible endpoints (e.g. https://api.openai.com/v1). | | my-ollama | User-defined | openai-compatible | Proxy to local LLM instances (e.g. Ollama, vLLM). |

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 45 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)

Executes the specified subagent inline with structured task context, dynamic skill loading, project context, and optional Taste-Skill dials.

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

| Tool | Purpose | Token guard | |------|---------|-------------| | read_file_head(path, max_lines?) | Preview first N lines (default 80) | Max 200 lines | | read_file_range(path, start_line, end_line) | Stream a line range with line numbers | Max 500 line span | | file_info(path) | Size, line count, mtime — no content load | Metadata only | | token_efficient_grep(pattern, dir, glob?, ignore_case?) | Compressed regex search | Max 20 matches (cap 50) | | get_file_structure(path) | Class/function signatures only (no bodies) | AST (Python) / regex (JS/TS) | | find_files_clean(pattern, dir) | Glob walk with blacklist | Skips .git, node_modules, dist, lockfiles |

QA Automation Tools (anbu exclusive)

| Tool | Signature | Purpose & Token Guard | |------|-----------|------------------------| | qa_codify | (flow_path, target_spec_path?, base_url?) | Compiles declarative flow JSON (tests/e2e/flows/*.json) to Playwright .spec.js. Rejects @e element refs, generates semantic locators, pre-verifies against target app, and runs syntax linting before writing. Accessible exclusively to anbu. | | qa_e2e_run | (test_file?, test_filter?, project_dir?, timeout_ms?) | Headless Playwright test runner with hard output cap strictly under 2,000 characters. Strips ANSI color codes, extracts failure traces, assigns unique run_id, and returns clean structured JSON summary. Prevents LLM context blowup. Accessible exclusively to anbu. |

Quality & Governance Tools

| Tool | Signature | Purpose & Token Guard | |------|-----------|------------------------| | anti_slop | (target_dir?, file_paths?) | Deterministic rule-based anti-slop verification engine executed during Kage pre-delivery review after aislop_scan. Audits changed files for lazy placeholders, generic syntax comments, speculative code, and conversational fluff. Returns 0-100 score and issue breakdown. |

[!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]==0.6.2 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_relate