konoha-mcp
Advanced tools
Token-efficient MCP skill server with SQLite FTS5 and specialist agent routing
-CLI-orange?logo=raspberrypi&logoColor=white){kind=icon}
-red?logo=kalilinux&logoColor=white){kind=icon}
If you find Konoha helpful and want to support ongoing development, maintenance, and coffee-fueled coding sessions, consider buying me a coffee!
👉 Support Andy on Saweria (Buy Me Some Coffee) ☕
init --yes, socket loopback hardening, permission least-privilege), and isolated runtime governance.demo.webp)
demo-web.webp)
konoha-orchestration-flow.webp)
konoha-jonin-flow.webp)
konoha-kage-gate.webp)
konoha-qa-flow.webp)
konoha-telegram-flow.webp)
| 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 |
| 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 savingsoutput; latency and cost reductions are environment-dependent and are not guaranteed.
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.):
delegate.md and result.md) with direct in-memory structured context passing.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:
py-24, py-32, or py-48).grid-cols-12, bento grids) with bounded max-w-[1400px] containers instead of flaky flexbox percentages.min-h-[100dvh] to eliminate layout jumps on mobile address bar resizing.DESIGN_VARIANCE (1-10), MOTION_INTENSITY (1-10), VISUAL_DENSITY (1-10).
pnpm).~/.konoha/konoha.db).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:
assets/models/ (<100 MB each), enabling 100% offline installs and zero-download instant execution.searchChunksRAG()) for high-precision RAG context retrieval.KONOHA_SEMANTIC_SEARCH=1._EMBED_CACHE (512 entries), database-level binary blob reuse across skills, and candidate nearest-chunk deduplication.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.
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.semble.search, semble.find_related) — always via semble MCP, never grep/rg/find.konoha.read_file_head / read_file_range / file_info / token_efficient_grep, never generic Read / Grep / Glob / shell cat/head/tail.aislop.aislop_scan, aislop.aislop_fix, aislop.aislop_why for code hygiene and Kage review gating.README.md, docs/, CONTRIBUTING.md, .cursorrules, .clauderules, and canonical project skills (.agents/skills, skills/) before executing code.pnpm (never standalone npx or npm) for all JS/TS scaffolding, installs, and builds.@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, READMEsThe 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.
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;
| 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). |
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.
When a subagent runs, run_mcp_agent resolves skills in three layers:
agents.skills (per-agent YAML) is queried against skills.skill_name and references.name.devsecops-enginer → devsecops-engineer.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.
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.
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 onreport_from_agentare 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 subcommandskonoha data backup [path],konoha data rebuild-fts, andkonoha data prune [--retention <days>]. Note:konoha data prunedeletes immediately, with no confirmation and no automatic backup (takekonoha data backupfirst), 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 passallSessions: true.
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).
When installing Konoha, all required Node.js libraries, SQLite FTS5 database schemas, file tools MCP, and client configs are automatically provisioned:
@bufbuild/protobuf). Built on Node.js built-in node:sqlite (FTS5 + WAL) and native styling/prompting. Zero native compilation, zero build toolchain.~/.konoha/konoha.db (legacy skills.db is auto-migrated on first open).uvx for zero-setup deep code discovery.~/.konoha/ and registered with client IDE config schemas.[!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]
node:sqlite + FTS5, zero Python dependency)~/.agents/skills/ (with SKILL.md files); Konoha indexes and serves skill content through SQLite FTS5 without filesystem mirrorsTo 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.6) 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 |
Konoha structures every development task into an autonomous 8-phase state machine coordinated by sannin and validated by kage:
route (✧ Sannin): Runs Definition-of-Readiness (DoR) validation and registers the root task container in SQLite sdlc_tasks.explore (⚑ Genin): Read-only reconnaissance mapping codepaths, architecture boundaries, and dependencies (findings.md).plan (◎ Kage): Evaluates exploration findings, defines decoupled subtasks (- [agent]: task), registers unit subtasks in SQLite sdlc_tasks, and detects web research needs.research (▫ Chunin): Performs targeted web queries and documentation verification when requested by the Kage plan (needs_research: true).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.document (⬡ Tokubetsu-Jonin): Generates human-authentic documentation, API specifications, runbooks, and changelogs (final_docs.md).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.synthesize & done (✧ Sannin): Synthesizes final_report.md with full evidence table, marks root container completed, purges transient scratch files, and delivers cleanly.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:
TODO, FIXME, ???), existence of referenced files, and domain alignment before dispatch. Configurable per project (dor_mode: advisory or dor_mode: enforced).anbu, jonin) and the reviewing subagent (kage) are served by different underlying LLM models/bridges, ensuring unbiased second-opinion evaluation.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).anbu, re-verifying upon completion and bounded by the delegation-depth circuit breaker (slop_cycles > 7).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)./tasks): Visual task explorer, interactive Definition-of-Readiness sandbox tester, task evidence & anti-slop audit modal, and live governance mode toggles (/api/v1/sdlc/*)./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.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;
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:
src/telegram/)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./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.chat_id whitelist (telegram_config.chat_id) dropping unauthorized messages immediately.[KONOHA TASK REPORT], [SUCCESS], [QUEUED], [KAGE REVIEW GATE PASSED]).src/tunnel/)cloudflared (or ngrok) targeting Web UI port 1404 with automated binary provisioning and live URL detection (trycloudflare.com or custom domains).Cf-Access-Authenticated-User-Email) with zero in-app PIN friction while maintaining unauthenticated local access on localhost:1404.src/queue/)prompt_queue tracks atomic prompt states (pending -> processing -> completed / failed / cancelled) with filesystem session mirroring (~/.konoha/inbox/<session>.json).src/queue/worker.js):
kubectl, helm, docker, git, ssh, /sh, etc.) execute via interactive shell (bash -i -c) with 100% token elimination.agy -p ... with structured task telemetry and Kage Reviewer confidence reporting.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:
source ~/.nvm/nvm.sh then nvm use stablenvm use <version> then pnpm add --global github:andycungkrinx91/konohaFull platform-specific guides: SETUP-CLI.md, SETUP-IDE.md, SETUP-CURSOR.md, SETUP-MCP-CLIENTS.md.
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 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:
http://localhost:11434/v1Configure 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. Useopenai(API key) oropenai-compatiblebridges 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
~/.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
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.
After installation, Konoha registers 2 MCP servers that work together:
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.
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.
| 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 |
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. |
| 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, Antigravityview_file, or shellcat/head/grep. Workflow: semble (semantic code search) → konoha (skills & file operations).
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_related(file_path)Find files semantically related to a given file — useful for understanding dependencies and impact.
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.
ai_slop_findings: 0 and ai_slop_clean: true before any delivery is approved.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).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 thei-have-adhdskill — action first, numbered steps, one concrete next action, no preamble or closers. Sannin (router) and Kage (reviewer) keep their delivery-gate output contracts.
i-have-adhd): action-first answers, numbered steps, one concrete next action.code exploration tracing (invokes scout-level heuristics on startup).semble) to discover codebase context before executing web searches.i-have-adhd): action-first answers, numbered steps, one concrete next action.websearch deep research (loads intel gathering methodologies).agent-browser CLI.i-have-adhd): action-first answers, numbered steps, one concrete next action.sveltekit tailwind nextjs components (fetches design standards).anthropic-cybersecurity-skills).prompt-engineer) and creates/maintains agent skills (skill-creator).i-have-adhd): action-first answers, numbered steps, one concrete next action.terraform aws kubernetes helm ci-cd security kafka redis prompt (loads backend and defense recipes).documentation-writer).pdf).postmortem-writer).technical-article-writer).i-have-adhd): action-first answers, numbered steps, one concrete next action.documentation README API runbook postmortem pdf report article (retrieves writing standards).risk-assessment, improve-codebase-architecture).drawio-skill, mermaid-diagrams).code review architecture devsecops drawio mermaid risk (loads advanced architectural frameworks).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, andsecrets.yamlfiles 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
gitcommands (includingstatus,diff,log). Usesemblefor code search;konohafor 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
depthmetadata 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.
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:
| Client | Enforcement mechanism |
|---|---|
| Claude Code | ~/.local/bin/konoha-bash-guard.js PreToolUse hook (^Bash$ matcher) — denies destructive/git/secret/read-bypass commands; rtk-prefixed reads pass |
| Command Code | ~/.local/bin/konoha-native-blocker-cc.js PreToolUse hook — denies the native read_file tool and guards shell_command calls |
| Antigravity IDE/CLI | ~/.konoha/antigravity_tool_sanitize_hook.js PreToolUse hook — DENY-3 runs the full shared guardrail check on every run_command |
| Pi (pi.dev) | ~/.pi/agent/extensions/konoha-blocker.ts extension — blocks native reads and enforces the guardrails on bash/bash_command tool calls |
| OMP | Runtime contract (~/.omp/agent/AGENTS.md) — enforces MCP tool boundaries, RTK command prefixing, and 8-phase SDLC DAG execution |
| Codex / Cursor / OpenCode | No blocking-hook capability — prompt-only rules remain |
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).
The following charts demonstrate the context footprint savings per conversation session achieved by moving from full-disk loading to SQLite FTS5 on-demand retrieval:
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
| Metric | Without Konoha + Semble (Baseline) | With Konoha + Semble (Optimized) | Impact / Savings |
|---|---|---|---|
| Startup Context Load | ~1.1 MB (all SKILL.md rules + reference files loaded at start) | ~0 KB (instructions are lazy-loaded on-demand via MCP) | ~100% startup context reduction |
| Single Search Query Payload | 50 KB+ (entire files loaded/dumped) | ~4 KB - 12 KB (precise matches returned) | 83% - 98% token reduction per query |
| Active Workspace Calls | — | ~2,904 calls | — |
| Context Data Saved | — | ~302 MB | — |
| Active Tokens Saved | 0 (baseline) | ~110M tokens | ~110M tokens saved |
| Response Latency | Environment-dependent | Not measured by the repository test suite | No fixed claim |
| API Cost Footprint | Provider/model-dependent | Not measured by the repository test suite | No fixed claim |
Live Telemetry Accounting & Benchmark Integrity (v2.0.1):
read_file_range, find_skill, read_file_head) with structural pruning tools exceeding 99%.transcript.jsonl (99.8% exact fidelity) and sampled against cl100k_base tiktoken (~3.95 bytes/token, ±1.2% divergence, healthy).rtk gain.[!TIP] Read the complete auto-generated Token Savings & Optimization Benchmark Report for full metrics breakdown and analysis.
For an in-depth breakdown of system behavior, token consumption, configuration fragmentation, and architectural overhead, please read the Detailed Before vs After Comparison section in the Benchmark Report.
FAQs
Token-efficient MCP skill server with SQLite FTS5 and specialist agent routing
The npm package konoha-mcp receives a total of 257 weekly downloads. As such, konoha-mcp popularity was classified as not popular.
We found that konoha-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.