Kota

A lightweight, highly extensible ai code agent, built in Rust:

Why Kota?

Kota is designed with the philosophy of vim - lightweight, highly extensible, and simple to configure. Just as vim became the go-to editor for developers who value efficiency and customization, Kota aims to be the AI code agent that gets out of your way while giving you full control.

Core Principles:

• Lightweight - Minimal dependencies, fast startup, low resource usage. Built in Rust for performance and reliability.
• Highly Extensible - Skills system, custom tools, hooks, and plugin architecture. Extend Kota to fit your workflow, not the other way around.
• Simple Configuration - Plain text config files, straightforward API. No complex setup, no bloated frameworks.
• Practical - Focus on real development tasks: code review, refactoring, debugging, documentation. Tools that actually help you code.

Whether you use it as a CLI tool or integrate it as a library into your own projects, Kota gives you the power to build AI-assisted workflows that match your needs - without the overhead.

Comparison with Other Code Agents

Feature	Kota	Cursor	GitHub Copilot	Claude Code	Codex
Language	Rust	Electron/TS	TypeScript	Proprietary	Rust
Extensibility	✅ Lua config + Custom tools	Limited	Plugin API	❌ No	API only
Library Usage	✅ Rust crate	❌ No	❌ No	❌ No	❌ No
Skills System	✅ Built-in	❌ No	❌ No	✅ Built-in	❌ No
Custom Commands	✅ Lua functions	❌ No	❌ No	❌ No	❌ No
Multi-Model	✅ Multiple	✅ Multiple	❌ OpenAI only	❌ Claude only	❌ OpenAI only
Configuration	Simple Lua files	GUI settings	GUI settings	Web UI	API config
Learning Curve	Low (vim-like)	Medium	Low	Low	High

Setup

Configuration

Kota uses Lua-based configuration (inspired by Neovim). Create a .kota/config.lua file in your project root:

kota.setup({
  model = "deepseek-chat",
  api_key = os.getenv("API_KEY"),
  api_base = "https://api.deepseek.com/v1",
  temperature = 0.7,
  
  -- Custom commands with parameter support
  commands = {
    -- Simple string commands
    ["fix"] = "analyze and fix the current file",
    
    -- Function commands with parameters
    ["test"] = function(args)
      local file = args.file or "current file"
      return "run tests for " .. file
    end,
    
    ["review"] = function(args)
      local file = args.file or "current file"
      local aspect = args.aspect or "general quality"
      return string.format("review %s focusing on %s", file, aspect)
    end,
  },
})

Set your API key as an environment variable:

# Linux/Mac
export API_KEY="your-api-key-here"

# Windows PowerShell
$env:API_KEY="your-api-key-here"

See Lua Configuration Guide for more details.

.kota Directory Structure

Kota uses a .kota directory in your project root for all configuration and extensions:

.kota/
├── config.lua         # Main configuration file
├── mcps/              # Model Context Protocol servers (future)
├── prompts/           # Custom prompt templates
├── skills/            # Custom skills definitions
│   ├── code-review/
│   │   └── SKILL.md
│   ├── debug/
│   │   └── SKILL.md
│   ├── refactor/
│   │   └── SKILL.md
│   └── rust-expert/
│       └── SKILL.md
├── tools/             # Custom tool implementations
├── ui/                # Custom UI components (future)
└── workflows/         # Workflow definitions (future)

Directory Purposes:

• config.lua - Main Lua configuration file for model settings, commands, tools, and hooks
• skills/ - Custom skill definitions with SKILL.md files describing specialized behaviors
• tools/ - Custom tool implementations to extend Kota's capabilities
• prompts/ - Reusable prompt templates for common tasks
• mcps/ - MCP server configurations (planned feature)
• workflows/ - Automated workflow definitions (planned feature)
• ui/ - Custom UI components and themes (planned feature)

Installation

As a CLI Tool

cargo install kota

Then start it:

kota

As a Library

Add Kota to your Cargo.toml:

[dependencies]
kota = "0.1.3"
tokio = { version = "1.0", features = ["full"] }
anyhow = "1.0"

Usage as a Library

Kota can be used as a library to build your own AI code agents. Here's a quick example:

use kota::kota_code::{AgentBuilder, ContextManager};
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // Create context manager for conversation history
    let context = ContextManager::new(".chat_sessions", "my-session".to_string())?;

    // Create a code agent instance with context
    let mut agent = AgentBuilder::new(
        "your-api-key".to_string(),
        "gpt-4".to_string()
    )?
    .with_context(context)
    .build()?;

    // Simple chat with automatic context management
    let response = agent.chat("Hello! Can you help me with Rust?").await?;
    println!("Tokens used: {}", response.usage().total_tokens);

    // Continue conversation (context is automatically maintained)
    let response = agent.chat("Can you give me an example?").await?;
    println!("Tokens used: {}", response.usage().total_tokens);

    Ok(())
}

Library Features

• Agent Builder: Create customized AI code agents with different LLM providers
• Agent Instance: Unified structure containing agent, context manager, and skill manager
• Context Management: Persistent conversation history with session support
• Plan Management: Structured task execution with dependencies
• Skills System: Specialized agent behaviors for different tasks
• Tool Registry: Extensible tool system for custom functionality
• Custom Commands: Define parameterized commands in Lua configuration
• Built-in Tools: File operations, code scanning, grep search, and more

Supported Models

Kota supports various LLM providers:

• OpenAI Compatible - (e.g., gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo...)
• DeepSeek - (e.g., deepseek-chat, deepseek-coder...)
• Anthropic Claude (e.g., claude-3-5-sonnet, claude-4-opus...)

Other Providers

• Any OpenAI-compatible API endpoint can be configured
• Local models via Ollama or similar services

CLI Features

Kota provides a powerful command-line interface with built-in commands, custom command support, and intelligent tab completion.

Interactive Commands

Kota provides an interactive CLI with the following commands:

• /quit or /exit - Exit the application
• /config - Show current model configuration
• /help - Show available commands
• /history - Show conversation history
• /skills - List all available skills
• /skill <name> - Activate a specific skill
• /skill-off - Deactivate current skill
• /load <session_id> - Load specific session
• /sessions - List all sessions
• /delete <session_id> - Delete a specific session

Custom Commands

Kota supports custom commands defined in your Lua configuration with parameter support:

# Simple commands
/fix

# Named parameters
/test file=main.rs
/review file=src/lib.rs aspect=security

# Positional parameters
/refactor main.rs "use builder pattern"

# Mixed parameters
/review main.rs aspect=performance

Custom commands are defined in your .kota/config.lua:

commands = {
  -- Simple string commands
  ["fix"] = "analyze and fix the current file",
  
  -- Function commands with parameters
  ["test"] = function(args)
    local file = args.file or "current file"
    return "run tests for " .. file
  end,
  
  ["review"] = function(args)
    local file = args.file or "current file"
    local aspect = args.aspect or "general quality"
    return string.format("review %s focusing on %s", file, aspect)
  end,
}

Tab Completion

Kota supports intelligent tab completion for commands:

• Type partial commands (e.g., /h) and press Tab to auto-complete
• Commands are highlighted in green when recognized
• Use Ctrl+C to exit or Ctrl+D for EOF

Example usage:

❯ /h<Tab>        # Completes to /help
❯ /hi<Tab>       # Completes to /history

Current architecture of Kota

Available Tools

Kota comes with a comprehensive set of file system and development tools:

Category	Tool	Description
File Operations	read_file	Read the contents of a file from the filesystem
	write_file	Write content to a file, creating it if it doesn't exist or overwriting completely
	edit_file	Apply unified diff patches to files for targeted changes
	delete_file	Delete a file from the filesystem
Directory Operations	make_dir	Create directories and all necessary parent directories
	scan_codebase	Scan and display the structure of a codebase directory tree
Search Operations	grep_find	Search for text patterns in files using regular expressions with recursive directory traversal
System Operations	exec_cmd	Execute bash/cmd commands and return output (use with caution)
Plan Mode	update_plan	Manage structured execution plans with tasks, dependencies, and status tracking (similar to Claude Code)

Each tool provides detailed feedback during execution and handles common error cases like permission issues and missing files.

Skills System

Kota now includes a powerful Skills system similar to Claude's skills, allowing you to specialize the AI assistant for specific tasks.

Built-in Skills

Skill	Description	Available Tools
code_review	Code quality analysis and review	read_file, scan_codebase, grep_search
refactor	Code refactoring and optimization	read_file, edit_file, write_file
debug	Problem diagnosis and debugging	read_file, execute_bash, grep_search
documentation	Documentation writing and improvement	read_file, write_file, scan_codebase

Using Skills

# List all available skills
❯ /skills

# Activate a skill
❯ /skill code_review

# Use the skill
❯ Please review src/main.rs for code quality issues

# Deactivate skill
❯ /skill-off

Roadmap & TODO

Upcoming Features

1. MCP (Model Context Protocol) Support

   • Integration with MCP servers for extended functionality
   • Support for custom MCP tools and resources
   • Enhanced context management through MCP

2. Claude Skills Integration

   • Implement Claude-like skills system for specialized capabilities
   • Modular skill architecture for extensibility
   • Built-in skills for common development tasks

Future Enhancements

• Plugin system for custom tools
• Enhanced session management
• Multi-project workspace support
• Integration with popular IDEs and editors

API Documentation

Full API documentation is available at docs.rs/kota.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.