deliberate-ai

v1.0.2

Published

9 days ago

Deep Ideation, Multi-Agent Deliberation & Systematic Thinking Engine for AI Coding Agents

Deliberate ⚡

Deep Ideation, Multi-Agent Deliberation & Systematic Thinking Engine for AI Coding Agents.
Empowers Claude Code, Antigravity, Codex, Devin, and Cursor with structured "System 2" reasoning before writing code.

🚀 Quick Run in 15 Seconds (Zero Install)

# 1. Multi-round dialectical brainstorm with visual browser dashboard & ADR
npx deliberate-ai brainstorm "Designing a lock-free distributed ring buffer" \
  --rounds 2 \
  --show-debate \
  --adr ./docs/adr/ADR-001.md \
  --ui

# 2. Automated Git Pre-Push Protection Hook
npx deliberate-ai hook install

# 3. Pre-PR Git diff adversarial red-teaming
npx deliberate-ai red-team --git --export ./audit-report.md

# 4. Interactive council interview Q&A ("Grill Me" mode)
npx deliberate-ai interview "Real-time collaborative canvas with 10k users"

📖 Table of Contents

🎯 The Problem: "First-Token Greediness"

When AI coding agents (Claude Code, Antigravity, Devin, Codex) tackle non-trivial architecture or migration tasks, they typically suffer from First-Token Greediness—immediately generating standard boilerplate on token #1 without exploring alternative paradigms, stress-testing edge cases, or weighing Pareto trade-offs.

Deliberate is a dedicated open-source deliberation library, CLI, and Model Context Protocol (MCP) server that injects systematic, high-order thinking into any AI coding workflow.

 User Goal ──► [ Systematic Ideation Topologies ] ──► [ Adversarial Council ] ──► [ Dialectical Synthesis ]
                • First-Principles                     • The Principal Architect   • Pareto Trade-Off Matrix
                • Inversion (Anti-Problem)             • The Ruthless Contrarian   • Hard Invariants
                • TRIZ Contradictions                  • The Performance Hacker    • Actionable Blueprint
                • SCAMPER Mutations                    • The DX Purist             • Implementation Steps
                • Tree-of-Thoughts                     • The Security Auditor
                                                       • The Pragmatist (YAGNI)

⚡ Quickstart in 30 Seconds

Export your preferred LLM key and run instantly with npx:

# 1. Set your API key
export GEMINI_API_KEY="your-gemini-key"      # or ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY

# 2. Run Deliberate Brainstorming
npx deliberate-ai brainstorm "Real-time state sync for collaborative canvas with 10k users"

(Or install globally: npm install -g deliberate-ai)

🎛️ Interactive Model & Council Persona Selector

Deliberate comes with an interactive terminal wizard that lets you configure your models:

# Launch the interactive configuration wizard
npx deliberate-ai config

# Or pass -i to configure before running a brainstorm
npx deliberate-ai brainstorm "Multi-tenant auth engine" -i

You can choose between two modes:

Unified (One Model for All): Uses a single provider (e.g. Gemini 2.5 Flash, Claude 3.7, or GPT-4o) across all topologies and council debates.
Council Mix-and-Match (Elite Multi-Agent Diversity): Assign specialized models to different personas for maximum cognitive diversity:
- 🏛️ The Principal Architect ➔ Anthropic Claude 3.7 Sonnet
- 🥊 The Ruthless Contrarian ➔ DeepSeek-R1 Reasoner
- ⚡ The Performance Hacker ➔ Google Gemini 2.5 Flash
- 💎 The DX & Ergonomics Purist ➔ Anthropic Claude 3.7 Sonnet
- 🛡️ The Security Auditor ➔ OpenAI GPT-4o
- 🔨 The Pragmatist ➔ Local Ollama / Llama 3.3
- ⚡ Master Synthesizer ➔ Anthropic Claude 3.7 Sonnet

(Configurations are saved automatically to ./deliberate.config.json or ~/.deliberaterc)

🔑 How to Configure Your LLM Provider

Deliberate natively connects directly to frontier LLMs or free local models:

1. Cloud Providers

2. Free & 100% Offline Local Models (Ollama)

If you don't want to use API keys, start Ollama locally:

ollama run deepseek-r1:14b
# Deliberate auto-detects localhost:11434 with zero configuration!
npx deliberate-ai brainstorm "Design an in-memory ring buffer" --provider ollama

🛠️ Detailed How-To Guides

1. How to Brainstorm a System Architecture

Use brainstorm when designing new features, services, or data pipelines:

# Standard Balanced Deliberation (Topologies + 6 Personas)
npx deliberate-ai brainstorm "Multi-tenant auth engine with row-level security"

# Deep Tree-of-Thoughts Exploration with hard constraints
npx deliberate-ai brainstorm "Distributed cache with sub-ms p99 latency" \
  --mode deep-explore \
  --constraints "Zero external Redis daemons" "Memory bounded at 128MB"

# Fast 10-Second Sanity Check
npx deliberate-ai brainstorm "State management for offline-first React app" --mode flash

2. How to Red-Team Existing Source Code

Use red-team to find race conditions, security vulnerabilities, memory leaks, and missing invariants in an existing file:

npx deliberate-ai red-team ./src/billing/transfer.ts \
  --goal "Ensure zero double-spending under concurrent API requests"

3. How to Summon Specific Council Personas

If you only want specific expert viewpoints (e.g. Security + Performance):

npx deliberate-ai council "Migrate SQLite to distributed Raft" \
  --personas architect performance security

4. How to Connect to Claude Code (MCP)

Add deliberate-ai to Claude Code so Claude automatically deliberates before generating code:

claude mcp add deliberate npx -y deliberate-ai mcp

Now in Claude Code:

"Claude, re-architect our WebSocket ingestion layer to handle 50,000 concurrent connections."
Claude will automatically call deliberate_brainstorm and follow the synthesized Pareto blueprint!

5. How to Install into Google Antigravity

Install the Deliberate skill into Antigravity with 1 command:

mkdir -p ~/.gemini/antigravity/skills/deliberate
curl -sSL https://raw.githubusercontent.com/shanmukhaditya/deliberate/main/integrations/antigravity/SKILL.md > ~/.gemini/antigravity/skills/deliberate/SKILL.md

Now in Antigravity chat:

"Use deliberate to brainstorm a zero-downtime database partitioning strategy."

6. How to Use in Cursor, Windsurf & GitHub Copilot

For Cursor / Windsurf:

Drop the rules into your project:

curl -sSL https://raw.githubusercontent.com/shanmukhaditya/deliberate/main/integrations/cursor/.cursorrules > .cursorrules

For GitHub Copilot & Codex:

Add instructions to your repo:

mkdir -p .github
curl -sSL https://raw.githubusercontent.com/shanmukhaditya/deliberate/main/integrations/antigravity/SKILL.md > .github/copilot-instructions.md

7. How to Use the Programmatic SDK

In TypeScript / Node.js:

import { deliberate } from 'deliberate-ai';

const result = await deliberate.brainstorm({
  goal: "Design high-throughput event streamer with zero external dependencies",
  mode: "council",
  provider: "gemini", // or "anthropic", "openai", "deepseek", "ollama"
  constraints: ["p99 < 1ms", "Bounded memory at 64MB"]
});

console.log("Winning Architecture:", result.blueprint.winningArchitecture.title);
console.log("Hard Invariants:", result.blueprint.coreInvariants);
console.log("Implementation Steps:", result.blueprint.implementationSteps);

In Python / OpenAI Codex:

from deliberate_codex import Deliberate

result = Deliberate.brainstorm(
    goal="Design an in-memory lockless ring buffer",
    mode="council",
    provider="gemini"
)
print(result["stdout"])

🧠 The 6 Adversarial Personas

Unlike polite chat models that agree with everything, Deliberate personas enforce strict, anti-sycophantic loss functions:

🔬 The 5 Systematic Ideation Topologies

Deliberate replaces vague prompting with formal inventive heuristics:

First-Principles Deconstruction: Strips framework assumptions down to raw I/O, memory bandwidth, and computational constraints.
Inversion (The Anti-Problem / Jacobi's Rule): Simulates worst-case catastrophic failure modes, then inverts every failure into a non-negotiable Architectural Invariant.
TRIZ Contradiction Resolution: Eliminates inherent engineering trade-offs (e.g. Query Latency vs. Memory Overhead) using inventive principles.
SCAMPER Architectural Mutation: Mutates designs through 7 operators (Substitute, Combine, Adapt, Modify, Put to use, Eliminate, Reverse).
Tree-of-Thoughts Pareto Exploration: Generates 3-4 distinct architectural branches and computes Pareto scores across DX, Performance, Simplicity, and Security.

🔒 Privacy & Security FAQ

Where do my prompts and code go?

Prompts go directly and only to your chosen LLM provider (Google, Anthropic, OpenAI, DeepSeek) over encrypted HTTPS using your own API key. If you use Ollama, zero data leaves your laptop. There are no middleman servers, no proxy relays, and no telemetry.

Can I use this without any API keys?

Yes! Install Ollama and run ollama run deepseek-r1:14b (or llama3.3). Deliberate auto-detects local Ollama on localhost:11434.