Boring for Gemini (V15.2.0) 💎

⚡ Beyond Generative AI: Agentic Cognition

Boring-Gemini isn't just a collection of tools; it's the thinking layer for your AI development workflow. While standard AI models suggest code, Boring reasons, verifies, and learns.

🧞‍♂️ The Vibe Coder Philosophy

"Intent is the new Implementation."

In the era of Vibe Coding, your role shifts from writing syntax to defining Intent. Boring-Gemini acts as your agentic partner, handling the gap between a "Vibe" (Natural Language) and "Production" (Verified Code).

🚀 The Three Pillars of Autonomy

🧠 Pillar I: Cognitive Reasoning (Agentic Loop)

Boring implements a rigorous Planning -> Execution -> Verification loop. It doesn't just run commands; it uses sequentialthinking and criticalthinking to analyze its own steps, critiquing logic before hitting your disk.

🛡️ Pillar II: Resilient Autonomy (Active Recall)

The first agent with a Global Brain. When Boring encounters a failure, it consults its persistent knowledge base (.boring/brain) to recall how similar issues were solved across sessions. It learns from its mistakes so you don't have to.

⚡ Pillar III: Ultra-Fast Ecosystem (UV Native)

Designed for the modern Python stack. Boring natively supports uv for near-instant package management, lockfile synchronization, and isolated environment execution.

⚓ Pillar IV: Production-Grade Safety (Safety Net)

Trust is built on safety. Boring automatically creates Git Checkpoints before any risky operation. Combined with Shadow Mode, you have a "undo" button for AI agentic actions, ensuring your repository remains stable even during complex refactors.

🧬 Pillar V: The Diet & Skills Update (V11.4.2)

Boring achieved Full-Power status by activating all high-value cognitive tools.

• SpecKit Activation: Enabled full Specification-Driven Development tools (plan, tasks, analyze) for methodical planning.

• Global Brain Tools: Unlocked cross-project knowledge sharing (boring_global_export) to recycle success patterns.

• Skills Autonomy: New boring_skills_install allows the Agent to autonomously install missing Python packages.

• Node.js Autonomy: Automatic Node.js download/install to ensure gemini-cli works even on fresh systems.

• Lightweight Mode (BORING_LAZY_MODE): Perfect for "Quick Fixes" without polluting directories with .boring folders.

🧠 Pillar VI: Intelligent Adaptability (V11.5.0)

Introduction of Self-Awareness and Adaptive Safety.

• Usage Dashboard (P4): The Agent now tracks its own tool usage, visualizing stats in a CLI/Web dashboard.

• Anomaly Safety Net (P5): Automatically halts "stuck" loops (same tool + same args > 50 times) to save tokens and prevent crashes.

• Contextual Prompts (P6): Adaptive Profile now injects specific guides (e.g., Testing Guide) only when you need them.

🛡️ Pillar VII: The True One Dragon (V12.0.0)

The legacy production standard. Introduction of a State-Machine Workflow and Deep Shadow Mode.

• Unified Flow Graph: Dynamic orchestration (Architect -> Builder -> Healer -> Polish -> Evolver).

• Deep Shadow Mode: HealerNode activates STRICT safety enforcement during auto-repairs.

• Cognitive Reflex: Semantic Search integrated into the Brain for fuzzy error correction.

🧐 Pillar VIII: Async Evolution (V13.0.0)

The current high-performance standard. Focused on Parallel Orchestration and Hybrid Storage.

• Async Agent Runner: Parallel execution of sub-tasks for faster completion.

• Semantic Storage Fallback: FAISS integration for robust vector search when ChromaDB is unavailable.

• One Dragon 2.0: Enhanced state management for complex "One Dragon" workflows.

🔮 Pillar IX: Intelligence & Offline (V13.1 - V13.5)

The cutting edge. Shifting from reactive to Predictive and Local-First.

• Offline-First Mode: Local LLM support (llama-cpp-python) for 100% privacy and zero-network operation.

• Predictive Error Detection: AI-powered anti-pattern detection and proactive warnings before errors occur.

• AI Git Bisect: Semantic analysis of commit history to instantly identify bug sources.

• Lazy Loading System: Optimized MCP startup (<500ms) for high-performance developer environments.

🏆 Pillar X: Sovereign Autonomy & Perfection (V14.0.0)

The Sovereign Edition. Achieving "100-Point Perfection" through enterprise-grade governance and knowledge continuity.

• Project Biography (: Persistent team-wide knowledge continuity.

• Policy-as-Code (: Secure, auditable tool permission guardrails.

• Sovereign Audit (: Automated 7-stage validation for production readiness.

• Self-Healing Doctor (: Autonomous environment repair and dependency resolution.

• System Optimizer (: Deep storage cleanup (VACUUM), brain pattern maintenance (Decay/Pruning), and reconciler checkpointing.

• Migration Engine (: Forward-compatible project state transition.

💖 Pillar XI: Anti-Rage UX (V15.0.0)

The Delight Update. Transforming the user experience from "Frustrating" to "Fluid".

• Visual Feedback: Rich Spinners, Step Tracking (Step 5/50), and Task Progress bars.

• Cost Awareness: Proactive API cost warnings to prevent bill shock.

• Resilience: Robust file locking handling (WinError 32) and friendly error translations.

• State Serialization: Ability to pause and resume long-running flows.

🌍 Pillar XII: The Zero-Cost Ecosystem (V15.0)

The Democratization Update. A fully decentralized, zero-cost plugin economy.

• Pack & Install: boring pack and boring install turn any repo into a plugin.

• Knowledge Share: boring brain export lets you share your AI's learned wisdom.

• GitOps Sync: boring sync enables serverless team collaboration via Git.

• Registry Spec: Open standard (registry.json) for a decentralized internet of agents.

🛠️ Key Capabilities

🎛️ Intelligent Tool Profiles (V10.26+)

Boring adapts to your environment to save tokens and context:

• LITE (Default): Essential tools for daily coding (43 tools) using ~15% of context window.

• FULL: All 67+ tools active.

• ADAPTIVE (Recommended): Automatically builds a custom profile based on your top 20 most frequently used tools + Prompt Injection.

  • Enable: export BORING_MCP_PROFILE=adaptive

🔔 Enterprise Notifications (V14.0+)

Boring supports multi-channel task notifications to keep you informed:

• Desktop: Windows Toast, macOS, Linux notifications.

• Webhooks: Slack, Discord.

• Messaging: LINE Notify, Facebook Messenger.

• Email: Gmail (via SMTP).

Configure these in .boring.toml:

📦 Getting Started

🎭 Dual-Mode Architecture (Hybrid Engine)

Boring is a Hybrid Agent that adapts to your workflow. It works in two distinct modes:

1. Cyborg Mode (MCP Server) 🧠

• Where: Inside Cursor, Claude Desktop, or VSCode.

• Role: Your "second brain". It sits alongside you as an MCP server.

• Usage: You chat with it via the @boring command. It remembers context, provides tools, and offers "Active Recall" suggestions.

• Best For: Daily coding, debugging, and interactive problem solving.

2. Autonomous Mode (CLI Agent) 🤖

• Where: Standard Terminal / Command Prompt.

• Role: Your "unattended worker". It runs as a standalone process.

• Usage: Run boring start (NOT boring run). It reads task.md, executes the plan loop (Plan -> Code -> Test -> Fix), and stops when done.

• Best For: Bulk refactoring, massive migrations, or long-running tasks while you sleep.

3. VS Code Extension (GUI Helper) 🖥️

• Where: extensions/vscode-boring/

• Role: A graphical interface for the CLI Agent inside VS Code.

• Features: One-click Start/Stop, Live Dashboard, and Status Bar integration.

• How to use: Open the directory in VS Code, press F5 to debug, or compile with npm run compile.

🔒 Data Privacy & The "Global Brain"

Your data stays YOURS. Boring uses a two-tier memory system:

1. Project Memory (.boring/memory/):

   • Lives in your project folder.

   • Contains project-specific graphs and indexes.

   • Safe to commit: Share with your team via Git.

2. Global Brain (~/.boring/brain/):

   • Lives in your user home directory (Local Manager).

   • Stores learned patterns and skills across all your projects.

   • NEVER uploaded: This data never leaves your machine unless you explicitly configure a sync.

Quick Install (One-Click)

Designed for Vibe Coders. Setup in < 30 seconds.

Windows (PowerShell):

Linux / macOS:

Manual Install (pip)

Using

Modular Components:

🛠️ Usage & Workflows

💎 Top Interaction Triggers

Just say these phrases to the AI in your IDE (Cursor/Claude):

• boring_flow: 🐉 One Dragon Engine. The ultimate autonomous workflow. Handles Setup -> Plan -> Build -> Polish automatically via code.

• start session: 🚀 Vibe Session. Activates Deep Thinking to autonomously manage the entire lifecycle of a complex task.

• /vibe_start: Kick off a new project from scratch.

• quick_fix: Automatically repair all linting and formatting errors.

• review_code: Request a technical audit of your current file.

• smart_commit: Generate a semantic commit message from your progress.

• boring_vibe_check: Run a comprehensive health scan of the project.

• boring doctor --optimize: Perform deep system optimization (Storage, Brain, and Checkpoints).

🧠 External Intelligence

Boring comes bundled with elite tools to boost AI performance:

• Context7: Real-time documentation querying for the latest libraries.

• Thinking Mode: Forces the agent into deep analytical reasoning (Sequential Thinking).

• Security Shadow Mode: A safety sandbox that intercepts dangerous AI operations.

📄 License & Links

• License: Apache 2.0

• Repository: GitHub

• Smithery: Boring Server