kodelet

module
v0.6.11-beta Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 12, 2026 License: MIT

README

Kodelet

Your tools. Your models. Your agent.

Kodelet is an open-source coding agent built for software engineering and the work around it. Use it to understand a codebase, implement and verify changes, investigate failures, and automate repeatable work. Extend it with specialist tools and expertise to take it beyond coding.

Start a task in your terminal, follow it in your browser, or work through an ACP-compatible editor. You choose the model, the machine doing the work, and the capabilities available to the agent.

Why Kodelet?

  • Close the terminal. Keep the work going. A background daemon owns execution and saves your conversations. Leave terminal chat without stopping the task, follow the same conversation in the Web UI, and return without starting over.
  • Your terminal. Another machine. Use the built-in runner for local work, or connect a runner on another machine to work with its files, dependencies, and environment. Your client does not need to be where the work happens.
  • Bring the tools you rely on. Skills, recipes, and executable extensions add expertise, repeatable workflows, and new tools. Plugins package them for reuse, including capabilities beyond coding, such as image generation and integrations with external services.
  • Pick the model for the job. Use Anthropic Claude, OpenAI, or an OpenAI-compatible endpoint with your own credentials. Choose a configured model profile and reasoning effort before starting a conversation.

Get started

Kodelet supports macOS and Linux on amd64 and arm64.

Install

With Homebrew:

brew tap jingkaihe/kodelet
brew install kodelet

Or use the install script:

curl -sSL https://raw.githubusercontent.com/jingkaihe/kodelet/main/install.sh | bash

# Force standalone binary install
curl -sSL https://raw.githubusercontent.com/jingkaihe/kodelet/main/install.sh | bash -s -- --binary

The install script defaults to package-based installation: Homebrew on macOS and .deb/.rpm packages on Linux.

Connect a model

For a fresh installation using the default OpenAI provider, set your API key before starting Kodelet:

export OPENAI_API_KEY="your-api-key"

See the provider guide and sample configuration for other providers, authentication options, and model profiles. Model configuration and provider credentials belong to the daemon; if it is already running, finish active work and run kodelet server restart from the shell with the updated environment.

Start in your terminal

From the directory you want to work in:

kodelet chat

Try a small, verifiable task:

Explain this project's structure and how to run its tests. Do not edit files.

Then ask for a change, investigate a problem, or work through a plan together. Kodelet can edit files and execute commands, so start in a workspace you trust and review its changes and verification results.

Pick up in your browser

kodelet server url --open

This starts the local daemon if needed and opens the Web UI. Terminal chat and the browser share that daemon and its saved conversations. Exiting terminal chat leaves work running; use /stop when you want to cancel it.

Put it to work

Use kodelet run for one-off tasks or as part of a shell pipeline:

# Run a task directly
kodelet run "Fix the failing tests and verify the changes."

# Pipe in context from another command
git diff main | kodelet run "Review these changes for correctness and missing tests."

Add --result-only to output just the final response for use in scripts.

Make it yours

Start with project instructions, then add capabilities as you need them:

Capability Use it for
AGENTS.md Project context, conventions, and build or test instructions loaded automatically.
Recipes Reusable prompts with arguments and shell substitutions for tasks you repeat.
Skills Domain guidance the agent loads when relevant to the task.
Extensions Executable tools, commands, and lifecycle behavior that connect the agent to your workflows.
Plugins Bundles of skills, recipes, and extensions you can install and share.

For example, with an image-generation extension installed, a request in terminal chat can produce an image you open in the Web UI.

With remote runners, install workspace skills, recipes, and extensions on the runner host, the machine that actually uses them.

Documentation

Development

Kodelet uses mise for tool versions and development tasks:

mise install
mise run install
mise run lint
mise run test

Run mise tasks to list the remaining build, frontend, SDK, packaging, and container tasks.

License

Kodelet is licensed under the MIT License.

Directories

Path Synopsis
cmd
kodelet command
Package main provides the entry point for the Kodelet CLI application.
 Package main provides the entry point for the Kodelet CLI application.
pkg
acp
Package acp implements the Agent Client Protocol (ACP) server for kodelet.
 Package acp implements the Agent Client Protocol (ACP) server for kodelet.
acp/acptypes
Package acptypes defines types for the Agent Client Protocol (ACP).
 Package acptypes defines types for the Agent Client Protocol (ACP).
acp/bridge
Package bridge provides the bridge between kodelet's message handler system and the ACP session update protocol.
 Package bridge provides the bridge between kodelet's message handler system and the ACP session update protocol.
acp/session
Package session manages ACP session lifecycle, wrapping kodelet threads with ACP session semantics.
 Package session manages ACP session lifecycle, wrapping kodelet threads with ACP session semantics.
agentenv
Package agentenv defines the environment boundary used by Kodelet's central agent loop.
 Package agentenv defines the environment boundary used by Kodelet's central agent loop.
artifacts
Package artifacts persists immutable image files and their conversation references.
 Package artifacts persists immutable image files and their conversation references.
auth
Package auth provides authentication mechanisms for various AI providers.
 Package auth provides authentication mechanisms for various AI providers.
binaries
Package binaries provides functionality for managing external binary dependencies that kodelet requires, such as ripgrep and fd.
 Package binaries provides functionality for managing external binary dependencies that kodelet requires, such as ripgrep and fd.
chat
Package chat implements shared persisted chat orchestration for Kodelet UIs.
 Package chat implements shared persisted chat orchestration for Kodelet UIs.
controlplane
Package controlplane provides Kodelet's central HTTP API and server runtime.
 Package controlplane provides Kodelet's central HTTP API and server runtime.
controlplane/userauth
Package userauth implements Kodelet-issued credentials for non-browser users.
 Package userauth implements Kodelet-issued credentials for non-browser users.
conversations
Package conversations provides conversation management functionality for kodelet.
 Package conversations provides conversation management functionality for kodelet.
conversations/sqlite
Package sqlite provides SQLite-specific implementation for conversation storage.
 Package sqlite provides SQLite-specific implementation for conversation storage.
db
Package db provides shared SQLite database utilities.
 Package db provides shared SQLite database utilities.
db/migrations
Package migrations contains all database migrations for kodelet.
 Package migrations contains all database migrations for kodelet.
diffview
Package diffview renders structured unified diffs consistently across Kodelet surfaces.
 Package diffview renders structured unified diffs consistently across Kodelet surfaces.
extensions
Package extensions implements Kodelet's long-running extension runtime.
 Package extensions implements Kodelet's long-running extension runtime.
fragments
Package fragments provides a template system for reusable prompt fragments and recipes.
 Package fragments provides a template system for reusable prompt fragments and recipes.
goals
Package goals contains persisted thread-goal state and prompt rendering.
 Package goals contains persisted thread-goal state and prompt rendering.
llm
Package llm provides a unified interface for Large Language Model providers.
 Package llm provides a unified interface for Large Language Model providers.
llm/anthropic
Package anthropic provides a client implementation for interacting with Anthropic's Claude AI models.
 Package anthropic provides a client implementation for interacting with Anthropic's Claude AI models.
llm/base
Package base provides shared functionality for LLM thread implementations.
 Package base provides shared functionality for LLM thread implementations.
llm/openai
Package openai provides OpenAI API client implementations.
 Package openai provides OpenAI API client implementations.
llm/openai/copilotdefaults
Package copilotdefaults builds OpenAI-compatible model defaults from the Copilot model catalog.
 Package copilotdefaults builds OpenAI-compatible model defaults from the Copilot model catalog.
llm/openai/preset/codex
Package codex provides preset configurations for Codex CLI models.
 Package codex provides preset configurations for Codex CLI models.
llm/openai/preset/openai
Package openai provides preset configurations for OpenAI models
 Package openai provides preset configurations for OpenAI models
llm/openai/responses
Package responses implements storage types for the OpenAI Responses API.
 Package responses implements storage types for the OpenAI Responses API.
llm/prompts
Package prompts provides common prompt templates for LLM interactions including context compacting prompts and other reusable prompt text used throughout kodelet's LLM communication.
 Package prompts provides common prompt templates for LLM interactions including context compacting prompts and other reusable prompt text used throughout kodelet's LLM communication.
logger
Package logger provides context-aware structured logging functionality using logrus.
 Package logger provides context-aware structured logging functionality using logrus.
messagehistory
Package messagehistory persists raw user-submitted chat messages for local composer recall.
 Package messagehistory persists raw user-submitted chat messages for local composer recall.
osutil
Package osutil provides common utility functions for kodelet including content formatting with line numbers, process management, language detection, domain filtering, and various helper functions used across the application.
 Package osutil provides common utility functions for kodelet including content formatting with line numbers, process management, language detection, domain filtering, and various helper functions used across the application.
plugins
Package plugins provides a unified plugin system for managing skills, recipes, and extensions.
 Package plugins provides a unified plugin system for managing skills, recipes, and extensions.
presenter
Package presenter provides consistent CLI output functionality for user-facing messages, including success, error, warning, and informational output with color support and quiet mode.
 Package presenter provides consistent CLI output functionality for user-facing messages, including success, error, warning, and informational output with color support and quiet mode.
runner/client
Package client implements the workspace-bound side of the runner protocol.
 Package client implements the workspace-bound side of the runner protocol.
runner/controlplaneurl
Package controlplaneurl provides canonical control-plane URL identity and endpoint construction.
 Package controlplaneurl provides canonical control-plane URL identity and endpoint construction.
runner/localstate
Package localstate stores runner identity, registrations, and workspace locks outside source repositories.
 Package localstate stores runner identity, registrations, and workspace locks outside source repositories.
runner/protocol
Package protocol defines the versioned JSON-RPC protocol shared by Kodelet control planes and workspace-bound runners.
 Package protocol defines the versioned JSON-RPC protocol shared by Kodelet control planes and workspace-bound runners.
runner/protocol/payload
Package payload defines runner application payloads that depend on Kodelet's model, tool, slash-command, and extension types.
 Package payload defines runner application payloads that depend on Kodelet's model, tool, slash-command, and extension types.
runner/registry
Package registry owns live runner registrations and run-lease coordination in the control plane.
 Package registry owns live runner registrations and run-lease coordination in the control plane.
skills
Package skills provides an agentic skills system where the model can autonomously invoke specialized capabilities based on task context.
 Package skills provides an agentic skills system where the model can autonomously invoke specialized capabilities based on task context.
slashcommands
Package slashcommands provides recipe-backed slash command parsing and expansion.
 Package slashcommands provides recipe-backed slash command parsing and expansion.
steer
Package steer provides persistent user steering for autonomous conversations.
 Package steer provides persistent user steering for autonomous conversations.
sysprompt
Package sysprompt renders system prompts from embedded templates.
 Package sysprompt renders system prompts from embedded templates.
telemetry
Package telemetry provides OpenTelemetry tracing for Kodelet
 Package telemetry provides OpenTelemetry tracing for Kodelet
tools
Package tools provides the core tool execution framework for Kodelet.
 Package tools provides the core tool execution framework for Kodelet.
tools/renderers
Package renderers provides CLI output rendering functionality for tool results.
 Package renderers provides CLI output rendering functionality for tool results.
tui
Package tui implements Kodelet's native terminal chat interface.
 Package tui implements Kodelet's native terminal chat interface.
types/conversations
Package conversations defines types and interfaces for conversation data structures, query options, and conversation records used throughout kodelet's conversation management system.
 Package conversations defines types and interfaces for conversation data structures, query options, and conversation records used throughout kodelet's conversation management system.
types/llm
Package llm defines types and interfaces for Large Language Model interactions including message handlers, threads, configuration, and usage tracking for different LLM providers.
 Package llm defines types and interfaces for Large Language Model interactions including message handlers, threads, configuration, and usage tracking for different LLM providers.
types/tools
Package tools defines interfaces and types for kodelet's tool system including tool execution, result structures, state management, and JSON schema generation for LLM tool integration.
 Package tools defines interfaces and types for kodelet's tool system including tool execution, result structures, state management, and JSON schema generation for LLM tool integration.
usage
Package usage provides functionality for tracking and calculating usage statistics for LLM conversations including token counts, conversation metrics, and time-based analytics for monitoring system performance.
 Package usage provides functionality for tracking and calculating usage statistics for LLM conversations including token counts, conversation metrics, and time-based analytics for monitoring system performance.
version
Package version provides version information for kodelet including semantic version, git commit SHA, build time, and build information that are set during the build process.
 Package version provides version information for kodelet including semantic version, git commit SHA, build time, and build information that are set during the build process.
vision
Package vision provides provider-neutral image preprocessing helpers.
 Package vision provides provider-neutral image preprocessing helpers.
webui
Package webui provides Kodelet's embedded browser application.
 Package webui provides Kodelet's embedded browser application.
scripts
package-binary-metadata command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.