Documentation

Kodelet Documentation

Kodelet is a lightweight agentic SWE agent that runs in your terminal. It handles software engineering work, production operations tasks, and repository automation from a local CLI.

Installation

Homebrew

# Install via Homebrew on macOS or Linux
brew tap jingkaihe/kodelet
brew install kodelet

Install script

# Install using the default package-based installer
curl -sSL https://raw.githubusercontent.com/jingkaihe/kodelet/main/install.sh | bash

The default install path is package-based: Homebrew on macOS and .deb or .rpm packages on Linux.

Quick Start

Use one-shot mode for fast automation, kodelet serve for a chat-based web UI, and ACP for longer interactive sessions:

# Ask Kodelet to plan a custom tool implementation
kodelet run "comes up a plan of implementing the custom tool"

# Follow up on the previous conversation and have it implement the plan
kodelet run --follow "now implement it"

# Launch the local chat-based web UI
kodelet serve

# Connect an ACP client for interactive chat mode
toad acp 'kodelet acp'

Usage Modes

One-shot mode: kodelet run "your query" with support for persisted conversations, --follow, --resume, --result-only, --no-tools, --disable-fs-search-tools, and headless JSON output.
Web UI mode: kodelet serve launches a chat-based web UI for using Kodelet locally, typically on localhost:8080.
Interactive ACP mode: Connect an ACP client such as toad to kodelet acp for real-time streaming, multi-turn conversations, and tool execution visualization.
Git workflows: kodelet commit and kodelet pr support common repository workflows.
Vision support: kodelet run --image ./diagram.png "review this architecture" supports screenshots, diagrams, and mockups on vision-enabled models.
Programmatic access: kodelet run --headless and conversation stream commands support structured streaming for integrations and tooling.

Common Commands

# Analyze a repository from the CLI
kodelet run "analyze this codebase"

# Launch the local chat-based web UI
kodelet serve

# Emit structured JSON for automation and integrations
kodelet run --headless "produce structured output"

# Generate a commit message from staged changes
kodelet commit

Providers and Authentication

Kodelet supports Anthropic Claude, OpenAI-compatible models, and Google Gemini. The current docs also cover OpenAI Codex authentication and Anthropic multi-account login flows.

Example environment-based configuration:

export KODELET_PROVIDER="openai"
export KODELET_MODEL="gpt-5.4"
export OPENAI_API_KEY="your-api-key"

You can also configure Anthropic or Google credentials, or use layered config files in ~/.kodelet/config.yaml and ./kodelet-config.yaml.

Configuration Model

Command-line flags override environment variables.
Environment variables override configuration files.
Repository configuration in kodelet-config.yaml merges with and overrides your global config.
Profiles let you switch between named setups for different models and workflows.

Extensibility

Agent context files: AGENTS.md files provide project-specific context automatically.
Custom tools: Executables in .kodelet/tools/ or ~/.kodelet/tools/ extend Kodelet with a simple JSON protocol.
Agentic skills: Discoverable domain-specific capabilities are invoked automatically when relevant.
Lifecycle hooks: Executables in .kodelet/hooks/ or ~/.kodelet/hooks/ can audit, block, or modify agent behaviour.
Plugins: Repositories can package skills, hooks, and other reusable capabilities.

Upstream Docs

Examples

Architecture and repository analysis

kodelet "analyze the architecture of this codebase"

Images and diagrams

kodelet run --image ./architecture.png "review this system architecture and suggest improvements"

GitHub automation

kodelet pr

Contributing

Contributions are welcome. Start with the GitHub repository and the development guide.

License

This project is licensed under the MIT License.