Kingod Brainstormer

Terminal-first local AI brainstorming, memory, planning, and deep research for extreme vibe coders.

Kingod is built for the moment where you want to think, plan, research, checkpoint, and ship without opening five slow workspaces. It starts as a TUI, stores your work as local Markdown/JSONL, uses cheap local-first defaults, and exposes MCP tools so coding agents can use the same memory.

One-Line Install

macOS and Ubuntu:

curl -fsSL https://raw.githubusercontent.com/claudianus/kingod-brainstormer/main/scripts/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/claudianus/kingod-brainstormer/main/scripts/install.ps1 | iex

Then launch the TUI:

kgb

The installers verify Node.js >= 20.11, install a user-space runtime when possible, install kingod-brainstormer globally, and run kgb doctor.

Direct npm install:

npm install -g kingod-brainstormer
kgb

What You Get

• Fast TUI cockpit: capture, ask, plan, research, graph, timeline, checkpoint, backup.
• Local-first vault: readable Markdown plus append-only JSONL events in ~/.kingod-brainstormer.
• Hybrid local search: keyword, deterministic vector similarity, lexical fallback, and reciprocal rank fusion.
• Cited local answers: kgb ask and kgb brief keep sources visible.
• Deep research lane: SearxNG first, optional DuckDuckGo HTML fallback, local evidence fallback.
• Local rollback: full-vault checkpoints with preview and reversible restore.
• Backup lanes: GitHub diffable backup plus encrypted portable bundles.
• MCP server: agents can search, ask, capture, brief, checkpoint, and back up through one small tool surface.
• Optional AI: Ollama first, OpenAI-compatible APIs second, deterministic fallback when no model is configured.

First Five Minutes

kgb capture "Build a local-first research cockpit for my current project" --tag idea
kgb ask "What am I trying to build?"
kgb plan "Ship the smallest useful version this week"
kgb checkpoint create "before importing old notes"
kgb

For a full mission brief:

kgb brief "Turn my current project into a shippable plan"

For activity review:

kgb timeline
kgb graph "current project"

TUI Hotkeys

• c: capture an idea
• a: ask local memory
• p: create a plan
• b: create an execution board
• f: create a mission brief
• r: run research
• i: ingest files or folders
• g: build a knowledge graph
• l: show activity timeline
• v: run quality audit
• x: create a local checkpoint
• m: write backup manifest
• s: run security scan
• u: GitHub backup dry-run
• /: search local memory
• q: quit

Core Commands

kgb init
kgb capture "idea text" --tag cli --tag ai
kgb ingest ./docs --tag seed
kgb search "local-first memory"
kgb ask "What have we learned?"
kgb context "current project"
kgb graph "current project"
kgb timeline "current project"
kgb plan "Build the 10x local-first planning tool"
kgb board "Build the 10x local-first planning tool"
kgb brief "Ship a local-first AI planning cockpit"
kgb quality "local-first memory"
kgb research "Notion Obsidian user pain points AI research local-first" --depth 2 --max 4
kgb watch ./docs --tag watched

Default vault:

~/.kingod-brainstormer

Use an isolated vault:

KINGOD_HOME=/tmp/kingod-lab kgb

Local Checkpoints

Checkpoints are for fast rollback during risky imports, refactors, and agent runs. They are local-only and ignored by GitHub backup by default.

kgb checkpoint create "before importing old notes"
kgb checkpoint list
kgb checkpoint preview latest
kgb checkpoint restore latest --dry-run
kgb checkpoint restore latest

Restore moves any non-empty target aside before writing the snapshot, so rollback remains reversible.

GitHub Backup

GitHub backup is intentionally diffable. Agents and humans can review Markdown, JSONL events, and manifests.

kgb backup status
kgb backup scan
kgb backup manifest
kgb backup diff
kgb backup github yourname/kingod-brainstormer-vault --dry-run
kgb backup github yourname/kingod-brainstormer-vault
kgb backup restore yourname/kingod-brainstormer-vault --target ~/.kingod-brainstormer-restored --dry-run
kgb backup sync --dry-run

Backups are blocked by default when high-confidence secrets are detected.

Encrypted Bundles

Encrypted bundles are the sealed portable lane. The bundle contents are encrypted with AES-256-GCM, while the plaintext manifest keeps only file paths, sizes, timestamps, and SHA-256 hashes so restore impact can be inspected without exposing note bodies.

export KINGOD_BACKUP_PASSPHRASE='use-a-long-passphrase-here'
kgb backup bundle --output ~/kingod-vault.kgbundle
kgb backup preview-bundle ~/kingod-vault.kgbundle --target ~/.kingod-brainstormer-restored
kgb backup restore-bundle ~/kingod-vault.kgbundle --target ~/.kingod-brainstormer-restored --dry-run
kgb backup restore-bundle ~/kingod-vault.kgbundle --target ~/.kingod-brainstormer-restored

AI Providers

Local Ollama:

ollama serve
export KINGOD_OLLAMA_MODEL=llama3.1:8b

OpenAI-compatible endpoint:

export KINGOD_OPENAI_BASE_URL=https://api.openai.com/v1
export KINGOD_OPENAI_API_KEY=...
export KINGOD_OPENAI_MODEL=gpt-4.1-mini

Search provider:

export KINGOD_SEARXNG_URL=http://localhost:8080

Experimental no-key web fallback:

export KINGOD_ENABLE_DDG=1

MCP

Run:

kgb mcp

Tools exposed:

• kgb_search
• kgb_context
• kgb_ask
• kgb_capture
• kgb_graph
• kgb_timeline
• kgb_brief
• kgb_quality
• kgb_checkpoint_create
• kgb_checkpoint_list
• kgb_checkpoint_preview
• kgb_checkpoint_restore
• kgb_backup_github
• kgb_backup_manifest
• kgb_backup_diff
• kgb_backup_bundle
• kgb_restore_github
• kgb_restore_bundle
• kgb_preview_bundle_restore
• kgb_security_scan

The surface is deliberately small: broad tools, low context overhead, local state.

Development

npm install
npm run typecheck
npm test
npm run build
npm run dev

Product Thesis

Big GUI knowledge tools are powerful but leak momentum through latency, sync ambiguity, search brittleness, plugin drift, and AI cost opacity. Kingod chooses the opposite trade: terminal speed, local files, explicit citations, cheap/local AI paths, checkpoint rollback, and agent-readable memory.

See docs/research.md for the research synthesis that shaped the build.