⚔️ Antigravity Campaigns Plugin

High-Speed Strategic Task Engine, Tactical Strike Coordinator & Double-Entry Treasury HUD for AI Agents

📖 The Story Behind Campaigns & The Sovereign Ecosystem

Heavyweight productivity platforms and complex enterprise managers (like Stratagem) offer deep features, but come at a steep operational cost: heavy system resource consumption, slow database latencies, and clunky interfaces.

Campaigns was born from a simple realization:

You don't need gigabytes of electron bloat or cloud vendor lock-in to achieve peak personal execution. You need a rock-solid, sub-millisecond local relational state machine that your AI assistant can drive effortlessly.

The Campaigns architecture provides a unified ecosystem across three specialized tools:

• 🖥️ Campaigns Desktop Command Center: High-speed, local-first Svelte 5 & Electron desktop UI for human operators.

• 🤖 Antigravity Campaigns Plugin: Autonomous AI FastMCP server operating directly on the exact same SQLite database.

• ♟️ Stratagem Command Matrix: Deep cinematic macro-strategic life planning and institutional analysis matrix.

Related MCP server: DataBook

🗺️ Dual Terminology Bridge: Everyday Productivity vs. Tactical Command

Whether you think like a software project manager or a tactical operational commander, Campaigns speaks your language:

🏛️ System Architecture

Deep Developer Documentation: For complete relational DDL schemas, ER diagrams, strict state machines, and token minimization protocols, see docs/ARCHITECTURE.md.

┌─────────────────────────────────────────────────────────────────────────────┐
│                       GOOGLE ANTIGRAVITY AGENT / MCP HOST                   │
│                    (Antigravity CLI · Claude Desktop · Cursor)              │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ JSON-RPC (stdio)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    ANTIGRAVITY CAMPAIGNS PLUGIN (mcp/server.py)             │
├─────────────────────────────────────────────────────────────────────────────┤
│ 🛡️ Strict Whitelist & Type Sanitizer (Foreign Key Enforcement)             │
├──────────────────────────────────────┬──────────────────────────────────────┤
│ 📋 Project Lifecycle Engine          │ 🎯 Daily Strike Coordinator          │
│ 🌳 Subtask Checkpoint Hierarchy      │ 🏷️ Uppercase Taxonomy & Tag Indexer  │
│ 💰 Double-Entry Treasury Ledger      │ 👥 Counterparty Directory Dossier    │
│ 🩺 Health & Integrity Auditor        │ ⚡ Parameterized SQL Query Engine    │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │ SQLite WAL Driver (Sub-millisecond)
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        CAMPAIGNS SQLITE DATABASE                            │
│                 `%APPDATA%\Campaigns\Database\campaigns.sqlite`             │
│       [ Tasks · Subtasks · Strikes · Tags · Counterparties · Treasury ]     │
└─────────────────────────────────────────────────────────────────────────────┘

⚡ AI-First Architecture: "Minimum Token Consumption, Maximum Speed"

Autonomous agents face tight context windows and round-trip latency. Campaigns is architected to minimize tokens and maximize speed:

• 📉 Compact List Payloads (80–85% Token Reduction): campaigns_list_tasks defaults to include_description: false, omitting multiline text to preserve LLM context. Set include_description: true only when inspecting a single task runbook.

• 🌳 1-Shot Multi-Subtask Inception: Pass subtasks: ["Milestone 1", "Milestone 2"] directly to campaigns_create_task. The server creates the project and its entire milestone tree in a single atomic transaction—turning 5 tool calls into 1.

• 🎯 1-Shot Foreign-Key Resolution: Pass task_title directly to campaigns_create_strike. The server dynamically resolves foreign keys in SQLite, eliminating redundant search calls.

• ⚡ Flat Top-Level Mutation Shortcuts: Update arguments directly at the top level without verbose nested fields: {} payloads.

• 📅 Deterministic Relative Date Engine: Pass natural expressions like today, tomorrow, +3d, +2w, +1m, eom, monday, or friday. The server parses exact calendar dates natively.

• 💰 Horizon-Segmented Runway Telemetry: campaigns_get_treasury_dashboard delivers immediate 7-day and 30-day cash flow runways in a single pass.

🛠️ Tool Catalog (20 Native Operations)

🚀 Quickstart & Setup

Pathway A: Google Antigravity Plugin (Recommended)

1. Clone or copy into your local Antigravity plugins directory:

   git clone https://github.com/karansinghverma979/antigravity-campaigns-plugin.git ~/.gemini/config/plugins/campaigns-plugin

2. Antigravity automatically detects plugin.json, loads the campaigns skill (skills/campaigns/SKILL.md), and registers the autonomous agent (agents/campaigns.md).

Pathway B: Universal FastMCP Server (Claude Desktop, Cursor, Zed)

1. Install dependencies:

   pip install mcp>=1.0.0

2. Initialize database:

   python mcp/init_db.py

3. Add to your client config:

For Antigravity mcp_config.json:

{
  "mcpServers": {
    "campaigns-mcp": {
      "command": "python",
      "args": [
        "C:\\Users\\<YourUsername>\\.gemini\\config\\plugins\\campaigns-plugin\\mcp\\server.py"
      ],
      "disabled": false
    }
  }
}

For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "campaigns": {
      "command": "python",
      "args": [
        "/path/to/antigravity-campaigns-plugin/mcp/server.py"
      ]
    }
  }
}

🗄️ Database Lifecycle, Invariants & Real-Time GUI Synchronization

1. Zero-Precondition Auto-Creation

If campaigns.sqlite does not exist on your computer, the MCP server automatically provisions the entire database on cold boot:

• Auto-creates the database directory (%APPDATA%\Campaigns\Database\ on Windows, ~/.local/share/campaigns/ on Linux/macOS, or via CAMPAIGNS_DB_PATH).

• Auto-executes the canonical DDL schema, provisioning all 6 tables (Tasks, Tags, Subtasks, Strikes, Counterparties, Treasury) and 13 indexes in <1ms.

• Zero manual SQL scripts or pre-configuration needed.

2. Strict Schema Rules & Allowed Entries

All agent actions are enforced against canonical business invariants:

• Zero-Time Calendar Dates: Strictly DD-MM-YYYY (e.g. 20-09-2026). Timestamps, hours/minutes, and ISO strings are strictly banned. Natural dates (today, tomorrow, +3d, monday, eom) auto-resolve to DD-MM-YYYY.

• Task Priorities: Strictly 3 levels: 'High', 'Medium', 'Low'.

• State & Stage Matrix:

  • Arsenal ➔ ['RawIntel', 'Strategizing']

  • Execution ➔ ['Active', 'Executing']

  • Breach ➔ ['Overdue', 'Breach']

  • Archive ➔ ['Victory', 'Aborted']

• Strike Statuses: Capitalized case: 'Standby', 'Engaged', 'Neutralized', 'Aborted', 'Pending', 'Template', 'Undated'. Finished strikes are saved strictly as 'Neutralized'.

• Subtasks: Capitalized case ('Initiated', 'Doing', 'Completed', 'Failed'). Creation date is strictly created_at.

• Treasury: Symmetrical 'Payable' and 'Receivable' flows with linked counterparties.

• Ministers: 4 focal disciplines: 'Adhipati', 'Bhakta', 'Antaryami', 'Jigyasu'.

• Tags: Strictly single-word UPPERCASE with underscores (e.g. MOTOR_WINDING).

3. Real-Time Desktop GUI Synchronization (Ctrl+R)

If you run the Campaigns Electron Desktop Application alongside Antigravity:

• Both systems execute concurrently on SQLite WAL (Write-Ahead Log) without file locking.

• When AI agents mutate projects, strikes, or cash flow via MCP, press Ctrl+R in the Campaigns Desktop App (or select CAMPAIGNS Menu ➔ Hard Reload (Ctrl+R)) to immediately rehydrate all UI stores from disk.

🔒 Security, Privacy & OpenSSF Standards

• Zero Machine Path Leaks: Fully supports CAMPAIGNS_DB_PATH environment variable with dynamic fallback across Windows (%APPDATA%) and Linux/macOS (~/.local/share/).

• Data Isolation: Database files (*.sqlite, *.db) are permanently quarantined outside git tracking.

• OpenSSF Hardened Workflows: All GitHub Actions workflows declare permissions: contents: read and pin dependencies to immutable 40-character commit SHAs.

• Vulnerability Disclosure: Governed by standard SECURITY.md guidelines.

Maintained by Karan Singh Verma · Released under the MIT License