klaude-code 2.24.0

Minimal code agent CLI

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: Task, Explore
• Structured sub-agent output: Main agent defines JSON schema and get schema-compliant responses via constrained decoding
• 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)
• Sessions: Resumable with --continue
• Extras: Slash commands, sub-agents, image paste, terminal notifications, auto-theming

Installation

uv tool install klaude-code

To update:

uv tool upgrade klaude-code

Or use the built-in command:

klaude upgrade

Development Install

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:

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

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:

# 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 BRAVE_API_KEY=BSA-xxx             # Brave Search (optional, WebSearch provider)
export EXA_API_KEY=exa-xxx               # Exa Search (optional, WebSearch provider)

# 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 helper models:

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

compact_model:
  - gemini-flash
  - haiku

Klaude tries these entries in order and uses the first available model. fast_model is used for session-title generation; compact_model is used for compact/helper tasks.

Built-in Providers

Provider	Env Variable	Models
anthropic	ANTHROPIC_API_KEY	sonnet, sonnet-no-thinking, opus, haiku
openai	OPENAI_API_KEY	gpt-5.4-high, gpt-5.4-xhigh, gpt-5.3-codex, gpt-5.3-codex-xhigh
openrouter	OPENROUTER_API_KEY	gpt-5.3-codex, gpt-5.3-codex-xhigh, gpt-5.4-high, gpt-5.4-xhigh, kimi, haiku, sonnet, sonnet-no-thinking, opus, gemini-pro, gemini-flash, grok, minimax, glm
google	GOOGLE_API_KEY or GEMINI_API_KEY	gemini-pro, gemini-flash
google-vertex	GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION	gemini-pro, gemini-flash
bedrock	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION	sonnet
deepseek	DEEPSEEK_API_KEY	deepseek
moonshot	MOONSHOT_API_KEY	kimi
cerebras	CEREBRAS_API_KEY	glm
claude-max	N/A (OAuth)	sonnet, sonnet-no-thinking, opus, haiku
codex	N/A (OAuth)	gpt-5.3-codex, gpt-5.3-codex-xhigh, gpt-5.4-high, gpt-5.4-xhigh
github-copilot	N/A (OAuth)	gpt-5.3-codex, gpt-5.3-codex-xhigh, gpt-5.4-high, gpt-5.4-xhigh, sonnet, sonnet-4.5, haiku, opus
ark-api	ARK_API_KEY	seed-pro, seed-code
ark-coding-plan	ARK_API_KEY	seed-code, kimi

List all configured providers and models:

klaude list

Models from providers without a valid API key are shown as dimmed/unavailable.

Authentication

Use the auth command to configure API keys or login to subscription-based providers:

# Interactive provider selection
klaude auth login

# Configure API keys
klaude auth login anthropic   # Set ANTHROPIC_API_KEY
klaude auth login openai      # Set OPENAI_API_KEY
klaude auth login google      # Set GOOGLE_API_KEY
klaude auth login openrouter  # Set OPENROUTER_API_KEY
klaude auth login deepseek    # Set DEEPSEEK_API_KEY
klaude auth login moonshot    # Set MOONSHOT_API_KEY

# OAuth login for subscription-based providers
klaude auth login codex       # ChatGPT Pro subscription

API keys are stored in ~/.klaude/klaude-auth.json and used as fallback when environment variables are not set.

To logout from OAuth providers:

klaude auth logout codex

Custom Configuration

User config file: ~/.klaude/klaude-config.yaml

Open in editor:

klaude conf

Model Configuration

You can add custom models to built-in providers or define new ones. Configuration is inherited from built-in providers by matching provider_name.

# ~/.klaude/klaude-config.yaml
main_model: opus

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

compact_model:
  - gemini-flash
  - haiku

provider_list:
  # Add/Override models for built-in OpenRouter provider
  - provider_name: openrouter
    model_list:
      - model_name: qwen-coder
        model_id: qwen/qwen-2.5-coder-32b-instruct
        context_limit: 131072
        cost: { input: 0.3, output: 0.9 }
      - model_name: sonnet # Override built-in sonnet params
        model_id: anthropic/claude-3.5-sonnet
        context_limit: 200000

  # Add a completely new provider
  - provider_name: my-azure
    protocol: openai
    api_key: ${AZURE_OPENAI_KEY}
    base_url: https://my-instance.openai.azure.com/
    is_azure: true
    azure_api_version: "2024-02-15-preview"
    model_list:
      - model_name: gpt-4
        model_id: gpt-4-deploy-name
        context_limit: 128000

Key Tips:

• Merging: If provider_name matches a built-in provider, settings like protocol and api_key are inherited.
• Overriding: Use the same model_name as a built-in model to override its parameters.
• Environment Variables: Use ${VAR_NAME} syntax for secrets.
• Model Preference Lists: fast_model and compact_model accept either a single string or a list of model selectors. When you provide a list, Klaude tries them in order and picks the first available one.

Sub-agent Model Configuration

sub_agent_models only accepts sub-agent types. Current supported keys are:

• general-purpose (Task sub-agent)
• explore (Explore sub-agent)

If a sub-agent type is not configured, it falls back to the main agent model.

sub_agent_models:
  general-purpose: sonnet
  explore: haiku

Supported Protocols

• anthropic - Anthropic Messages API
• openai - OpenAI Chat Completion API
• responses - OpenAI Responses API (for o-series, GPT-5, Codex)
• codex_oauth - OpenAI Codex CLI (OAuth-based, for ChatGPT Pro subscribers)
• openrouter - OpenRouter API (handling reasoning_details for interleaved thinking)
• google - Google Gemini API
• bedrock - AWS Bedrock for Claude(uses AWS credentials instead of api_key)

List configured providers and models:

klaude list

Cost Tracking

View aggregated usage statistics across all sessions:

# Show all historical usage data
klaude cost

# Show usage for the last 7 days only
klaude cost --days 7

# Alias for days
klaude cost --recent 7

Slash Commands

Inside the interactive session (klaude), use these commands to streamline your workflow:

• /... supports mixed completion for commands + skills (command names take priority on conflicts).

• //... shows skill-only completion and triggers skills explicitly.

• /model - Switch the active LLM during the session.

• /thinking - Configure model thinking/reasoning level.

• /clear - Clear the current conversation context.

• /copy - Copy last assistant message.

• /status - Show session usage statistics (cost, tokens, model breakdown).

• /resume - Select and resume a previous session.

• /fork-session - Fork current session to a new session ID (supports interactive fork point selection).

• /export - Export last assistant message to a temp Markdown file.

• /debug [filters] - Toggle debug mode and configure debug filters.

• /init - Bootstrap a new project structure or module.

• /dev-doc [feature] - Generate a comprehensive execution plan for a feature.

• /terminal-setup - Configure terminal for Shift+Enter support.

• /help - List all available commands.

Input Shortcuts

Key	Action
Enter	Submit input
Shift+Enter	Insert newline (requires /terminal-setup)
Ctrl+J	Insert newline
Ctrl+L	Open model picker overlay
Ctrl+T	Open thinking level picker overlay
Ctrl+V	Paste image from clipboard
Left/Right	Move cursor (wraps across lines)
Backspace	Delete character or selected text
c (with selection)	Copy selected text to clipboard

Sub-Agents

The main agent can spawn specialized sub-agents for specific tasks:

Sub-Agent	Purpose
Explore	Fast codebase exploration - find files, search code, answer questions about the codebase
Task	Handle complex multi-step tasks autonomously