KIT (Knowledge Inference Tool)

A powerful, extensible AI coding agent CLI with multi-provider support, built-in tools, and a rich extension system.

Features

Multi-Provider LLM Support: Anthropic, OpenAI, Google Gemini, Ollama, Azure OpenAI, AWS Bedrock, OpenRouter, and more
Built-in Core Tools: bash, read, write, edit, grep, find, ls - no MCP overhead
MCP Integration: Connect external MCP servers for expanded capabilities
Extension System: Write custom tools, commands, widgets, and UI modifications in Go
Interactive TUI: Rich terminal interface powered by Bubble Tea with streaming, syntax highlighting, and custom rendering
Session Management: Tree-based conversation history with branching support
Non-Interactive Mode: Script-friendly positional args with JSON output
ACP Server: Run Kit as an Agent Client Protocol agent over stdio
Go SDK: Embed Kit in your own applications

Installation

Using npm (recommended)

npm install -g @mark3labs/kit

Using Go

go install github.com/mark3labs/kit/cmd/kit@latest

Building from source

git clone https://github.com/mark3labs/kit.git
cd kit
go build -o kit ./cmd/kit

Quick Start

Basic Usage

# Start interactive session
kit

# Run a one-off prompt
kit "List files in src/"

# Attach files as context
kit @main.go @test.go "Review these files"

# Continue the most recent session
kit --continue

# Use specific model
kit --model anthropic/claude-sonnet-4-5-20250929

Non-Interactive Mode

# Get JSON output for scripting
kit "Explain main.go" --json

# Quiet mode (final response only)
kit "Run tests" --quiet

# Ephemeral mode (no session file)
kit "Quick question" --no-session

ACP Server Mode

Kit can run as an ACP (Agent Client Protocol) agent server, enabling ACP-compatible clients (such as OpenCode) to drive Kit as a remote coding agent over stdio.

# Start Kit as an ACP server (communicates via JSON-RPC 2.0 on stdin/stdout)
kit acp

# With debug logging to stderr
kit acp --debug

The ACP server exposes Kit's full capabilities — LLM execution, tool calls (bash, read, write, edit, grep, etc.), and session persistence — over the standard ACP protocol. Sessions are persisted to Kit's normal JSONL session files, so they can be resumed later.

Configuration

Kit looks for configuration in the following locations (in order of priority):

CLI flags
Environment variables (with KIT_ prefix)
./.kit.yml (project-local)
~/.kit.yml (global)

Basic Configuration

Create ~/.kit.yml:

model: anthropic/claude-sonnet-4-5-20250929
max-tokens: 4096
temperature: 0.7
stream: true

Environment Variables

export ANTHROPIC_API_KEY="sk-..."
export OPENAI_API_KEY="sk-..."
export KIT_MODEL="openai/gpt-4o"

MCP Server Configuration

Add external MCP servers to .kit.yml:

mcpServers:
  filesystem:
    type: local
    command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
    environment:
      LOG_LEVEL: "info"
    allowedTools: ["read_file", "write_file"]
  
  search:
    type: remote
    url: "https://mcp.example.com/search"

CLI Reference

Global Flags

# Model and provider
--model, -m              Model to use (provider/model format)
--provider-api-key       API key for the provider
--provider-url           Base URL for provider API
--tls-skip-verify        Skip TLS certificate verification

# Session management
--session, -s            Open specific JSONL session file
--continue, -c           Resume most recent session for current directory
--resume, -r             Interactive session picker
--no-session             Ephemeral mode, no persistence

# Behavior (non-interactive: pass prompt as positional arg)
--quiet                  Suppress all output (non-interactive only)
--json                   Output response as JSON (non-interactive only)
--no-exit                Enter interactive mode after prompt completes
--max-steps              Maximum agent steps (0 for unlimited)
--stream                 Enable streaming output (default: true)
--compact                Enable compact output mode
--auto-compact           Auto-compact conversation near context limit

# Extensions
--extension, -e          Load additional extension file(s) (repeatable)
--no-extensions          Disable all extensions

# Generation parameters
--max-tokens             Maximum tokens in response (default: 4096)
--temperature            Randomness 0.0-1.0 (default: 0.7)
--top-p                  Nucleus sampling 0.0-1.0 (default: 0.95)
--top-k                  Limit top K tokens (default: 40)
--stop-sequences         Custom stop sequences (comma-separated)

# System
--config                 Config file path (default: ~/.kit.yml)
--system-prompt          System prompt text or file path
--debug                  Enable debug logging

Commands

# Authentication (for OAuth-enabled providers)
kit auth login           # Start OAuth flow
kit auth logout          # Remove credentials
kit auth status          # Check authentication status

# Model database
kit models               # List available models
kit models --all         # Show all providers (not just Fantasy-compatible)
kit update-models        # Update local model database from models.dev

# Extension management
kit extensions list      # List discovered extensions
kit extensions validate  # Validate extension files
kit extensions init      # Generate example extension template

# ACP server
kit acp                  # Start as ACP agent (stdio JSON-RPC)
kit acp --debug          # With debug logging to stderr

Extension System

Extensions are Go source files that run via Yaegi interpreter. They can add custom tools, slash commands, widgets, keyboard shortcuts, and intercept lifecycle events.

Minimal Extension

//go:build ignore

package main

import "kit/ext"

func Init(api ext.API) {
    api.OnSessionStart(func(_ ext.SessionStartEvent, ctx ext.Context) {
        ctx.SetFooter(ext.HeaderFooterConfig{
            Content: ext.WidgetContent{Text: "Custom Footer"},
        })
    })
}

Usage:

kit -e examples/extensions/minimal.go

Extension Capabilities

Lifecycle Events: OnSessionStart, OnSessionShutdown, OnAgentStart, OnAgentEnd, OnToolCall, OnToolResult, OnInput, OnMessageStart, OnMessageUpdate, OnMessageEnd, OnModelChange, OnContextPrepare, OnBeforeFork, OnBeforeSessionSwitch, OnBeforeCompact

Custom Components:

Tools: Add new tools the LLM can invoke
Commands: Register slash commands (e.g., /mycommand)
Widgets: Persistent status displays above/below input
Shortcuts: Global keyboard shortcuts
Overlays: Modal dialogs with markdown content
Tool Renderers: Customize how tool calls display
Editor Interceptors: Handle key events and wrap rendering

Extension Examples

See the examples/extensions/ directory:

minimal.go - Clean UI with custom footer
notify.go - Desktop notifications
widget-status.go - Persistent status widgets
custom-editor-demo.go - Vim-like modal editor
prompt-demo.go - Interactive prompts (select/confirm/input)
tool-logger.go - Log all tool calls
overlay-demo.go - Modal dialogs
plan-mode.go - Read-only planning mode
subagent-widget.go - Multi-agent orchestration
auto-commit.go - Auto-commit on shutdown

Loading Extensions

Auto-discovery (loads automatically):

./.kit/extensions/*.go (project-local)
~/.config/kit/extensions/*.go (global)

Explicit loading:

kit -e path/to/extension.go
kit -e ext1.go -e ext2.go  # Multiple extensions

Disable auto-load:

kit --no-extensions

Session Management

Kit uses a tree-based session model that supports branching and forking conversations.

Session Locations

Default: ~/.local/share/kit/sessions/<cwd-hash>/<uuid>.jsonl
Each line is a session entry (messages, tool calls, extension data)
Supports branching from any message to explore alternate paths

Session Commands

# Resume most recent session for current directory
kit --continue
kit -c

# Interactive session picker
kit --resume
kit -r

# Open specific session file
kit --session path/to/session.jsonl
kit -s path/to/session.jsonl

# Ephemeral mode (no file persistence)
kit --no-session

Go SDK

Embed Kit in your Go applications:

package main

import (
    "context"
    "log"
    
    kit "github.com/mark3labs/kit/pkg/kit"
)

func main() {
    ctx := context.Background()
    
    // Create Kit instance with default configuration
    host, err := kit.New(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer host.Close()
    
    // Send a prompt
    response, err := host.Prompt(ctx, "What is 2+2?")
    if err != nil {
        log.Fatal(err)
    }
    
    println(response)
}

With Options

host, err := kit.New(ctx, &kit.Options{
    Model:        "ollama/llama3",
    SystemPrompt: "You are a helpful bot",
    ConfigFile:   "/path/to/config.yml",
    MaxSteps:     10,
    Streaming:    true,
    Quiet:        true,
})

With Callbacks

response, err := host.PromptWithCallbacks(
    ctx,
    "List files in current directory",
    func(name, args string) {
        // Tool call started
        println("Calling tool:", name)
    },
    func(name, args, result string, isError bool) {
        // Tool call completed
        if isError {
            println("Tool failed:", name)
        }
    },
    func(chunk string) {
        // Streaming text chunk
        print(chunk)
    },
)

Session Management

host.Prompt(ctx, "My name is Alice")
response, _ := host.Prompt(ctx, "What's my name?")

host.SaveSession("./session.json")
host.LoadSession("./session.json")
host.ClearSession()

Advanced Usage

Subagent Pattern

Spawn Kit as a subprocess for multi-agent orchestration:

kit "Analyze codebase" \
    --json \
    --no-session \
    --no-extensions \
    --quiet \
    --model anthropic/claude-haiku-3-5-20241022

Parse the JSON output:

{
  "response": "Final assistant response text",
  "model": "anthropic/claude-haiku-3-5-20241022",
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 512,
    "total_tokens": 1536
  },
  "messages": [...]
}

Testing with tmux

Test the TUI non-interactively:

# Start Kit in detached tmux session
tmux new-session -d -s kittest -x 120 -y 40 \
  "kit -e ext.go --no-session 2>kit.log"

# Wait for startup
sleep 3

# Capture screen
tmux capture-pane -t kittest -p

# Send input
tmux send-keys -t kittest '/command' Enter

# Cleanup
tmux kill-session -t kittest

Development

Build and Test

# Build
go build -o output/kit ./cmd/kit

# Run tests
go test -race ./...

# Run specific test
go test -race ./cmd -run TestScriptExecution

# Lint
go vet ./...

# Format
go fmt ./...

Project Structure

cmd/kit/           - CLI entry point
cmd/               - CLI command implementations
pkg/kit/           - Go SDK
internal/agent/    - Agent loop and tool execution
internal/ui/       - Bubble Tea TUI components
internal/extensions/ - Yaegi extension system
internal/core/     - Built-in tools
internal/tools/    - MCP tool integration
internal/config/   - Configuration management
internal/acpserver/ - ACP (Agent Client Protocol) server
internal/session/  - Session persistence
internal/models/   - Provider and model management
examples/extensions/ - Example extension files

Supported Providers

Anthropic - Claude models (native, prompt caching, OAuth)
OpenAI - GPT models
Google - Gemini models
Ollama - Local models
Azure OpenAI - Azure-hosted OpenAI
AWS Bedrock - Bedrock models
Google Vertex - Claude on Vertex AI
OpenRouter - Multi-provider router
Vercel AI - Vercel AI SDK models
Auto-routed - Any provider from models.dev database

Model String Format

provider/model            # Standard format
anthropic/claude-sonnet-4-5-20250929
openai/gpt-4o
ollama/llama3
google/gemini-2.0-flash-exp

Model Aliases

claude-opus-latest      → claude-opus-4-20250514
claude-sonnet-latest    → claude-sonnet-4-5-20250929
claude-3-5-haiku-latest → claude-3-5-haiku-20241022

Name		Name	Last commit message	Last commit date
Latest commit History 337 Commits
.agents/skills/btca-cli		.agents/skills/btca-cli
.github/workflows		.github/workflows
.iteratr/data		.iteratr/data
.opencode		.opencode
cmd		cmd
contribute		contribute
examples/extensions		examples/extensions
internal		internal
npm		npm
pkg/kit		pkg/kit
skills/kit-extensions		skills/kit-extensions
specs		specs
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
Taskfile.yml		Taskfile.yml
btca.config.jsonc		btca.config.jsonc
go.mod		go.mod
go.sum		go.sum
logo.jpg		logo.jpg
skills-lock.json		skills-lock.json

Folders and files

Latest commit

History

Repository files navigation

KIT (Knowledge Inference Tool)

Features

Installation

Using npm (recommended)

Using Go

Building from source

Quick Start

Basic Usage

Non-Interactive Mode

ACP Server Mode

Configuration

Basic Configuration

Environment Variables

MCP Server Configuration

CLI Reference

Global Flags

Commands

Extension System

Minimal Extension

Extension Capabilities

Extension Examples

Loading Extensions

Session Management

Session Locations

Session Commands

Go SDK

With Options

With Callbacks

Session Management

Advanced Usage

Subagent Pattern

Testing with tmux

Development

Build and Test

Project Structure

Supported Providers

Model String Format

Model Aliases

Contributing

License

Community

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages