kit-extensions

Kit Extensions Development Guide

Kit extensions are single-file Go programs interpreted at runtime by Yaegi. They hook into Kit's lifecycle, register custom tools and slash commands, display widgets, intercept editor input, render tool output, register and switch color themes, and more.

Extensions can be distributed via git repositories using kit install. Repos can contain single extensions or collections of multiple extensions.

This file is the entry point. It gives the structure, a minimal example, and the constraints you must never miss. Detailed material lives in the references/ directory (see Reference files below). Read only the reference files that apply to your task.

Extension Structure

Every extension must export a package main with an Init(api ext.API) function:

//go:build ignore

package main

import "kit/ext"

func Init(api ext.API) {
    // Register event handlers, tools, commands, etc.
}

The //go:build ignore tag prevents go build from compiling the file directly.

Extension Locations

Extensions are auto-loaded from these directories:

• /usr/share/kit/extensions/*.go (system-wide, single files)
• /usr/share/kit/extensions/*/main.go (system-wide, subdirectories)
• ~/.config/kit/extensions/*.go (user, single files)
• ~/.config/kit/extensions/*/main.go (user, subdirectories)
• .kit/extensions/*.go (project-local, single files)
• .kit/extensions/*/main.go (project-local, subdirectories)

Or loaded explicitly:

kit -e path/to/extension.go
kit --extension path/to/extension.go

Import Path

Extensions import the Kit API as "kit/ext". The full standard library is available plus os/exec for subprocess spawning.

API Overview

The Init function receives an ext.API object for registering handlers, and event handlers receive an ext.Context with runtime capabilities.

• api.On* — subscribe to one of 31 lifecycle events (OnSessionStart, OnToolCall, OnAgentEnd, ...). See references/lifecycle-events.md.
• api.RegisterTool / RegisterCommand / RegisterShortcut / RegisterOption — add LLM tools, /slash commands, key bindings, and config options. See references/tools-commands-shortcuts.md.
• ctx.* — runtime capabilities: print output, inject messages, widgets, header/footer, prompts, overlays, editor interceptor, session data/state, model and tool management, LLM completions, themes. See references/context-api.md.
• api.RegisterToolRenderer / api.RegisterMessageRenderer — custom rendering of tool calls and messages. See references/renderers.md.