koopa

command module

v0.0.0-...-d8a54d3 Latest Latest Go to latest Published: Feb 21, 2026 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

A terminal AI assistant with local knowledge management. Supports Gemini, Ollama, and OpenAI.

Features

Multi-provider — Switch between Gemini, Ollama (local), and OpenAI with an environment variable
Interactive TUI — Chat in your terminal with streaming responses
HTTP API — JSON REST API with SSE streaming for building frontends
MCP Server — Use Koopa's tools from Claude Desktop or Cursor
RAG — Semantic search over your conversations and documents (pgvector)
User Memory — Automatically learns user preferences, identity, and project context across sessions (pgvector + LLM extraction, two-threshold dedup, time-decay)
Built-in tools — File I/O, shell commands, web search, web scraping
MCP client — Plug in external MCP servers for additional tools
Sessions — Persistent conversation history in PostgreSQL

Quick Start

# 1. Start PostgreSQL with pgvector
docker compose up -d postgres

# 2. Configure
cp .env.example .env
# Edit .env — set GEMINI_API_KEY and DATABASE_URL
source .env

# 3. Build and run
go build -o koopa .
./koopa cli

Usage

koopa cli          Interactive chat
koopa serve [addr] HTTP API server (default: 127.0.0.1:3400)
koopa mcp          MCP server for IDE integration
koopa --version    Version info

CLI Commands

Command	Description
`/help`	Show available commands
`/clear`	Clear conversation history
`/exit`	Exit Koopa
`Ctrl+D`	Exit

HTTP API

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

See API Integration Guide for endpoint details, SSE streaming protocol, and frontend integration examples.

MCP Server

Add to Claude Desktop or Cursor config:

{
  "mcpServers": {
    "koopa": {
      "command": "/path/to/koopa",
      "args": ["mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "DATABASE_URL": "postgres://koopa:password@localhost:5432/koopa?sslmode=disable"
      }
    }
  }
}

Tools: read_file, write_file, list_directory, execute_command, get_env, web_search, web_fetch, search_history, search_documents, search_system_knowledge.

Providers

Gemini (default)

export GEMINI_API_KEY=your-key
./koopa cli

Ollama

ollama pull llama3.3
export KOOPA_PROVIDER=ollama
export KOOPA_MODEL_NAME=llama3.3
./koopa cli

OpenAI

export OPENAI_API_KEY=your-key
export KOOPA_PROVIDER=openai
export KOOPA_MODEL_NAME=gpt-4o
./koopa cli

Configuration

Priority: Environment variables > ~/.koopa/config.yaml > defaults.

Variable	Required	Default	Description
`GEMINI_API_KEY`	Gemini	-	Google AI API key
`OPENAI_API_KEY`	OpenAI	-	OpenAI API key
`DATABASE_URL`	Yes	-	PostgreSQL connection URL
`HMAC_SECRET`	Serve	-	CSRF secret (min 32 chars)
`KOOPA_PROVIDER`	No	`gemini`	AI provider: gemini, ollama, openai
`KOOPA_MODEL_NAME`	No	`gemini-2.5-flash`	Model identifier
`KOOPA_OLLAMA_HOST`	No	`http://localhost:11434`	Ollama server address
`DEBUG`	No	-	Enable debug logging

For MCP server connections and web search configuration, see config.example.yaml.

Docker Compose

docker compose up -d postgres           # PostgreSQL only
docker compose up -d                     # + SearXNG web search

Service	Port	Description
PostgreSQL	5432	Database with pgvector
SearXNG	8888	Privacy-respecting web search

Prerequisites

Go 1.25+
Docker (for PostgreSQL)

License

MIT

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
api Package api provides the JSON REST API server for Koopa.	Package api provides the JSON REST API server for Koopa.
app Package app provides application initialization and lifecycle management.	Package app provides application initialization and lifecycle management.
chat Package chat implements Koopa's main conversational agent.	Package chat implements Koopa's main conversational agent.
config Package config provides application configuration management with multi-source priority.	Package config provides application configuration management with multi-source priority.
mcp Package mcp implements a Model Context Protocol (MCP) server.	Package mcp implements a Model Context Protocol (MCP) server.
memory Package memory provides persistent user memory backed by pgvector.	Package memory provides persistent user memory backed by pgvector.
rag Package rag implements Retrieval-Augmented Generation (RAG) for Koopa.	Package rag implements Retrieval-Augmented Generation (RAG) for Koopa.
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 with PostgreSQL.	Package session provides conversation history persistence with PostgreSQL.
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.