Klaude Code

# Klaude Code

Minimal code agent CLI.

## Features
- **Multi-provider**: Anthropic Message API, OpenAI Responses API, OpenRouter, ChatGPT Codex OAuth etc.
- **Keep reasoning item in context**: Interleaved thinking support
- **Model-aware tools**: Claude Code tool set for Opus, `apply_patch` for GPT-5/Codex
- **Reminders**: Cooldown-based todo tracking, instruction reinforcement and external file change reminder
- **Sub-agents**: General Purpose, Finder, Code Reviewer, Code Simplifier (+ fork-context variant)
- **Recursive `@file` mentions**: Circular dependency protection, relative path resolution
- **External file sync**: Monitoring for external edits (linter, manual)
- **Interrupt handling**: Ctrl+C preserves partial responses and synthesizes tool cancellation results
- **Output truncation**: Large outputs saved to file system with snapshot links
- **Agent Skills**: Built-in + user + project Agent Skills (with implicit invocation by Skill tool or explicit invocation by typing `//skill` or `/skill`)
- **Prompt caching**: Append-only message history maximizes prefix cache hits (cached tokens cost 10% of base input)
- **Context management**: Auto-compaction, Rewind (rollback to checkpoint), Handoff (compress and continue in fresh context)
- **Auto memory**: Persistent cross-session memory per project (`~/.klaude/projects/<project>/memory/`)
- **Web UI**: Browser-based interface via `klaude web` or `/web` slash command
- **Sessions**: Resumable with `--continue`, forkable with `/fork-session`
- **Extras**: Slash commands, sub-agents, image paste, terminal notifications, auto-theming

## Installation

```bash
uv tool install klaude-code
```

To update:

```bash
uv tool upgrade klaude-code
```

Or use the built-in command:

```bash
klaude upgrade
```

### Development Install

```bash
git clone https://github.com/inspirepan/klaude-code.git
cd klaude-code
make install    # init submodules, build web frontend, install as editable
```

Or step by step:

```bash
git submodule update --init --recursive
uv sync                              # install Python deps
uv run python scripts/build_web.py   # build web frontend
uv tool install -e .                 # install CLI globally (editable)
```

Requires `pnpm` or `npm` for the web frontend build (`pnpm` preferred).

## Usage

```bash
klaude [--model [<name>]] [--continue] [--resume [<id>]]
```

**Options:**
- `--model`/`-m`: Choose a model.
  - `--model` (no value): opens the interactive selector.
  - `--model <value>`: resolves `<value>` to a single model; if it can't, it opens the interactive selector filtered by `<value>`.
- `--continue`/`-c`: Resume the most recent session.
- `--resume`/`-r`: Resume a session.
  - `--resume` (no value): select a session to resume for this project.
  - `--resume <id>`: resume a session by its ID directly.
- `--vanilla`: Minimal mode with only basic tools (Bash, Read, Edit, Write) and no system prompts.

**Model selection behavior:**
- Default: uses `main_model` from config.
- `--model` (no value): always prompts you to pick.
- `--model <value>`: tries to resolve `<value>` to a single model; if it can't, it prompts with a filtered list (and falls back to showing all models if there are no matches).

**Debug Options:**
- `--debug`/`-d`: Enable debug mode with verbose logging and LLM trace.
- `--debug-filter`: Filter debug output by type (comma-separated).


### Configuration

#### Quick Start (Zero Config)

Klaude comes with built-in provider configurations. Just set an API key environment variable and start using it:

```bash
# Pick one (or more) of these:
export ANTHROPIC_API_KEY=sk-ant-xxx      # Claude models
export OPENAI_API_KEY=sk-xxx             # GPT models
export OPENROUTER_API_KEY=sk-or-xxx      # OpenRouter (multi-provider)
export DEEPSEEK_API_KEY=sk-xxx           # DeepSeek models
export MOONSHOT_API_KEY=sk-xxx           # Moonshot/Kimi models
export MINIMAX_API_KEY=xxx               # MiniMax models
export GOOGLE_API_KEY=xxx                # Google Gemini models (or GEMINI_API_KEY)
export EXA_API_KEY=exa-xxx               # Exa Search (optional, WebSearch provider, preferred)
export BRAVE_API_KEY=BSA-xxx             # Brave Search (optional, WebSearch provider, fallback)

# Then just run:
klaude
```

On first run, you'll be prompted to select a model. Your choice is saved as `main_model`.

You can also configure fallback lists for the main model and helper models:

```yaml
main_model:
  - gpt-5.5
  - gpt-5.4
  - opus

fast_model:
  - haiku
  - gemini-flash
  - gpt-5-nano

compact_model:
  - gemini-flash
  - haiku
```

Klaude expands each entry into concrete provider candidates in `provider_list` order, then falls through to the next model in the list. For example, `gpt-5.4` will try available providers such as `gpt-5.4@openai` and `gpt-5.4@openrouter` before moving to the next model. Runtime fallback is used for non-retryable provider/model failures such as quota, billing, permission, or model-unavailable errors. `fast_m

... (truncated)