cleankoda logo

Getting Started with cleankoda

cleankoda is a terminal-native AI coding agent that manages the entire development cycle, from the initial ticket request to the final pull request.

Instead of generating code in isolation within a chat window, cleankoda works directly on your file system and applies changes in a controlled, sandboxed environment. You remain in full control throughout the process: every step—from the execution plan to the unified diffs—is displayed transparently and requires your keyboard-based approval.

Prerequisites

Before installing cleankoda, ensure the following tools are available on your system:

  • Python: Version 3.10 or newer.
  • uv: An extremely fast Python package and project manager (recommended for isolated tool management).
  • Docker: Required for sandboxing. cleankoda executes shell commands, test runs, and code analyses in isolated containers to protect your host system from unintended side effects.
  • API Keys: At least one API key from a supported LLM provider (e.g., Anthropic, OpenAI, or a local Ollama setup) as well as API tokens for your issue trackers (Jira, GitHub, or Trello).

Installation

Choose the installation method appropriate for your operating system.

On Linux, the fastest way to install cleankoda is via the official shell script. It checks for dependencies and automatically sets up the executable in your system path:

curl -fsSL https://cleankoda.com/install.sh | bash

macOS & Windows (Download & uv)

On macOS and Windows, you can install cleankoda directly from the release package using uv:

  1. Download the latest release package from the download page or the GitHub repository.
  2. Install the tool in an isolated environment using uv.
uv tool install cleankoda

Tip: If you haven’t installed uv yet, you can install it from astral.sh/uv.

Getting Started

cleankoda is always launched from the root directory of the project you are currently working on.

For the best workflow, launch cleankoda in your editor’s integrated terminal (e.g., VS Code, Cursor, Zed, or Neovim). This allows you to see file changes and Git status indicators alongside the diffs in the terminal:

cd /pfad/zu/deinem/projekt
cleankoda

2. In the operating system’s standalone terminal

Alternatively, you can use any standard terminal (e.g., Alacritty, Kitty, WezTerm, iTerm2, or Windows Terminal):

cd /pfad/zu/deinem/projekt
cleankoda

Upon initial startup, cleankoda checks the Docker connection for sandboxing, loads the repository context, and opens the interactive TUI dashboard.