koopa

command module

v0.0.0-...-26e635b Latest Latest Go to latest Published: Dec 22, 2025 License: MIT Imports: 3 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/koopa0/koopa

Links

Open Source Insights

README ¶

Koopa

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).

Core Philosophy

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.

Features

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.

Technology Stack

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

Quick Start

Prerequisites

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

Installation

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

Start infrastructure
```
docker-compose up -d
```
Build
```
task build
```

Configure Create ~/.koopa/config.yaml:

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

Run

export GEMINI_API_KEY="your-key"
./koopa

Usage

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

Configuration

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"

Development

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

Contributing

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

License

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

Documentation ¶

Overview ¶

Package main is the entry point for the Koopa CLI application.

Source Files ¶

View all Source files

main.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd Package cmd provides CLI commands for Koopa.	Package cmd provides CLI commands for Koopa.
db Package db provides database utilities including migration support.	Package db provides database utilities including migration support.
internal
agent Package agent provides sentinel errors for the chat agent.	Package agent provides sentinel errors for the chat agent.
agent/chat Package chat implements Koopa's main conversational agent.	Package chat implements Koopa's main conversational agent.
app Package app provides application initialization and dependency injection.	Package app provides application initialization and dependency injection.
config Package config provides application configuration management with multi-source priority.	Package config provides application configuration management with multi-source priority.
log Package log provides a unified logging infrastructure for the koopa application.	Package log provides a unified logging infrastructure for the koopa application.
mcp Package mcp implements a Model Context Protocol (MCP) server.	Package mcp implements a Model Context Protocol (MCP) server.
observability Package observability provides OpenTelemetry integration for distributed tracing.	Package observability provides OpenTelemetry integration for distributed tracing.
rag Package rag constants.go defines shared constants, types, and configuration for RAG operations.	Package rag constants.go defines shared constants, types, and configuration for RAG operations.
security Package security provides security validators for protecting against common vulnerabilities.	Package security provides security validators for protecting against common vulnerabilities.
session Package session provides conversation history persistence.	Package session provides conversation history persistence.
sqlc
testutil Package testutil provides shared testing utilities for the koopa project.	Package testutil provides shared testing utilities for the koopa project.
tools Package tools provides AI agent tools for file, system, network, and knowledge operations.	Package tools provides AI agent tools for file, system, network, and knowledge operations.
tui Package tui provides Bubble Tea terminal interface for Koopa.	Package tui provides Bubble Tea terminal interface for Koopa.
web Package web provides the GenUI web server and HTTP handlers.	Package web provides the GenUI web server and HTTP handlers.
web/component templ: version: v0.3.960	templ: version: v0.3.960
web/handlers Package handlers provides HTTP handlers for the GenUI web interface.	Package handlers provides HTTP handlers for the GenUI web interface.
web/layout templ: version: v0.3.960	templ: version: v0.3.960
web/page templ: version: v0.3.960	templ: version: v0.3.960
web/sse Package sse provides Server-Sent Events utilities for streaming responses.	Package sse provides Server-Sent Events utilities for streaming responses.
web/static Package static provides embedded static assets for production builds.	Package static provides embedded static assets for production builds.