Skip to content
aethelondev-stackPublic

About

Context-efficient Gemini Worker for AI coding agents, with caching, evidence verification, security isolation, and automatic task routing.

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

BUBU: General-Purpose AI Worker & LLM Context Engine

High-Performance, Context-Preserving General-Purpose Research & Analytical Worker for AI Coding Agents (Google Antigravity, Cursor, Cline). Built with Zero External Dependencies (100% Python Standard Library).

BUBU is a source-available, modular companion for autonomous AI coding agents like Google Antigravity. It solves the critical bottleneck of context window bloat by offloading heavy multi-file reading, stack-trace debugging, security audits, and library research out-of-band to a dedicated LLM worker layer (Google Gemini as Provider #1 by default, or any OpenAI-Compatible API such as DeepSeek, OpenRouter, or local Ollama), returning only compact, evidence-verified structured findings to the lead coding agent.


🌐 The Ecosystem: BUBU + NEXUS + ARGUS

BUBU is the dedicated General-Purpose Worker within the autonomous three-layer agent ecosystem:

BUBU (General-Purpose AI Worker)
  ↓
NEXUS (Always-On Host Coordinator)
  ↓
ARGUS (Visual / Computer Interaction AI Worker)
  • BUBU: General-purpose AI worker offloading multi-file context analysis, architectural audits, and memory leak detection.
  • NEXUS: Always-on host coordinator managing task routing, provider quota (429/TPM) and rate limits, loop detection, and evidence aggregation.
  • ARGUS: Visual and computer interaction worker utilizing local GPU to prevent multimodal token bleeding.

πŸ“‘ Table of Contents


⚑ Quick Start (Zero-Prompt Auto-Onboarding)

Get up and running in under 30 seconds:

  1. Copy the Portable Package (her projeye taşınacak klasârler/) into your project: Copy the contents of her projeye taşınacak klasârler/ into your target repository root:
    • .agents/skills/ai-studio-worker/ (Worker engine)
    • .ai-worker/ (Cache, quota, and reports scaffolding)
    • AGENTS.md (Zero-token on-demand onboarding rule)
    • .env (Your API key) & .gitignore
  2. Start coding normally: Open a new chat in Antigravity and prompt your agent with any engineering task (e.g., "Build a login API").
    • Antigravity's AGENTS.md rule automatically fulfills your coding task first.
    • At the end of the response, it prompts for your BUBU and ARGUS mode preference once.
    • Zero-Token Guard: If you select disabled, it writes the setting without wasting a single token reading skills or scripts.
    • If you select auto or enabled, it loads the worker on-demand and saves your preference forever.

πŸ€– Install with an AI Coding Agent

If you are using Google Antigravity or another AI pair-programming assistant, copy and paste this universal setup prompt into your chat:

Install and verify BUBU for this project.

First, discover the BUBU skill (.agents/skills/ai-studio-worker) and inspect the project configuration.

If my Worker usage preference is not yet saved in .ai-worker/config.json, present me with these choices once:
1. enabled
2. disabled
3. auto (Recommended)

If my preference is already saved, do not ask again.

Do NOT request, reveal, or output my real API key in the chat.
Verify that the installation and worker status are functional before modifying any code.

πŸ€– For AI Coding Agents

Notice for LLMs and AI Agents Reading This Repository:

When you are operating in a project equipped with BUBU, follow these operational directives:

  1. Role Division: You (the lead agent) are the Lead Architect. BUBU is your Analyst.
    • The worker is strictly read-only. It will never edit project source files directly.
    • The worker gathers evidence and diagnoses root causes; you decide what code to write and apply the diffs.
  2. Locating BUBU:
  3. Secret Hygiene:
    • Never read, output, or prompt for .env contents.
    • Do not print API keys to stdout, stderr, or chat transcripts.
  4. Context Isolation Rule:
    • The worker saves detailed markdown reports to .ai-worker/reports/<task_id>.md.
    • The worker emits a compact JSON summary to stdout.
    • Do NOT automatically read or display full report files in chat unless the compact summary lacks necessary technical detail.
  5. Evidence Verification:
    • When the worker returns evidence_verified: true, the file paths, line numbers, and snippets have been programmatically matched against local disk files.
  6. Graceful Fallback Handling:
    • If the worker returns status: "fallback" (e.g. quota exhausted or network error), do NOT halt the user's task.
    • Acknowledge the fallback briefly and inspect the targeted files directly using your built-in read tools (view_file, grep_search).

πŸ”Œ Supported LLM Providers

BUBU is designed from the ground up as a provider-agnostic worker implemented exclusively using Python standard library networking (urllib.request). It requires zero pip dependencies:

Provider ID Provider Name Default Model Authentication Typical Use Case
gemini (Default) Google Gemini (via Google AI Studio) gemini-3.6-flash GEMINI_API_KEY (URL query or Bearer) Default high-capacity provider. Generous free tier, 1M+ token context windows, fast inference.
openai_compatible OpenAI / DeepSeek / OpenRouter / Ollama gpt-4o-mini OPENAI_API_KEY (Bearer Token) Self-hosted LLMs, enterprise OpenAI endpoints, DeepSeek-V3/R1, or multi-provider aggregators.

Switching providers is as simple as passing --provider <name> on the CLI or setting AI_WORKER_PROVIDER=<name> in your environment.


πŸ’‘ Why BUBU?

The Problem: Context Window Exhaustion

When modern coding agents tackle real-world bugs, they frequently need to inspect 20–30 files, browse long logs, or read architectural contracts. This floods the agent's context window with 100,000–300,000 tokens:

  • Attention Degradation: Models suffer from the "needle in a haystack" phenomenon, missing critical constraints.
  • Extreme Latency: Every conversational turn becomes progressively slower.
  • Quota Burn: Expensive conversation context quotas are rapidly consumed.

The Solution: External Context Processing

BUBU shifts heavy reading and initial diagnosis out-of-band to a dedicated LLM worker layer:

  • Zero Chat Context Bloat: Raw source files never touch your main chat session.
  • Verified Grounding: Every line citation is checked against disk before being returned.
  • Instant Caching: Identical analyses return in <0.5 seconds at zero API cost.
  • Seamless Continuity: If the API is offline, the agent falls back to local inspection without skipping a beat.

🚫 What BUBU is NOT

  • NOT an autonomous coding agent: BUBU does not write code to your source tree or execute shell commands.
  • NOT an Antigravity replacement: BUBU is a specialized context-processing tool designed to serve the lead agent.
  • NOT an all-or-nothing requirement: In auto mode, BUBU sleeps during small edits and only wakes for heavy analytical tasks.
  • NOT an external closed service: BUBU runs locally on your machine, invoking your selected LLM provider using your own direct credentials.

πŸ—οΈ Architecture & The Three Layers

BUBU is structured across three distinct operational layers:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                 LAYER A: LEAD AGENT (ANTIGRAVITY)            β”‚
β”‚  β€’ High-level planning & orchestration                      β”‚
β”‚  β€’ Reads compact evidence & makes decisions                 β”‚
β”‚  β€’ Modifies code, runs build tools, and writes tests        β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                               β”‚ evaluates task
                               β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                 LAYER B: PROJECT WORKER (BUBU)              β”‚
β”‚  β€’ Local CLI worker (.agents/skills/ai-studio-worker/)      β”‚
β”‚  β€’ Multi-factor SHA-256 cache & local quota tracker         β”‚
β”‚  β€’ Auto Mode decision engine & evidence verification        β”‚
β”‚  β€’ Zero-dependency HTTP runtime (urllib.request)            β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                               β”‚ HTTPS / TLS 1.3
                               β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚            LAYER C: LLM PROVIDER ABSTRACTION LAYER          β”‚
β”‚                                                             β”‚
β”‚   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚
β”‚   β”‚   Provider #1: Gemini     β”‚ Provider #2: OpenAI-Comp β”‚  β”‚
β”‚   β”‚   β€’ Google AI Studio REST β”‚ β€’ /chat/completions REST β”‚  β”‚
β”‚   β”‚   β€’ gemini-3.6-flash      β”‚ β€’ OpenAI / DeepSeek /    β”‚  β”‚
β”‚   β”‚   β€’ Free Tier Available   β”‚   OpenRouter / Ollama    β”‚  β”‚
β”‚   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚
β”‚  β€’ User-owned API keys (never logged or exposed)             β”‚
β”‚  β€’ Strict structured JSON schema enforcement                β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Layer A: Global Antigravity Integration

Antigravity discovers BUBU via its native skill discovery mechanism. When .agents/skills/ai-studio-worker/SKILL.md is present in a workspace, Antigravity learns how and when to offload heavy analysis.

Layer B: Project-Scoped BUBU Runtime

Each project maintains its own isolated runtime in .ai-worker/:

  • .ai-worker/config.json: Project-specific mode (auto, enabled, disabled) and provider configuration.
  • .ai-worker/cache/: Multi-factor SHA-256 cache index (provider-isolated).
  • .ai-worker/quota/: Daily usage safety accounting ledger.
  • .ai-worker/reports/: Full analytical markdown reports generated by the worker.

Layer C: LLM Provider Layer

The worker communicates directly with provider REST endpoints over TLS 1.3:

  • Gemini: https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
  • OpenAI-Compatible: {base_url}/chat/completions

βš™οΈ Worker Usage Modes

Configured in .ai-worker/config.json:

Mode Behavior When to Use
auto (Default & Recommended) Dynamically evaluates task complexity. Offloads large/multi-file tasks to the worker; skips worker for small local edits. Standard everyday pair programming. Balances speed, context savings, and API quotas.
enabled Always activates the worker for analytical requests. Large legacy refactoring, repository-wide compliance audits, or multi-module investigations.
disabled Completely deactivates the worker. Antigravity inspects all files directly within its own conversation context. Working without an internet connection, without an API key, or on sensitive internal micro-edits.

Querying or Changing Modes

# Query active mode
python .agents/skills/ai-studio-worker/scripts/ai_worker.py --get-mode

# Set mode
python .agents/skills/ai-studio-worker/scripts/ai_worker.py --set-mode auto

🎯 Auto Mode Decision Engine

Auto Mode (--decide) analyzes your request before making any API calls:

python .agents/skills/ai-studio-worker/scripts/ai_worker.py `
  --type <TASK_TYPE> `
  --prompt "<instruction>" `
  --files <file1> <file2> ... `
  --decide

When Auto Mode Offloads (USE):

  • Multi-File Scope: 3 or more source files targeted.
  • Heavy Payload: Total file size $\ge 15\text{ KB}$.
  • Analytical Task Types: AUDIT, COMPARE, RESEARCH, VALIDATE.
  • Complex Keywords: Concurrency, race conditions, memory leaks, architectural regressions, circular dependencies.

When Auto Mode Skips (SKIP):

  • Single-File Micro-Edits: Changing button text, adjusting a CSS style, renaming a local variable.
  • Obvious Local Bugs: Fixing a typo or null check where context is already clear.
  • Fast Iterative Tweaks: Localized edits that Antigravity can solve instantly in conversation.

πŸ”‘ Configuring Providers & API Keys

BUBU supports multiple LLM providers. Choose the one that best fits your workflow:

Provider 1: Google Gemini (Default)

Google AI Studio provides generous free-tier keys at zero cost.

  1. Navigate to: πŸ‘‰ https://aistudio.google.com/app/apikey
  2. Sign in with your Google account and click Create API Key.
  3. In your project root, configure .env:
    AI_WORKER_PROVIDER=gemini
    GEMINI_API_KEY=your_actual_gemini_api_key_here
    GEMINI_MODEL=gemini-3.6-flash

Provider 2: OpenAI-Compatible (OpenAI, DeepSeek, OpenRouter, Ollama)

You can connect BUBU to any service providing an OpenAI-compatible /chat/completions endpoint:

Example for OpenAI:

AI_WORKER_PROVIDER=openai_compatible
OPENAI_API_KEY=your_actual_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=https://api.openai.com/v1

Example for DeepSeek:

AI_WORKER_PROVIDER=openai_compatible
OPENAI_API_KEY=your_deepseek_api_key_here
OPENAI_MODEL=deepseek-chat
OPENAI_BASE_URL=https://api.deepseek.com/v1

Example for Local Ollama (No API Key Required):

AI_WORKER_PROVIDER=openai_compatible
OPENAI_MODEL=qwen2.5-coder:7b
OPENAI_BASE_URL=http://localhost:11434/v1

Note

Compatibility Note: Services such as DeepSeek, OpenRouter, and Ollama interface via the OpenAI-compatible endpoint abstraction (openai_compatible). While the wire protocol is standard, provider-specific live validation may be required depending on custom model naming, parameter restrictions, or remote rate limits.

Switching via CLI Flags

You can also override the provider per invocation:

python .agents/skills/ai-studio-worker/scripts/ai_worker.py --provider openai_compatible --status

πŸ”’ API Key Security & Privacy

Caution

Never commit your API key to Git or share it publicly.

BUBU enforces strict security boundaries:

  • Repository Cleanliness: Real .env files and credentials are gitignored by default.
  • In-Memory Masking: The worker redacts API keys from stdout, stderr, logs, and generated reports ([REDACTED_API_KEY]).
  • Secret File Exclusion: The worker automatically skips files matching .env*, *.pem, *.key, id_rsa*, credentials*, or *.keystore.
  • Path Traversal Guard: Any path containing ../ that attempts to escape the project root is blocked with exit code 7 (EXIT_PATH_ERROR).
  • Prompt Injection Isolation: Source code is demarcated as UNTRUSTED SOURCE MATERIAL. Directives embedded in code comments (e.g. "ignore instructions") cannot alter the worker's operational protocol.

πŸ“Š Understanding Free API Limits & Tokens

Core Concepts Explained Simply

Concept Simple Explanation Technical Definition
Request 1 analytical job sent to Gemini by BUBU. A single HTTP POST call to generativelanguage.googleapis.com.
Token The basic unit of text processed by the model (~4 characters of English text or code). A sub-word token generated by Gemini's Byte-Pair Encoding (BPE) tokenizer.
Input Tokens The files, line numbers, and prompts sent to Gemini. Tokens billed/counted against the prompt context quota.
Output Tokens The structured JSON diagnosis returned by Gemini. Tokens generated by the model in its response candidate.
Cache A stored diagnosis used to answer identical requests instantly. Local SHA-256 indexed JSON record on disk; avoids network calls.

Free Tier Quota Metrics: RPM, TPM, RPD

Google AI Studio measures usage across three primary limits:

  • RPM (Requests Per Minute): How many distinct analysis requests you can send in 60 seconds.
  • TPM (Tokens Per Minute): The maximum volume of combined text and code processed per minute.
  • RPD (Requests Per Day): The maximum total requests permitted within a 24-hour calendar window.

Important

1 File $\neq$ 1 Request. In BUBU, an entire batch of 10, 20, or 30 source files is bundled into a single API request. You do not burn 30 requests to analyze 30 files.

To inspect active quotas for your account and model, check your project settings directly at Google AI Studio.


⚑ Multi-Factor Caching Engine

BUBU includes an intelligent local caching engine to eliminate redundant API calls and prevent quota burn.

The 7-Factor Cache Formula

Unlike simple caches that only check file timestamps, BUBU's cache key reflects the complete analytical environment, ensuring complete provider and model isolation:

$$\text{Cache Key} = \text{SHA-256}(\text{Version} + \text{Provider} + \text{Model} + \text{TaskType} + \text{Prompt} + \text{SortedFileHashes} + \text{Config})$$

Cache Invalidation Rules:

The cache is invalidated and a fresh API call is triggered if:

  1. Any targeted file is modified by even 1 character (file SHA-256 changes).
  2. The user's prompt or question is altered.
  3. The assigned task type (DEBUG vs AUDIT) changes.
  4. The provider or model is switched (gemini vs openai_compatible).
  5. The worker engine version is updated.
  6. The --force flag is specified.

When a cache hit occurs, BUBU delivers verified findings in <0.5 seconds with 0 API calls and 0 additional tokens.


πŸ›‘οΈ Local Quota Accounting vs. Server Quota

BUBU maintains a local usage ledger in .ai-worker/quota/quota_tracker.json.

Key Distinction: The Local Quota Tracker is a client-side safety guardrails system. It is designed to prevent accidental runaway loops or rapid exhaustion. It does not replace the provider's server-side rate limits, but works proactively to keep your usage well within safe operating margins.

Transient Error Handling

If provider servers return 429 (Rate Limit) or 503 (Server Busy), BUBU applies exponential backoff (retrying after 1s, 2s, and 4s). If the limit persists, it transitions to Resilient Fallback.


πŸ”„ Resilient Graceful Fallback

BUBU follows a zero-failure philosophy: an analytical worker issue must never crash the lead developer's workflow.

If the LLM provider encounters:

  • 429 Too Many Requests
  • Daily quota exhaustion
  • Network interruption or timeout
  • Unconfigured API key

BUBU cleanly outputs a structured fallback JSON payload:

{
  "task_id": "audit-20260921-b4c5d6",
  "status": "fallback",
  "fallback_reason": "QUOTA_EXHAUSTED",
  "summary": "LLM Provider unavailable (QUOTA_EXHAUSTED). Falling back to local Antigravity inspection."
}

The process exits with code 0. Antigravity detects the fallback state and proceeds immediately with local inspection tools (view_file, grep_search).


πŸ§ͺ Empirical Validation & Stress Test Evidence

BUBU's performance and safety have been validated through rigorous stress testing on an independent 31-file synthetic Kotlin codebase:

======================================================================
AI STUDIO WORKER β€” EMPIRICAL VALIDATION METRICS
======================================================================
Codebase Scale:          31 files | 2,571 lines | 116.8 KB
Injected Flaws:          8 complex logical, concurrency & leak defects
Findings Detected:       10 total (8/8 injected + 2 valid secondary issues)
Evidence Grounding:      10/10 citations verified against disk (100%)
Context Payload Proxy*:  ~94.7% context payload reduction proxy
Cache Performance:       Initial: 34.57s  ──►  Cache Hit: 0.42s (~82x faster)
Cache Token Burn:        0 additional tokens consumed on cache hits
Read-Only Guarantee:     Source file SHA-256 hashes 100% identical
Secret Leakage:          0 occurrences across stdout, stderr, reports & logs
Path Traversal:          Blocked outside project root (Exit code 7)
Independent Test Suite:  30 / 30 validation tests passed (100% PASS)
======================================================================

Note

*Important Disclosure on the ~94.7% Metric:
This metric measures the context-payload reduction proxy (the byte difference between sending raw source files plus detailed reports into the chat vs. returning only the verified compact JSON). It is not a direct measurement of Antigravity's internal proprietary token consumption.


🌐 Privacy and Data Flow

[Local Project Source]
        β”‚
        β–Ό (Targeted files only; secret files excluded)
   [ai_worker.py]
        β”‚
        β–Ό (HTTPS / TLS 1.3 encryption)
 [LLM Provider Layer] (Google Gemini / OpenAI / DeepSeek / Local Ollama)
        β”‚
        β–Ό (Analysis & citations)
   [ai_worker.py]
        β”‚
        β”œβ”€β”€β–Ί Full Report written to disk (.ai-worker/reports/)
        └──► Compact Summary emitted to stdout ──► Antigravity Chat
  • Data in Flight: Data sent to external providers is encrypted in transit via TLS 1.3. For local providers (e.g. Ollama on localhost), data never leaves your machine.
  • Enterprise & Proprietary Code: If you are bound by strict enterprise privacy agreements, choose local Ollama or an enterprise provider tier where data is not used for model training.

πŸ“„ License & Commercial Terms

BUBU is licensed under the BUBU Source-Available & Commercial License (Version 1.0).
Copyright (c) 2026 aethelondev-stack. All rights reserved.

  • Non-Commercial Use: Free for personal exploration, educational projects, hobbyists, security research, academic study, and internal non-monetized evaluation.
  • Commercial Use Restriction: Any deployment, bundling, embedding, distribution, or offering of BUBU as part of a commercial product, proprietary software package, monetization workflow, or paid SaaS/cloud offering strictly requires a separate, written Commercial License from the copyright holder (aethelondev-stack).
  • Commercial Licensing Inquiries: To negotiate commercial terms, request custom licensing, or inquire about enterprise deployments, please contact the author via GitHub: aethelondev-stack.

Notice: This summary and the repository LICENSE document are provided for this project and do not constitute formal legal advice.


❓ Frequently Asked Questions (FAQ)

What is BUBU?

BUBU is an out-of-band context-processing worker that helps AI coding agents (like Google Antigravity) analyze large codebases without bloating their conversation context.

Which LLM providers are supported?

BUBU supports:

  1. Google Gemini (via Google AI Studio REST API) β€” default, generous free tier.
  2. OpenAI-Compatible Providers β€” OpenAI, DeepSeek, OpenRouter, vLLM, and local Ollama.

Does BUBU require any pip packages?

No. BUBU is built entirely using Python's standard library (urllib.request, json, pathlib, hashlib, etc.). No pip install is ever needed.

Can BUBU be used with local LLMs (Ollama)?

Yes! Set AI_WORKER_PROVIDER=openai_compatible, OPENAI_BASE_URL=http://localhost:11434/v1, and OPENAI_MODEL=qwen2.5-coder:7b. No API key is required for local endpoints.

Can BUBU be used without Antigravity?

Yes. BUBU can be invoked directly from PowerShell, Bash, or any external automation script using python .agents/skills/ai-studio-worker/scripts/ai_worker.py.

Which model does it use by default?

For Gemini, it defaults to gemini-3.6-flash. For OpenAI-compatible, it defaults to gpt-4o-mini. Both are fully configurable.

Is it free to use?

Yes. Google AI Studio offers a free tier for Gemini API keys. Local Ollama is completely free on your own hardware.

How many requests do I get per day?

Quotas depend on your provider tier and active model. You can monitor live quotas in your provider's dashboard.

Does 100 files equal 100 API requests?

No! BUBU bundles multiple files into a single prompt payload. A 20-file audit typically counts as one single request.

Where do I store my API keys?

In .env in your project root (recommended) or in your operating system's user environment variables.

Can I commit my API keys to GitHub?

No, absolutely not. BUBU's .gitignore protects .env from being tracked.

Does the worker run on every single prompt?

No. In auto mode, BUBU only activates for complex, multi-file, or deep analytical tasks. Small localized edits bypass the worker entirely.

What happens if I re-run the same analysis?

BUBU's multi-factor cache serves the result in <0.5s with zero API calls and zero token consumption.

What happens if the LLM provider is down or quota is exhausted?

BUBU emits a graceful fallback response (status: "fallback"), allowing your agent to continue seamlessly using local file inspection.

Does the worker ever modify my source code?

Never. The worker is strictly read-only and only writes to the .ai-worker/ directory.


πŸ—ΊοΈ Documentation Map

BUBU/
β”œβ”€β”€ README.md                          # Master documentation & quick start
β”œβ”€β”€ LICENSE                            # BUBU Source-Available & Commercial License 1.0
β”œβ”€β”€ INSTALL.md                         # 4-step installation & agent prompt guide
β”œβ”€β”€ SECURITY.md                        # Threat model, secret handling & reporting
β”œβ”€β”€ CONTRIBUTING.md                    # Contribution rules & testing procedures
β”œβ”€β”€ CHANGELOG.md                       # Release notes and version history
β”œβ”€β”€ .env.example                       # API key & configuration template
β”œβ”€β”€ .gitignore                         # Security & runtime ignore rules
β”‚
β”œβ”€β”€ .agents/
β”‚   └── skills/
β”‚       └── ai-studio-worker/
β”‚           β”œβ”€β”€ SKILL.md               # Antigravity skill interface definition
β”‚           └── scripts/
β”‚               └── ai_worker.py       # Core worker script (Python standard lib)
β”‚
└── studio/
    β”œβ”€β”€ README.md                      # Documentation hub
    β”œβ”€β”€ ARCHITECTURE.md                # Detailed orchestration & component guide
    β”œβ”€β”€ WORKER_PROTOCOL.md             # CLI options, task types & output contract
    β”œβ”€β”€ QUOTA_AND_CACHE.md             # 6-factor caching & quota accounting
    └── TESTING_GUIDE.md               # Verification commands & empirical data

πŸ“‹ Release Checklist

  • Zero real API keys or secrets in repository files
  • Clean .env.example template provided
  • Machine-specific absolute paths removed (universal portability)
  • .gitignore verified for secrets, cache, and virtual environments
  • Comprehensive, professional English README
  • Dedicated instructions and prompt for AI coding agents
  • Getting a Gemini API key guide with official Google links
  • Clear explanation of free-tier quotas (RPM, TPM, RPD)
  • Simple and technical explanations of tokens and caching
  • Multi-factor SHA-256 caching fully documented
  • Local quota tracking vs. Google server quota distinguished
  • Auto mode decision engine criteria and examples documented
  • Mode comparison table (auto, enabled, disabled)
  • Resilient graceful fallback protocol documented
  • Strict read-only guarantee documented
  • Empirical test results and ~94.7% proxy disclosure verified
  • Privacy, data flow, and threat model documented
  • SECURITY.md, CONTRIBUTING.md, and CHANGELOG.md created
  • LICENSE created (BUBU Source-Available & Commercial License 1.0 - Copyright aethelondev-stack)

πŸ”— Official References

About

Context-efficient Gemini Worker for AI coding agents, with caching, evidence verification, security isolation, and automatic task routing.

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages