@kilidify/claude

Use Claude Code through Kilidify: pay for Claude in rials, keep your Claude Code workflow.

English · فارسی

English

What it does

• kilidify starts Claude Code pointed at the Kilidify gateway, with your Kilidify key and model mapping, without touching any settings file.
• kilidify setup makes that permanent in Claude Code's own settings, so plain claude goes through Kilidify.
• kilidify status and kilidify models show your balance, the live dollar rate, and model prices in dollars and tomans.
• kilidify mcp is an MCP server that lets Claude itself check your balance, the rate, model prices, and estimate a request's cost.

Install

Requires Node.js 18 or newer, and Claude Code itself:

npm install -g @anthropic-ai/claude-code
npm install -g @kilidify/claude

Quick start

npx @kilidify/claude login      # paste your kl_live_… key from the Kilidify dashboard
npx @kilidify/claude            # starts Claude Code through Kilidify

Anything you would pass to claude works the same way:

kilidify -p "explain this repository"
kilidify -- --model opus          # everything after -- goes to claude unchanged

Make it permanent

kilidify setup            # ~/.claude/settings.json (all projects)
kilidify setup --project  # .claude/settings.local.json (this project only)
kilidify setup --mcp      # also register the MCP server
kilidify setup --undo     # remove what setup wrote

setup merges into the existing file, keeps every other setting, and writes a backup next to it (settings.json.kelid-backup-…) first.

It configures an apiKeyHelper that runs kilidify key, so the key stays in Kilidify's own config file (owner-only, 0600) rather than in Claude Code's settings. Install globally before running setup; a helper pointing into a temporary npx cache can stop working. --plain-key writes the key into the settings file instead. If the file already has someone else's apiKeyHelper, setup stops unless you pass --force.

Commands

| Command | What it does | | --- | --- | | login [--key kl_live_…] [--no-verify] | Check the key against the gateway and store it | | logout | Remove the stored key | | [run] [claude args…] | Start Claude Code through Kilidify | | setup [--project] [--mcp] [--plain-key] [--force] [--undo] | Write Claude Code settings | | status | Gateway reachability, key validity, balance in USD and tomans, live rate, Claude Code version | | models [--search text] [--all] [--json] | Claude models with prices per million tokens in USD and tomans | | mcp | Stdio MCP server | | key | Print the stored key (used by apiKeyHelper) | | config [set <name> <value> \| unset <name>] | Show or change settings |

Configuration

| Setting (config set) | Environment | Default | | --- | --- | --- | | gateway | KELID_GATEWAY_URL | https://api.kilidify.com | | web (live rate) | KELID_WEB_URL | https://kilidify.com | | model.opus | KELID_MODEL_OPUS | anthropic/claude-opus-5 | | model.sonnet | KELID_MODEL_SONNET | anthropic/claude-sonnet-5 | | model.haiku | KELID_MODEL_HAIKU | ~anthropic/claude-haiku-latest | | model.fable | KELID_MODEL_FABLE | anthropic/claude-fable-5.1 | | model.subagent | KELID_MODEL_SUBAGENT | unset (Claude Code decides) | | nonessential | — | on: turn off Claude Code's traffic outside the gateway | | discovery | — | on: list the gateway's Claude models in /model |

The key can also come from KELID_API_KEY. Config lives in ~/.config/kelid/config.json (%APPDATA%\kelid on Windows, or KELID_CONFIG_DIR). For local development:

kilidify config set gateway http://localhost:4000
kilidify config set web http://localhost:3000

MCP server

kilidify setup --mcp
# or by hand:
claude mcp add --scope user --transport stdio kelid -- kilidify mcp

Tools: kelid_balance, kelid_exchange_rate, kelid_search_models, kelid_estimate_cost. The server reads the stored key on every call, so a new login applies without restarting Claude Code.

Troubleshooting

| Symptom | Cause and fix | | --- | --- | | 401 / "Invalid API key" | The key is wrong or revoked. Run kilidify login again. | | 402 / not_provisioned | The account has no upstream access until its first top-up. Top up on kilidify.com. | | 402 / insufficient_balance | The wallet is empty. Top up. | | 403 / model_not_allowed | This key is restricted to certain models. Change the model mapping or the key's allowed models. | | Claude Code opens the login screen | No credential reached it. Run kilidify instead of claude, or kilidify setup. | | "Your apiKeyHelper script is failing" | The helper path moved (npx cache, reinstall). Install globally and re-run kilidify setup. | | /model shows no gateway models | Discovery has a 3-second timeout; it falls back to the built-in list. Aliases still resolve through the model mapping. | | Web fetch or /fast report connectivity errors | Those checks go to api.anthropic.com directly, not through the gateway. Inference is unaffected. |

How it works

Claude Code speaks the Anthropic Messages API to whatever ANTHROPIC_BASE_URL names. Kilidify's gateway accepts that traffic on /v1/messages, checks the key, rate limit and wallet, forwards it to OpenRouter's Anthropic-compatible endpoint with the customer's own capped OpenRouter key, streams the response straight back, and bills the wallet from the usage and cost OpenRouter reports.

Facts this package relies on, checked against the sources on 14 September 2026:

• ANTHROPIC_BASE_URL points Claude Code at a gateway; it calls /v1/messages (as /v1/messages?beta=true) and optionally /v1/messages/count_tokens, and falls back to an estimate without it. Gateways must forward anthropic-version and anthropic-beta unchanged, stream without buffering, and relay upstream error bodies unmodified. — Gateway compatibility guide
• ANTHROPIC_AUTH_TOKEN is sent as Authorization: Bearer, ANTHROPIC_API_KEY as x-api-key, and an apiKeyHelper value in both; the helper's output is cached for five minutes (CLAUDE_CODE_API_KEY_HELPER_TTL_MS). CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 turns off traffic outside the gateway. — Connect Claude Code to an LLM gateway, Environment variables
• ANTHROPIC_DEFAULT_OPUS_MODEL, …_SONNET_MODEL, …_HAIKU_MODEL and …_FABLE_MODEL set what the aliases resolve to; CLAUDE_CODE_SUBAGENT_MODEL sets the subagent model. — Model configuration
• With CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, Claude Code calls GET /v1/models?limit=1000 (3-second timeout) and keeps entries whose id contains claude or anthropic, reading display_name when present. — Gateway compatibility guide › Model discovery
• Settings files and the env block: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json. — Settings
• claude mcp add [options] <name> -- <command> [args…], scopes local, project, user. — MCP
• OpenRouter exposes an Anthropic Messages-compatible endpoint at https://openrouter.ai/api/v1/messages (base URL https://openrouter.ai/api), with model ids such as anthropic/claude-sonnet-5. Responses carry msg_… ids and a usage object with input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens and cost (USD). — OpenRouter: Claude Code integration, OpenRouter: Create a message
• In Anthropic streams, usage starts in message_start.message.usage and the counts in message_delta.usage are cumulative. — Streaming messages
• Gateway-generated errors use Anthropic's error shape and status-to-type mapping (401 authentication_error, 402 billing_error, 429 rate_limit_error, …). — API errors

فارسی

این بسته چه می‌کند

• kilidify Claude Code را با کلید و تنظیمات مدل کلید اجرا می‌کند، بدون اینکه فایل تنظیماتی تغییر کند.
• kilidify setup این پیکربندی را در تنظیمات خود Claude Code دائمی می‌کند تا دستور claude هم از طریق کلیدیفای کار کند.
• kilidify status و kilidify models موجودی، نرخ لحظه‌ای دلار و قیمت مدل‌ها را به دلار و تومان نشان می‌دهند.
• kilidify mcp یک سرور MCP است تا خود Claude بتواند موجودی، نرخ و قیمت مدل‌ها را ببیند و هزینهٔ یک درخواست را تخمین بزند.

نصب

به Node.js نسخهٔ ۱۸ یا بالاتر و خود Claude Code نیاز دارید:

npm install -g @anthropic-ai/claude-code
npm install -g @kilidify/claude

شروع سریع

npx @kilidify/claude login      # کلید kl_live_… را از داشبورد کلید وارد کنید
npx @kilidify/claude            # Claude Code از طریق کلیدیفای اجرا می‌شود

هر آرگومانی که به claude می‌دهید، همین‌جا هم کار می‌کند. آرگومان‌های بعد از -- بدون تغییر به Claude Code می‌رسند.

پیکربندی دائمی

kilidify setup            # برای همهٔ پروژه‌ها (~/.claude/settings.json)
kilidify setup --project  # فقط همین پروژه (.claude/settings.local.json)
kilidify setup --mcp      # ثبت سرور MCP
kilidify setup --undo     # حذف تنظیمات کلید

setup تنظیمات موجود را حفظ می‌کند و پیش از تغییر، یک نسخهٔ پشتیبان کنار فایل می‌سازد. کلید در فایل تنظیمات Claude Code نوشته نمی‌شود: Claude Code آن را از دستور kilidify key می‌گیرد و کلید فقط در فایل پیکربندی کلید با دسترسی مالک (0600) می‌ماند. پیش از setup بسته را به صورت سراسری نصب کنید.

رفع اشکال

| نشانه | علت و راه‌حل | | --- | --- | | خطای 401 | کلید اشتباه یا باطل شده است. دوباره kilidify login را اجرا کنید. | | خطای 402 با not_provisioned | حساب پیش از اولین شارژ فعال نمی‌شود. حساب را در kilidify.com شارژ کنید. | | خطای 402 با insufficient_balance | موجودی کیف پول تمام شده است. حساب را شارژ کنید. | | خطای 403 با model_not_allowed | این کلید به مدل‌های مشخصی محدود است. نگاشت مدل یا مدل‌های مجاز کلید را تغییر دهید. | | Claude Code صفحهٔ ورود را نشان می‌دهد | کلیدی به آن نرسیده است. به جای claude از kilidify استفاده کنید یا setup را اجرا کنید. |

جزئیات فنی و منابع در بخش انگلیسی «How it works» آمده است.