Gaius

A terminal interface for navigating graph-oriented data domains. Projects high-dimensional embeddings onto a 19×19 grid.

Overview

Gaius renders knowledge bases and document collections as spatial layouts, using topological data analysis to identify structural patterns. The interface combines a Go board metaphor with orthographic projections and multi-agent analysis.

Named after Gaius Plinius Secundus (Pliny the Elder).

Philosophy

The Gaius Project deliberately supports continuous agent collaboration at every level. Dynamic agent interaction spans all components: from knowledge base analysis with local SLM swarms, to operations-oriented agents powered by special purpose models (Orchestrator-8B, Magma-8B), to periodic content-informed reasoning and reflection.

This extends to long-term codebase development itself, in collaboration with Claude Code. This is a deliberate departure from the traditional paradigm where software is developed to a point release, then packaged for end users. Gaius is intended to be cloned, not packaged—engineered to provide a foundation for agent collaboration in any knowledge domain, such that the codebase and model suite can be adaptively co-developed in situ through Rapid Agent Systems Engineering (RASE).

Central to RASE is intrinsic verifiability: the operational environment itself serves as the verification oracle, enabling autonomous capability development without external labeling dependencies.

Prerequisites

• Python 3.12+
• uv package manager
• PostgreSQL 16
• Qdrant vector database
• Optional: vLLM + optillm for local inference

Installation

git clone https://github.com/zndx/gaius.git
cd gaius

# Using devenv (recommended)
devenv shell

# Or with uv
uv sync --extra search --extra tda --extra inference

Configuration

Uses HOCON configuration with environment variable overrides.

# Required
export DATABASE_URL="postgres://localhost:5438/zndx_gaius?sslmode=disable"

# Optional inference
export OPTILLM_API_KEY="sk-optillm"
export GAIUS_OFFLINE="false"

See config/base.conf for full configuration options.

Security: gRPC Gateway Architecture

Gaius enforces a secure-by-default inference architecture. All inference requests route through the gRPC engine, which serves as the control plane for:

• Authentication and authorization
• Audit logging
• Resource management and rate limiting

All clients (TUI, CLI, MCP) connect to the engine via gRPC. The engine must be running for any client to function.

Usage

# Run database migrations
dbmate -d db/migrations up

# Start TUI
uv run gaius

# CLI mode
uv run gaius-cli --cmd "/state" --format json

Key Bindings

Global Navigation

Key	Action
hjkl	Navigate grid cursor
g	Cycle center panels (Graph → Think → Evolve → Observe)
v	Cycle view modes
o	Cycle overlays
[	Toggle left panel (FileTree)
]	Toggle right panel (Info)
\	Toggle both side panels
/	Enter command mode
?	Show help
q	Quit

FileTree (Left Panel)

Key	Action
↑ ↓	Navigate tree items
Enter	Open selected file
Space	Expand/collapse folder
G	Jump to last item (expands folders to find deepest leaf)
Ctrl-F	Page down (half page)
Ctrl-BB	Page up (half page) — requires double-press, known bug

Editor Panel (Normal Mode)

Vim-style modal editing for KB files.

Key	Action
i	Insert at cursor
I	Insert at line beginning
a	Append after cursor
A	Append at line end
o	Open line below
O	Open line above
ESC	Exit insert mode → normal mode
:q	Close editor
:wq	Save and close (auto-saves, so same as :q)
:<number>	Go to line number (e.g., :42)
:mv <path>	Move file to path
:rename [name]	Move to scratch with optional name

Editor Panel (Navigation)

Works in both normal and insert modes.

Key	Action
↑ ↓ ← →	Scroll viewport (browser-style)
Ctrl-F	Page down
Ctrl-B	Page up
G	Jump to end of document
hjkl	Pass through to main grid (normal mode only)

Commands

Command	Description
/search <query>	Search KB files and content
/research <topic>	Web search + LLM synthesis to KB
/explain [pos]	Explain grid position with differential geometry (saves to KB)
/domain <name>	Set domain focus
/swarm [domain]	Run multi-agent analysis
/summary	Generate daily summary
/activity	View activity log
/tda	Show topological features
/reindex	Refresh embeddings
/ambient status	Show ambient workload daemon status
/ambient start	Start ambient background processing
/ambient stop	Stop ambient background processing
/ambient buffer	Export buffered content to zettelkasten note
/gpu status	Show GPU endpoint status
/health	Run health diagnostics
/health fix <svc>	Auto-remediate unhealthy service

Layout

┌─────────┬──────────────┬───────┬─────────┬──────────┐
│ Agents  │              │ Embed │ Graph/  │   Info   │
│ ─────── │  19×19 Grid  │  9×9  │ Think   │          │
│ Files   │              ├───────┤         │          │
│         │              │  Iso  │         │          │
│         │              │  9×9  │         │          │
│         ├──────────────┴───────┴─────────┤          │
│         │         Content / Edit         │          │
├─────────┴────────────────────────────────┴──────────┤
│ / Command                                           │
└─────────────────────────────────────────────────────┘

Features

Grid Visualization

• KB entries projected onto 19×19 board via UMAP
• View modes: Go, Theta, Swarm
• Overlays: Risk, H1/H2 homology, Agents, Temporal

Orthographic Mini-Grids (9×9)

• Embed view: Cosine similarity spotlight around cursor document
• Iso view: Ricci curvature elevation map (boundaries vs interiors)
• Unicode block visualization (█▓▒░·) for spatial intuition

Differential Geometry

• Ricci curvature computation on semantic manifold
• Visual interpretation: bright Embed + low Iso = cluster core
• /explain generates LLM interpretations saved as KB notes
• Captures mini-grid snapshots in zettelkasten format

Multi-Agent Analysis

• 7 specialized agents (Leader, Risk, Optimizer, Planner, Critic, Executor, Adversary)
• Parallel execution with consensus synthesis

Knowledge Base

• Zettelkasten-style organization
• Wikilink support ([[links]])
• Markdown rendering

Topological Analysis

• Persistent homology computation
• H0 (components), H1 (loops), H2 (voids)
• Visual overlay on grid

Architecture

src/gaius/
├── app.py              # TUI application
├── cli.py              # Non-interactive CLI
├── mcp_server.py       # MCP server for Claude Code integration
├── core/
│   ├── config.py       # HOCON configuration
│   ├── state.py        # Application state
│   ├── projection.py   # UMAP grid projection
│   ├── tda.py          # Topological data analysis
│   ├── geometry.py     # Ricci curvature computation
│   ├── minigrids.py    # 9×9 orthographic views
│   └── kb_capture.py   # Zettelkasten note generation
├── agents/             # Swarm roles and orchestration
├── inference/          # LLM client, synthesis, embeddings
├── widgets/            # Grid, panels, command input
└── awareness/          # Situational reports

MCP Server

Gaius includes an MCP server for integration with Claude Code and other MCP clients.

# Run MCP server
uv run gaius-mcp

Key Tools:

• search_kb, read_kb, create_kb - Knowledge base operations
• explain_grid_position - Differential geometry explanation with KB capture
• run_swarm - Multi-agent analysis
• semantic_search - Vector similarity search
• research_topic - Web search + LLM synthesis

See src/gaius/mcp_server.py for full tool list.

Development

uv run gaius              # Run TUI
uv run pytest             # Run tests
mdbook build docs         # Build documentation

License

Apache License 2.0

Copyright 2025 Ryan Hill and Zndx Limited