Usage

The built-in terminal UI and Web UI are the main ways to work with Kodelet. Both support ongoing conversations backed by the same daemon, with workspace execution handled by a runner.

Before starting, install Kodelet and configure a provider. Begin with terminal chat from your project directory, or start the managed daemon and open your browser.

Terminal chat

Start in the repository you want to work on:

kodelet chat

The terminal UI streams responses, shows tool activity, and saves conversations. A few useful controls:

• /new starts a conversation; /sessions or Ctrl+L opens the conversation picker.
• Ctrl+O expands or collapses thinking and tool details.
• Ctrl+R searches sent messages; extensions can override this shortcut.
• Before the first message, Ctrl+T selects a model profile and Ctrl+Y selects reasoning effort.
• During a running turn, Enter queues your message as steering. /stop cancels the active turn.

Resume a known conversation or the most recent one in a directory:

kodelet chat --resume CONVERSATION_ID
kodelet chat --cwd "$PWD" --follow

Replace CONVERSATION_ID with an ID from kodelet conversation list. Resume preserves the saved runner, working directory, and model settings. Use a new conversation to choose a different model setup.

The terminal theme follows your terminal’s appearance by default. Use /theme inside chat or select a bundled theme at startup:

kodelet chat --theme catppuccin-latte

Web UI

Start the managed local daemon and open its browser interface:

kodelet server start
kodelet server url --open

Create a conversation, select the built-in runner, and choose the project directory you want it to work in. You can return to saved conversations, inspect tool activity, and continue work from the browser. Model and runner profiles let you select an existing setup before the conversation starts.

server start reuses an existing managed daemon. server url --open can also start one if needed. The managed server normally chooses an available port, so discover its address rather than assuming port 8080.

Omit --open to print the address, including its access token. Treat that URL as a credential and do not paste it into public logs or issues.

Foreground alternative

For foreground operation instead, finish active work, stop the managed server, and start serve:

kodelet server stop
kodelet serve

serve runs until you stop it or its supervisor does. It includes a workspace runner by default. Use --runner-workspace /path/to/project to choose that runner’s starting directory, not the removed serve --cwd flag.

Keep local use on loopback. A public or shared deployment needs explicit server authentication and configuration, not just a wider listen address.

One-shot tasks

For shell workflows rather than an ongoing UI session, use run:

kodelet run "Find the cause of the failing tests and fix it. Run the relevant tests afterward."
kodelet run --cwd "$PWD" --follow "Review the patch for unnecessary changes."

Like terminal chat, run starts or reuses the local daemon when no existing server is explicitly selected. --follow must be scoped with --cwd or --runner; it does not guess which workspace’s history you intended. To continue a specific conversation, use --resume CONVERSATION_ID instead.

Pipe input when the relevant context is already available:

git diff --cached | kodelet run --no-tools --result-only "Review this staged diff for correctness."

--no-tools disables model-callable tools. --result-only prints only the final agent message to standard output, not a JSON event stream. The conversation is still saved. For structured integrations, see programmatic access.

Images and diagrams

Attach a screenshot or diagram to a vision-capable model:

kodelet run --image ./screenshot.png "Inspect this UI and identify the layout problem."

Repeat --image for multiple attachments. Local attachment paths are read on the client and sent with the request; workspace paths and --cwd belong to the runner. Image support depends on the selected provider and model.

Editors and ACP

An Agent Client Protocol client launches Kodelet with this command and argument list:

{
  "command": "kodelet",
  "args": ["acp"]
}

Place this process definition in your client’s agent configuration; the surrounding settings depend on the editor. kodelet acp is a stdio protocol process, not an interactive terminal prompt. It provides streaming, tool visualization, images, and persisted session history to compatible clients.

To target a separately managed server and runner, configure the client to launch:

kodelet acp --server https://kodelet.example --runner project-runner

Replace the example endpoint and runner name with your deployment. Authenticate as a client, not with a runner token. Session directories refer to the runner machine, and resuming keeps the original execution context.

Git workflows

After reviewing and staging the files you intend to commit:

kodelet commit

This is a commit workflow, not merely a printed suggestion. The interactive flow lets you review the generated message; --no-confirm skips confirmation when you intentionally want non-interactive committing.

Create a pull request from your branch:

kodelet pr --target main --draft

Use the actual target branch for your repository. The repository and the Git/GitHub tooling needed for these operations must be available on the selected runner.

Daemon lifecycle

The background server keeps provider configuration and conversation history available across clients. Manage the local instance with:

Stop and restart refuse while runs are active. Only use --force when you intend to cancel that work. These lifecycle commands do not administer a remote server; stop foreground serve through its terminal or supervisor.

Automatic startup is not a login service, reboot service, or crash supervisor. Explicit --server, KODELET_SERVER, or trusted server configuration is connect-only: if that endpoint is unavailable, Kodelet fails rather than silently running somewhere else.

Before upgrading, finish or cancel active work, stop older processes, and back up ~/.kodelet. Keep client, daemon, and runner releases aligned. Legacy conversations can be assigned to a runner before resuming.

Stopping work

Closing a connection and canceling a task are deliberately different:

A dropped network connection does not stop daemon-owned work. If cancellation or submission was not confirmed, inspect the saved turn receipt before submitting the task again.