Koopa is a local-first AI workspace platform built with Go.

It unifies terminal efficiency with rich web interactions through a hybrid architecture: a keyboard-centric TUI for speed, and a server-driven Web UI for visualization. Powered by Firebase Genkit and PostgreSQL, Koopa enables local knowledge management, autonomous agents, and tool integration via the Model Context Protocol (MCP).

• Local Sovereignty: User data, sessions, and vector embeddings reside in a local PostgreSQL database.
• Hybrid Interface: Seamless context switching between CLI efficiency and Web UI richness.
• Hypermedia-Driven: Utilizes a modern Go stack (Templ + HTMX) to deliver high performance with low complexity.

• Generative Web UI: A server-driven interface supporting streaming responses and rich component rendering without SPA complexity.
• Terminal UI: A low-latency Bubble Tea application for rapid interaction.
• Local RAG: Automatic document indexing using pgvector for context-aware conversations.
• MCP Integration: Implements the Model Context Protocol to serve as a backend for compatible clients like Claude Desktop.
• Session Persistence: Robust conversation history management across all interfaces.

• Language: Go 1.25+
• AI Framework: Google Firebase Genkit
• Database: PostgreSQL + pgvector
• Web: Templ, HTMX, Tailwind CSS
• TUI: Bubble Tea

• Go 1.25 or higher
• Docker (for PostgreSQL)
• Node.js 20+ (asset compilation only)
• Gemini API Key

1. Clone and setup

   git clone https://github.com/koopa0/koopa-cli.git
   cd koopa-cli
   go install github.com/go-task/task/v3/cmd/task@latest
   task install

2. Start infrastructure

   docker-compose up -d

3. Build

   task build

4. Configure Create ~/.koopa/config.yaml:

   postgres_host: "localhost"
   postgres_port: 5432
   postgres_user: "koopa"
   postgres_db_name: "koopa"
   postgres_ssl_mode: "disable"

5. Run

   export GEMINI_API_KEY="your-key"
   ./koopa

Koopa operates in three modes.

Terminal Mode The default interactive interface.

./koopa

Web Server Mode Starts the HTTP server for the web interface.

export HMAC_SECRET=$(openssl rand -base64 32)
./koopa serve

Access the UI at http://localhost:8080/genui.

MCP Server Mode Exposes tools and knowledge base to external MCP clients.

./koopa mcp

Koopa uses a config-first approach. Non-sensitive settings reside in config.yaml, while secrets must be passed via environment variables.

Environment Variables

• GEMINI_API_KEY: Required. Google AI API key.
• HMAC_SECRET: Required for serve mode. Min 32 chars.
• POSTGRES_PASSWORD: Required if not using default credentials.

Configuration File Default settings in ~/.koopa/config.yaml:

model_name: "gemini-2.5-flash"
temperature: 0.7
max_tokens: 4096
rag_top_k: 5
embedder_model: "text-embedding-004"

Use Taskfile for standard workflows.

task generate css   # Build assets
task test           # Run unit tests
task test:race      # Run tests with race detector
task dev            # Start dev server with hot-reload

1. Fork the repository.
2. Create a feature branch.
3. Ensure task test:race passes.
4. Submit a Pull Request.

Distributed under the MIT License. See LICENSE for more information.