bestAI: Omni-Vendor Convergence

The industry-leading orchestration layer for autonomous AI engineering swarms.

Quick Start • Tutorial • v14.0 (Rust) • Mechanisms • Toolbelt

🦀 v14.0: The Rust Horizon (Professional Rewrite)

bestAI has evolved from a simple set of guidelines into the world's most advanced Autonomous Agent Governance OS. To support Enterprise-scale swarms, we are actively rewriting the entire core from Bash/Python into Rust.

Why Rust? The Professional Standard

1. Zero Dependencies (Single Binary): No more jq, Node.js, or Python environment issues. You download one incredibly fast executable (bestai) that works instantly on Linux, Mac, and Windows.
2. Sub-millisecond Latency: AI agents trigger security hooks thousands of times per session. Rust eliminates the overhead of Bash subprocess forking, bringing hook latency from ~150ms down to < 5ms.
3. AST-Level Security: Instead of relying on Regex to block malicious agent commands, the Rust core will use a true Abstract Syntax Tree (AST) parser to analyze shell commands, making the Force-Field mathematically unbreakable.
4. Memory-Safe Concurrency: The bestai conductor (managing async Swarm threads) will run on the blazing-fast Tokio runtime, preventing any thread-locking or memory leaks during week-long autonomous sessions.

👉 The current npm/bash versions (v7-v13) serve as our stable V1 architecture while the Rust core is built.

🔄 How bestAI Works (The Workflow)

graph LR
    User[User Prompt] --> Hook{🛡️ bestAI Hooks}
    Hook -- Block --> Fix[💡 Auto-Fix Suggestion]
    Hook -- Allow --> Exec[🤖 Agent Execution]
    Exec --> GPS[🛰️ Sync GPS State]
    GPS --> Context[🧠 Update Context Tiers]
    Context --> User

📜 The AI Agent Contract (v10.1)

bestAI projects are now self-documenting for incoming agents. The .bestai/CONTRACT.json file provides a machine-readable definition of:

• Capabilities: What enforcement and orchestration modes are active.
• Toolbelt: List of available bestai commands and their purpose.
• Security: Which files are protected and how bypasses are handled.

Incoming agents (Claude, GPT, etc.) read this contract at boot to align with your project's deterministic standards.

⚡ v14.0: The Living Swarm (Conductor Mode)

The latest evolution of bestAI introduces the Syndicate Conductor. You no longer wait for agents. You interact with a central "Project Brain" that orchestrates specialists in real-time.

Key v14.0 Mechanisms:

• Asynchronous Execution: Sub-agents (Claude, Gemini) work in background threads.
• Intelligence Filtering: The Conductor only alerts you for critical milestones or errors.
• Research Vault (TTL): Global cache for codebase analysis. Run once, remember forever.
• Continuous Conversation: A persistent shell that maintains multiple thought-streams.

🎬 Watch the v14.0 Living Swarm Demo

👉 Run it now: bestai conductor

👥 v14.0: The Human-AI Nexus (Team Collaboration)

bestAI v14.0 transforms from an individual tool to a Team Governance Platform. It enables Juniors, Seniors, and Managers to collaborate with AI Swarms through a unified project brain.

Key v14.0 Mechanisms:

• Nexus Journal: Every strategic human decision is logged and injected into the AI's T0 context, preventing models from contradicting human intent.
• Role-Based Governance: Customize hook intensity based on the user's seniority (e.g., Juniors get stricter Fail-Closed safety).
• Knowledge Handshake: Automated onboarding for new team members by parsing the Research Vault and Nexus logs.

The Nexus Workflow:

graph LR
    Lead[Senior Lead] -->|Strategy| Nexus((Nexus Bus))
    Nexus -->|Constraint| AI[AI Swarm]
    AI -->|Implementation| Nexus
    Nexus -->|Audit| Stakeholder[Manager]
    Junior[New Dev] -->|Learning| Nexus

👉 Run a check-in: bestai nexus --user "Name" --role "Lead" --decision "..."

🧠 v14.0: The Elastic Brain (Infinite Depth)

bestAI v14.0 eliminates the "flat context" problem. It introduces Dynamic Context Zoom, where the granularity of loaded data matches the precision of your task.

Key v14.0 Mechanisms:

• Macro/Micro Lens: The Conductor stays high-level (strategic), while specialists (Sub-agents) are pumped with granular technical details only when a specific "Deep Task" is triggered.
• Recursive Delegation: If a task is too complex, the agent spawns its own sub-swarm, preventing context saturation and maintaining 100% precision.
• Context Pressure Monitor: Automatically triggers delegation when an agent's memory usage exceeds optimal thresholds.

The Elastic Workflow:

graph TD
    User[User Input] --> Conductor["Dyrygent - Macro Mode"]
    Conductor -- Specific Task --> Specialist["Specialist - Micro Context"]
    Specialist -- Too Heavy? --> SubSwarm[Recursive Sub-Swarm]
    SubSwarm -- Results --> Specialist
    Specialist -- Summary --> Conductor
    Conductor -- Strategic Feedback --> User

👉 Run it now: bestai conductor

⏳ v11.0: The Time Machine & Autonomous Guardian

We identified the two biggest wastes of time and tokens in AI engineering: starting late on a messy project, and forcing LLMs to read the entire codebase just to figure out what needs testing. v11.0 fixes both.

1. The Time Machine (Retroactive Onboarding)

Did you start using AI without bestAI? It's a mess, right? The Time Machine parses your messy, gigabyte-sized .claude/history.jsonl (or similar logs) offline (saving millions of tokens). It extracts architectural decisions and milestones, instantly generating a perfect .bestai/GPS.json and knowledge base.

The Workflow:

graph LR
    Chaos[Messy Chat Logs] -->|Offline Python Parser| TM((bestAI Time Machine))
    TM -->|Extract Constraints| Dec[decisions.md]
    TM -->|Extract Milestones| GPS[GPS.json]
    GPS --> Order[Perfect Syndicate Start]

👉 Run: bestai retro-onboard

2. The Autonomous Guardian (Token-Saving Test Builder)

Why pay Claude API to scan 50 files just to write empty test stubs? The Guardian is an external script that statically analyzes your codebase, cross-references it with GPS.json functionalities, and automatically generates missing test boilerplates. You then simply command the agent: "Fill in the empty tests." Token savings: ~80%.

The Workflow:

graph LR
    Src[Source Code] -->|Static Analysis| Guard{bestAI Guardian}
    GPS[GPS.json Specs] --> Guard
    Guard -->|Zero Token Cost| Stubs[Empty Test Boilerplates]
    Stubs --> LLM[LLM Agent Fills Logic]

👉 Run: bestai guardian

🌌 bestAI + OpenClaw

High-Persistence Autonomous Intelligence. Using bestAI in OpenClaw unlocks Total Recall Mode. Preserve every decision, decision log, and codebase change across weeks of autonomous operation. No pruning, no forgetting.

👉 Learn how bestAI powers OpenClaw

🏗️ bestAI for IT Projects

Enterprise-Grade Standards for AI Engineering. Build robust IT projects with Deterministic Compliance. bestAI forces agents to follow security, testing, and architectural rules, reducing technical debt by 90%.

👉 Learn how bestAI builds IT Projects

🚀 Quick Start (Zero-to-Hero)

The One-Command OpenClaw Installer (v9.0+)

Deploy a fully configured, high-persistence multi-agent environment instantly:

curl -s https://raw.githubusercontent.com/radekzm/bestAI/master/install-openclaw.sh | bash

Manual Global Install

npm install -g @radekzm/bestai

2. Initialize bestAI in your Repo

cd your-project
bestai init .

Select the "Omni-Vendor" profile for the full multi-agent experience.

3. Verify Health

bestai doctor --strict

📖 Tutorial: Your First Swarm (Mini-API)

In this example, we will build a simple FastAPI application using Gemini for mapping and Claude for implementation.

Step 1: Initialize the Project State

Define your goal so all agents are aligned.

# Set the main goal in .bestai/GPS.json
echo '{"project":{"name":"FastAPI-Mini","main_objective":"Build a secure user registration API"}}' > .bestai/GPS.json

Step 2: Gemini Investigates (Research)

Gemini scans your environment and suggests the tech stack.

bestai swarm --vendor gemini --task "Search for best FastAPI boilerplates and update T3-summary.md"

Step 3: Claude Implements (Coding)

Claude reads the research from GPS and implement the code, protected by hooks.

bestai swarm --vendor claude --task "Create main.py with a signup endpoint using standard FastAPI patterns"

Step 4: Verify Compliance

Check if the agents followed the rules.

bestai compliance

🔐 Agent Authorization & Security

bestAI follows a Zero-Knowledge credential policy. Agents never handle raw API keys.

1. Credential Delegation

Before starting the swarm, ensure your local CLI tools are authenticated:

• Claude: claude auth login
• Gemini: export GOOGLE_API_KEY=your_key (in your shell, not in files)
• Ollama: Running locally on localhost:11434

2. The Secret-Guard Force-Field

All bestAI projects include hooks/secret-guard.sh. This hook physically blocks agents from:

• Reading Secrets: Attempts to cat .env or read SSH keys are blocked.
• Exfiltration: Attempts to curl local data to external servers are intercepted.
• Leaking: If an agent accidentally generates a secret in code, bestAI prevents the file write.

[!CAUTION] Never ask an agent to "Manage my API keys". Always handle authentication manually in your host terminal.

🔧 Core Mechanisms (Under the Hood)

bestAI is built on five revolutionary engineering pillars:

1. Deterministic Force-Field (Fail-Closed Hooks)

Unlike soft prompt-based rules, bestAI uses Bash Hooks. Every file write or shell command is intercepted. If an agent tries to edit a FROZEN file, the script returns Exit 2.

2. The 5-Tier Context OS

We bypass token limits by segmenting memory: T0 (Hot/GPS) to T4 (Frozen/Config).

3. Omni-GPS (Shared Global State)

A central JSON bus that synchronizes all agents (milestones, blockers, architectural decisions).

4. Swarm Mutex (swarm-lock)

Specifically for multi-vendor setups. Before any agent starts a heavy task, it places a lock on the target file path.

5. Human-in-the-Loop (bestai permit)

The ultimate override mechanism. Grant a temporary pass: bestai permit package.json --duration 10m

💎 The Strategic Value of bestAI (ROI)

🛠️ The Syndicate Toolbelt