🚀 Kurama

Your terminal-first AI coding assistant. Fully compatible with OmniRoute and OpenAI-style custom APIs.

 █▄▀ █ █ █▀▀█ █▀▀█ █▄ ▄█ █▀▀█
 █▀▄ █ █ █▄▄▀ █▄▄█ █ ▀ █ █▄▄█
 █ █ ▀▄▀ █ █ █ █ █ █ █

Kurama Logo

What is Kurama?

Kurama is a terminal-based coding assistant that integrates your local development environment directly with a custom LLM provider via the OpenAI API protocol. It is specifically designed to work out-of-the-box with OmniRoute as its primary AI backend.

Kurama connects to your workspace, reads context from files, interacts with Language Server Protocols (LSP), manages parallel agent swarms, and executes actions directly from the CLI.

Features

• OmniRoute Focused: Built to work with your own OmniRoute instance as the single endpoint.
• Dynamic Model Loading: Automatically discovers and lists models directly from your custom endpoint /v1/models.
• Dynamic MCP TUI Management: Supports on-the-fly configuration reloading and TUI management of Model Context Protocol (MCP) servers.
• Agent Swarms & Progress Tracking: Persistent display of execution goals (TODO list) in the sidebar, streaming progress, and parallel sub-agent status tracking.
• Advanced Clipboard Paste Integration: Copy images or large texts and paste them directly in the prompt using alt+v (or standard paste), automatically inserting reference tokens ([paste_N]).
• Session-Based Context: Maintain multiple work sessions and contexts per project.
• LSP Integration: Uses local LSPs (like gopls) to feed precise structural code context to the model.
• Cross-Platform: Works seamlessly on macOS, Linux, and Windows (PowerShell/WSL).

Installation & Setup

Quick Installation (Recommended)

You can quickly install the pre-compiled binary using the official installation scripts.

Unix Systems (Linux/macOS)

Run the following command in your terminal:

curl -fsSL https://codeberg.org/andeerc/kurama/raw/branch/main/install.sh | bash

Windows (PowerShell)

Run the following command in PowerShell:

iex (irm -useb https://codeberg.org/andeerc/kurama/raw/branch/main/install.ps1)

Build from Source

Prerequisites

• Go 1.26.4 or later installed.

Compilation

To compile the project and generate the executable:

# Clone the repository
git clone https://codeberg.org/andeerc/kurama.git
cd Kurama
# Build the executable
go build -o Kurama .

How It Works (Onboarding)

On your very first execution, Kurama will start an onboarding assistant directly in the terminal:

1. Configure Provider: It will ask you for:
   • Base URL: The URL of your OmniRoute instance (e.g. https://api.omniroute.io/v1).
   • API Key: Your OmniRoute authorization key.
2. Model Selection: Kurama will query your endpoint via GET /models and list the available models. You can choose one model for large/complex tasks and another for small/simple tasks.
3. Enjoy: Your terminal assistant is ready.

Note

All credentials and model settings are saved securely in your global configuration file: ~/.local/share/Kurama/kurama.json (on Linux/macOS) or %LOCALAPPDATA%\Kurama\kurama.json (on Windows).

Configuration Files

Kurama supports both global and project-level configuration files.

Global Configuration File Example

This file is generated during the onboarding flow at ~/.local/share/Kurama/kurama.json (on Linux/macOS) or %LOCALAPPDATA%\Kurama\kurama.json (on Windows):

{
 "providers": {
 "omniroute": {
 "id": "omniroute",
 "name": "OmniRoute",
 "base_url": "https://api.omniroute.io/v1",
 "type": "openai",
 "api_key": "YOUR_API_KEY",
 "models": [
 {
 "id": "model-large",
 "name": "Large Model"
 },
 {
 "id": "model-small",
 "name": "Small Model"
 }
 ]
 }
 }
}

Project Configuration File

You can place a kurama.json or .kurama.json configuration file at the root of your workspace to customize local settings (e.g., LSPs, excluded files, hooks, etc.).

Commands

Start the TUI

Runs the main terminal user interface:

Kurama

Run Non-Interactively

Ask Kurama to perform a task directly from the CLI without opening the full interface:

Kurama run "Check if there are any linting issues in this repository"

View and Follow Logs

Logs are kept in the local directory under .Kurama/logs/Kurama.log. You can view or follow logs:

# Follow logs in real-time
Kurama logs --follow
# Tail recent logs
Kurama logs --tail 200

Migrate from Nibble

If you were previously using Nibble, run this once to migrate all your sessions, configs and credentials:

# Preview what will be migrated (no changes made)
kurama migrate --dry-run
# Run the migration
kurama migrate

Check and Install Updates

Performs an in-place atomic upgrade directly from Codeberg:

kurama update

Contributing

Feel free to fork the repository on Codeberg and submit issues or pull requests.

License

This project is licensed under the FSL-1.1-MIT License. See LICENSE.md for details.