Klaudia Kode

Klaudia Kode is a coding agent wrapper CLI that can run against many LLM providers through a local OpenRouter-compatible proxy.

Use the CLI as klaudiak.

Quick Start

1. Install and verify:

npm i -g klaudiak
klaudiak --help

2. Start the proxy in one terminal:

klaudiak proxy deepseek/deepseek-chat-v3-0324 key sk-or-v1-... --port=10000

3. Start the coding agent in another terminal:

klaudiak --port=10000

If your proxy runs on default port 9090, you can simply run:

klaudiak

Laziest Setup (Two Commands)

If you want daily usage to be exactly:

klaudiak proxy
klaudiak

set the default profile once:

klaudiak defaults set default type proxy
klaudiak defaults set default openrouterModel deepseek/deepseek-chat-v3-0324
klaudiak defaults set default openrouterApiKey sk-or-v1-...
klaudiak defaults set default proxyPort 9090
klaudiak defaults set default anthropicBaseUrl http://localhost:9090

Then every day:

1. Terminal A: klaudiak proxy
2. Terminal B: klaudiak

If you choose another port, keep proxyPort and anthropicBaseUrl aligned to the same value.

Screenshots of this exact lazy flow:

klaudiak proxy

klaudiak

Recommended Daily Workflow

For repeat usage, set profile defaults once and then launch with short commands.

# Create a dedicated profile
klaudiak defaults create deepseek

# Save proxy settings to that profile
klaudiak defaults set deepseek type proxy
klaudiak defaults set deepseek openrouterModel deepseek/deepseek-chat-v3-0324
klaudiak defaults set deepseek openrouterApiKey sk-or-v1-...
klaudiak defaults set deepseek proxyPort 10000

# Terminal A: run proxy from profile (no model/key arguments needed)
klaudiak proxy --profile=deepseek

# Terminal B: run agent against the same proxy port
klaudiak --profile=deepseek --port=10000

This gives you predictable, reusable setup with minimal typing.

Command Reference

Start agent

klaudiak
klaudiak [agentArgs...]
klaudiak --profile=<name>
klaudiak --defaults=<name>
klaudiak --port=<port>
klaudiak --port <port>

• klaudiak starts the coding agent.
• Any additional args are forwarded to cli.js (for example -p "...").
• --profile=<name> loads settings from ~/.klaudiak profile <name>.
• --defaults=<name> is an alias of --profile=<name>.
• --port=<port> sets ANTHROPIC_BASE_URL=http://localhost:<port> for this run (overrides profile/env base URL).
• --port <port> is also supported.

When no profile flag is passed, Klaudiak always uses the default profile.

Behavior details that matter:

• Agent arguments are forwarded to cli.js after removing --profile/--defaults and --port.
• If running against localhost/127.0.0.1, Klaudiak auto-enables --bare unless you already passed it.
• If running against localhost and no Anthropic auth env vars are set, Klaudiak injects local placeholder auth values to avoid OAuth/login fallback.

Start proxy

klaudiak proxy
klaudiak proxy --profile=<name>
klaudiak proxy <model> key <apiKey> --port=<port>
klaudiak proxy <model> key <apiKey> --port <port>

Example:

klaudiak proxy openai/gpt-4o-mini key sk-or-v1-... --port=9090

• <model> is passed to OPENROUTER_MODEL.
• <apiKey> is passed to OPENROUTER_API_KEY.
• --port=<port> is passed to PROXY_PORT.
• --port <port> is also supported.

You can also run proxy from a profile with no model/key arguments when that profile includes openrouterModel and openrouterApiKey:

klaudiak proxy
klaudiak proxy --profile=<name>

Global defaults profiles

Klaudiak stores global profile defaults in ~/.klaudiak (JSON). The file is auto-created whenever klaudiak runs.

Common commands:

klaudiak defaults list
klaudiak defaults show default
klaudiak defaults create gemini
klaudiak defaults set gemini type proxy
klaudiak defaults set gemini openrouterModel google/gemini-2.5-pro
klaudiak defaults set gemini openrouterApiKey sk-or-v1-...
klaudiak defaults unset gemini anthropicApiKey
klaudiak defaults delete gemini

Supported fields:

• type (agent or proxy)
• anthropicBaseUrl
• anthropicApiKey
• anthropicModel
• proxyPort
• openrouterModel
• openrouterApiKey

Notes:

• Profile names must match ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$.
• default profile always exists and cannot be deleted.
• klaudiak auto-creates ~/.klaudiak on first run.

Configuration Precedence

For agent startup, effective values follow this order:

1. Existing environment variables (for example ANTHROPIC_API_KEY, ANTHROPIC_MODEL, ANTHROPIC_BASE_URL)
2. Selected profile values from ~/.klaudiak
3. CLI --port (overrides base URL to http://localhost:<port>)

Practical rule: if you pass --port, that port wins for ANTHROPIC_BASE_URL.

How It Works

Klaudia Kode CLI --> local proxy (default :9090) --> OpenRouter/provider

The agent speaks Anthropic-compatible protocol to the local proxy. The proxy translates and routes requests to the model/provider you selected.

Power Tips

• Use profiles per provider/model combo so you can switch quickly with --profile=<name>.
• Keep proxy and agent ports explicit when debugging: klaudiak proxy ... --port=10000 and klaudiak --port=10000.
• Use klaudiak defaults show <name> to confirm values before running.
• Store secrets in profile only on trusted machines, and rotate keys periodically.

Troubleshooting

Proxy not running

If you see a startup error about proxy connectivity:

1. Start proxy with the same port you want to use.
2. Start agent with matching --port=<port> or set ANTHROPIC_BASE_URL manually.

Wrong port

Use the same explicit port in both commands:

klaudiak proxy <model> key <apiKey> --port=10000
klaudiak --port=10000

Invalid key or model

Make sure:

• API key starts with an OpenRouter key format such as sk-or-v1-...
• Model string is valid for your provider account

Profile not found

If you pass --profile=<name> and get a not-found error:

1. Check available profiles with klaudiak defaults list.
2. Create it with klaudiak defaults create <name>.
3. Set required fields using klaudiak defaults set ....

Invalid profile file JSON

If ~/.klaudiak contains invalid JSON, Klaudiak recreates it with defaults and prints a warning.

Migration from Klaudiak

• Package/command is now klaudiak
• Legacy aliases are removed
• Proxy command contract is standardized as:
  • klaudiak proxy <model> key <apiKey> --port=<port>

Requirements

• Node.js 18+

License

MIT