One command. Any provider. Full control over Claude CLI.
Stop juggling environment variables and config files.
Claudy lets you switch between Anthropic, Z.AI, OpenRouter, Ollama, and custom endpoints with a single command — keeping credentials, config modes, and Claude frameworks cleanly isolated per profile.
Multi-provider · Config isolation · Channel bridge · Local agent bridge · Usage analytics
🇰🇷 한국어 • 🇨🇳 中文 • 🇯🇵 日本語 • 🇩🇪 Deutsch • 🇫🇷 Français • 🇪🇸 Español • 🇮🇳 हिन्दी • 🇧🇷 Português • 🇮🇩 Bahasa • 🇸🇦 العربية
| Feature | Why it matters | |
|---|---|---|
| 🔄 | Multi-provider launch | Switch across Anthropic, Z.AI, OpenRouter, Ollama, and custom endpoints in one command |
| 📦 | Config modes | Isolate CLAUDE.md, settings, skills, and agents per mode — no cross-contamination |
| 🔗 | Agent MCP bridge | Delegate tasks from Claude Code to Codex, Aider, and 20+ other agents |
| 💬 | Channel bridge | Run Telegram, Slack, and Discord bots with interactive permission prompts |
| 📊 | Usage analytics | Track token usage, costs, and tool patterns with a local Tauri dashboard |
| 🔐 | Safe process control | SIGINT/SIGTERM forwarding, atomic config writes, 0600 credential storage |
| 🔀 | Cross-provider session continuity | Sanitize sessions written by Z.AI/GLM so they resume cleanly with the Anthropic API |
| 🛠️ | Operational UX | Install, update, uninstall, doctor, ping — everything from one binary |
Claudy was inspired by Clother, a Go-based multi-provider launcher for Claude CLI. Z.AI has been the most thoroughly tested provider. If you run into any issues with other providers, please open an issue.
| Provider | Status | Notes |
|---|---|---|
| Built-in (Anthropic) | ✅ Tested | Default |
| Z.AI | ✅ Tested | |
| OpenRouter alias | Not fully tested — report issues on GitHub | |
| Ollama | Not fully tested — report issues on GitHub | |
| Custom endpoint | Not fully tested — report issues on GitHub |
1. Install
macOS / Linux:
brew install epicsagas/tap/claudyNo Homebrew? Use the installer script:
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/epicsagas/claudy/releases/latest/download/install.sh | shWindows:
irm https://github.com/epicsagas/claudy/releases/latest/download/install.ps1 | iexVia Rust toolchain:
cargo binstall claudy # pre-built binary (fast)
cargo install claudy # build from source2. Configure
claudy install # initialize dirs, config, secrets
echo 'ANTHROPIC_API_KEY=your-key' >> ~/.claudy/secrets.env3. Launch
claudy # default provider
claudy zai # Z.AI provider
claudy openrouter sonnet # OpenRouter alias4. Update
brew upgrade claudy # Homebrew
claudy update # built-in updater
# or re-run the installer script / cargo binstall claudy@latest
claudy --versionProvider credentials
| Variable | Provider |
|---|---|
ANTHROPIC_API_KEY |
Anthropic (native) |
ZAI_API_KEY |
Z.AI |
ZAI_CN_API_KEY |
Z.AI China |
MINIMAX_API_KEY |
MiniMax |
MINIMAX_CN_API_KEY |
MiniMax China |
KIMI_API_KEY |
Kimi K2 |
MOONSHOT_API_KEY |
Moonshot AI |
ARK_API_KEY |
VolcEngine |
DEEPSEEK_API_KEY |
DeepSeek |
MIMO_API_KEY |
Xiaomi MiMo |
ALIBABA_API_KEY |
Alibaba Coding Plan |
OPENROUTER_API_KEY |
OpenRouter (all aliases) |
Custom providers use the api_key_env variable defined in their custom_providers entry.
config.yaml schema
All configuration lives in ~/.claudy/config.yaml. Only add the sections you need — defaults are used for anything omitted.
Full reference: docs/config.md
# Provider overrides — override default model and model tiers per provider
provider_overrides:
zai:
model: "glm-5.1"
model_tiers:
haiku: "glm-4.7" # → ANTHROPIC_DEFAULT_HAIKU_MODEL
sonnet: "glm-5.1" # → ANTHROPIC_DEFAULT_SONNET_MODEL
opus: "glm-5" # → ANTHROPIC_DEFAULT_OPUS_MODEL
# OpenRouter aliases — invoke as: claudy or <alias>
openrouter_aliases:
kimi: "moonshotai/kimi-k2.5"
sonnet: "anthropic/claude-sonnet-4"
# Custom Anthropic-compatible providers — invoke as: claudy <slug>
custom_providers:
my-llm:
name: "my-llm"
display_name: "My Custom LLM"
base_url: "https://my-llm.com/api/anthropic"
api_key_env: "MY_LLM_API_KEY"
default_model: "my-model-v1"
# Compaction policy
compaction:
auto_compact: true # default: true
threshold: 0.8 # 0.0–1.0, default: 0.8
# Per-model context window overrides
model_settings:
deepseek-chat:
max_context_tokens: 64000
# Channel bridge — non-interactive alternative to `claudy channel add`
channel:
enabled_platforms: ["telegram"]
listen_addr: "127.0.0.1:3456"
default_profile: "zai"
platform_profiles:
telegram: "zai"
platform_allowed_users:
telegram: ["user_id_1"]
max_concurrent_sessions: 0 # 0 = unlimited
stream_timeout_secs: 1800
# Agent overrides
agents:
aider:
binary: "aider"
args: ["--message", "{prompt}"]
timeout: 300A launch target that resolves provider metadata + auth strategy (built-in provider, OpenRouter alias, or custom provider).
A named Claude config directory at ~/.claudy/modes/<name>/.
When you run:
claudy <profile> <mode> [args...]Claudy sets:
CLAUDE_CONFIG_DIR=~/.claudy/modes/<mode>/so Claude reads mode-specific config files.
Modes are also a natural fit for dedicated Claude frameworks and toolkits that ship their own CLAUDE.md, skills, agents, or settings — such as gstack, superpowers, ecc, our own epic-harness (a self-evolving Claude Code plugin), or any custom harness. Instead of polluting your default config, isolate each framework in its own mode:
# Create a dedicated mode for the framework
claudy mode create gstack
# Copy or symlink the framework's config into the mode directory
cp -r /path/to/gstack/.claude/. ~/.claudy/modes/gstack/
# Launch Claude with that framework active
claudy <profile> gstackEach mode directory is a self-contained CLAUDE_CONFIG_DIR, so frameworks never conflict with each other or with your default setup.
Pairs with epic-harness. Claudy owns the operational layer — provider switching, config isolation, channel/agent bridges — while epic-harness (3 commands, 26 auto-trigger skills, self-evolving from your failure patterns) adds agent intelligence. Same
epicsagasfamily; a clean split of concerns across modes.
Command Reference
claudy ls(alias:list): list configured/resolved profiles.claudy setup [provider](alias:config): interactive provider setup.claudy show <profile>(alias:info): show resolved provider details.claudy ping [profile](alias:test): test provider connectivity.claudy doctor(alias:status): show version, paths, and profile count.claudy sync(alias:install): install/synchronize claudy binary.claudy update: update claudy.claudy uninstall: remove installed files.claudy mode <action> [name]: manage Claude config modes.claudy channel <subcommand>: manage channel bridge.claudy mcp: run as MCP server for agent bridge.claudy analytics <subcommand>: usage analytics dashboard.claudy session sanitize: fix sessions with invalid thinking blocks from non-Anthropic providers.
claudy mode create <name>
claudy mode ls
claudy mode remove <name>Mode name rule: [a-z0-9][a-z0-9_-]* (mode is reserved).
claudy channel serve [--profile <profile>] [--listen <host:port>]
claudy channel start [--profile <profile>] [--listen <host:port>]
claudy channel stop
claudy channel restart [--profile <profile>] [--listen <host:port>]
claudy channel status
claudy channel add <telegram|slack|discord>
claudy channel remove <telegram|slack|discord>
claudy channel enable
claudy channel disablechannel add guides you through bot token, allowed users, profile, and mode mapping.
| Platform | Ingestion | Interactive buttons | Notes |
|---|---|---|---|
| Telegram | Long-polling + webhook | Inline keyboard | Most complete |
| Slack | Event subscription webhook | Block Kit actions | HMAC-SHA256 verified |
| Discord | Interaction webhook | Action row components | Ed25519 verified |
Once running, the bot responds to these commands in chat:
/help— Show available commands/cancel— Cancel current task/model— Change Claude model (interactive buttons)/yolo— Toggle auto-allow permissions/status— Show session status, profile, mode, git branch, and token usage/sessions— List recent Claude sessions (with switch buttons)/projects— List projects (with browse buttons)/new— Start a new session/history— Show recent session history
Send any other text to talk directly to Claude.
When Claude requests approval to use a tool (run a command, edit a file, etc.), the bot sends an interactive Allow/Deny prompt to your chat. Tapping a button sends the response back to Claude and processing continues automatically.
Store channel credentials in ~/.claudy/secrets.env (see Provider credentials for full format):
TELEGRAM_BOT_TOKEN=...
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
DISCORD_BOT_TOKEN=...
DISCORD_APPLICATION_ID=...
DISCORD_PUBLIC_KEY=...Run claudy mcp to start a stdio-based MCP server that lets Claude Code delegate tasks to other locally installed AI coding agents.
claudy mcp run # Start the MCP server (called by Claude Code)
claudy mcp install # Register claudy as an MCP server in Claude Code settings
claudy mcp uninstall # Remove claudy from Claude Code MCP settingsclaudy mcp install automatically registers itself in ~/.claude/settings.json. When you create a mode with claudy mode create <name>, it also registers in the mode's settings file. No manual configuration needed.
To register manually (or in a project-level .claude/settings.json):
{
"mcpServers": {
"claudy": {
"command": "claudy",
"args": ["mcp"]
}
}
}Claude Code will see an ask_agent tool that exposes all installed agents.
Once registered, Claude Code can delegate tasks like this:
> Ask codex to write unit tests for the parser module
> Ask aider to refactor the database layer
Claude Code selects the appropriate agent, passes the prompt, and returns the result. You can also specify a working directory:
{ "agent": "codex", "prompt": "Explain this module", "working_directory": "/path/to/project" }# Check if claudy is registered
cat ~/.claude/settings.json | grep -A3 claudy
# Test the MCP server manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | claudy mcp run| Agent | Binary | Headless command |
|---|---|---|
| Codex CLI | codex |
codex exec "..." |
| Cursor Agent | agent |
agent -p "..." --output-format text |
| Antigravity | agy |
agy -p "..." |
| GitHub Copilot | copilot |
copilot -p "..." |
| OpenCode | opencode |
opencode run "..." |
| Cline | cline |
cline -y "..." |
| Aider | aider |
aider --message "..." |
| Goose | goose |
goose run "..." |
| Amp | amp |
amp --non-interactive "..." |
| Droid | droid |
droid exec "..." |
| Kiro | kiro-cli |
kiro-cli chat --no-interactive --trust-all-tools "..." |
| Junie | junie |
junie "..." |
| Kimi Code | kimi |
kimi "..." |
| Mistral Vibe | vibe |
vibe "..." |
| Qwen Code | qwen-code |
qwen-code "..." |
| Crush | crush |
crush "..." |
| Groq Code | groq-code |
groq-code --prompt "..." |
| Plandex | plandex |
plandex tell "..." |
| Kilo Code | kilo |
kilo "..." |
| OpenHands | openhands |
openhands "..." |
Add agents in ~/.claudy/config.yaml under the agents key (see Configuration for full schema):
agents:
my-agent:
binary: "my-agent"
args: ["--prompt", "{prompt}", "--no-interactive"]
description: "My custom agent"
timeout: 180Same key as a built-in agent overrides its defaults. {prompt} in args is replaced with the actual task.
Note: The analytics feature is still a work in progress. Token counts, cost estimates, and other metrics may not be fully accurate. Expect refinements in upcoming releases.
claudy analytics dashboard # Open local analytics dashboard (Tauri 2)
claudy analytics ingest # Ingest session data from ~/.claude/projects/
claudy analytics ingest --full # Re-ingest all files (ignore checkpoints)
claudy analytics ingest --project my-project # Ingest specific project
claudy analytics recommend # Show usage recommendations in CLI
claudy analytics export # Export analytics data (JSON, default 30 days)
claudy analytics export --format csv --days 7 # Export as CSV for last 7 days
claudy analytics sync-pricing # Sync model pricing from models.dev and Anthropic pricing page
claudy analytics recalculate # Recalculate all costs using the latest pricing data
claudy analytics insights # Generate compact JSON insights summary (default: 7 days)
claudy analytics insights --days 14 # Analyze last 14 days
claudy analytics insights --from 2026-04-01 --to 2026-04-30 # Specific date range
claudy analytics insights --project my-project # Filter by projectThe fastest way to analyze your usage is directly inside Claude Code. The analytics-insights skill is automatically available — just ask naturally:
> /analytics-insights
> /analytics-insights last 2 weeks
> analyze my usage patterns
> 사용 패턴 분석해줘
Claude runs claudy analytics insights, analyzes the JSON, and returns a structured report with:
- Cost trends — daily/weekly spend with spike detection
- Model distribution — which models you use and what they cost per session
- Tool patterns — most-used tools, error rates, efficiency observations
- Cache performance — hit ratio and estimated savings
- Actionable recommendations — specific suggestions like "route simple tasks to turbo" with estimated dollar savings
Example output (see docs/examples/analytics-insights-sample.json for raw data):
#### Summary
81 sessions, $481 total spend at an average of $68.7/day. Costs trending
sharply upward — last 3 weekdays averaged $97/day.
#### Recommendations
1. Route simple tasks to glm-5-turbo — est. savings: ~$90/month
2. Investigate $1.91/turn outlier session (6x average cost-per-turn)
3. Reduce harness overhead — TaskCreate/Update accounted for ~1,000 calls
No manual commands, no context switching. Ask Claude about your usage and get answers instantly.
- Tokens: Detailed trends of input, output, and cache tokens over the last 30 days, grouped by model and date.
- Tools: Distribution analysis showing which tools Claude uses most frequently, including call counts, error rates, and average execution time.
- Cost: Real-time estimation of usage costs based on actual token pricing, including daily/weekly/monthly forecasts and trend detection (increasing/stable/decreasing).
- Tips (Recommendations): Data-driven optimization advice, such as detecting high-cost sessions, suggesting Haiku for simple tasks, and identifying long conversations that could benefit from context summarization.
- Projects: Automatically maps cryptic session UUIDs to human-readable project folder names for better context.
Data is stored in a local SQLite database under ~/.claudy/analytics/. The dashboard runs as a high-performance local Tauri 2 + Svelte app. Use the [Sync] button in the dashboard to instantly refresh data from your Claude CLI history.
claudy analytics dashboard
When you work in a session started with a non-Anthropic provider (such as Z.AI / GLM), the Claude CLI records thinking blocks in the session file with an empty signature. The Anthropic API validates these signatures and rejects them with HTTP 400 when the session is resumed:
API Error: 400 Invalid `signature` in `thinking` block
Claudy handles this in two ways:
Automatic (channel bridge): When the channel server resumes a session, it silently converts any thinking blocks with empty signatures to plain text blocks before spawning the Claude process. No action required.
Manual (CLI): Use claudy session sanitize to repair sessions before resuming with claude --resume:
# Interactive — list flagged sessions, pick one
claudy session sanitize
# Filter by project name
claudy session sanitize --project book-forge
# Sanitize all flagged sessions at once
claudy session sanitize --all --yesOutput example:
Sessions with invalid thinking blocks
──────────────────────────────────────────────────────────────────────────────────
# Project Session ID Age Last message Blocks
──────────────────────────────────────────────────────────────────────────────────
1 book-forge ad2f38c0 2d oss-dist 스킬로 book-forge 프로젝트… 7
2 obsidian-forge 17e75a8c 5d LaunchAgent 설정 구현… 12
──────────────────────────────────────────────────────────────────────────────────
Select session to sanitize (or "Sanitize ALL"):
What the conversion does: thinking blocks with empty signatures are rewritten as plain text blocks, preserving the reasoning content as readable context. The session file is updated atomically. Sessions with valid Anthropic signatures are not touched.
Limitation: session continuity requires the conversation history to be compatible. Switching provider mid-session may cause subtle context shifts even after sanitization.
By default, Claudy stores data under:
~/.claudy/
Important files/directories:
config.yaml: provider + channel + agent configuration.secrets.env: provider/bot credentials.launchers.json: launcher/symlink manifest.modes/: Claude config modes.session-patches/: session patch storage.channel/: channel runtime state (pid, sessions, audit log).analytics/: analytics SQLite database and checkpoints.cache/update.json: update metadata cache.
CLAUDY_HOME: override the Claudy home directory (default:~/.claudy).CLAUDE_CONFIG_DIR: set automatically by Claudy when launching with a mode.
claudy setup
claudy <profile>claudy mode create work
claudy <profile> work --yolo
--yolois claudy's shorthand for--dangerously-skip-permissions.
Frameworks like gstack, superpowers, ecc, or our epic-harness ship their own CLAUDE.md, skills, and agents. Keep them isolated:
# One-time setup: create the mode and seed it with the framework config
claudy mode create gstack
cp -r /path/to/gstack/.claude/. ~/.claudy/modes/gstack/
# Daily use: launch Claude with the framework active
claudy <profile> gstackSwitch between frameworks without touching your default config:
claudy <profile> gstack # gstack framework active
claudy <profile> superpowers # superpowers framework active
claudy <profile> # your default config, unchanged# 1) Ensure MCP is registered (happens automatically on first `claudy mcp`)
claudy mcp
# 2) In Claude Code, ask it to delegate to any installed agent:
# "Ask codex to analyze this error"
# "Ask aider to refactor the auth module"claudy doctor
claudy pingprofile not recognized: runclaudy lsand choose a listed profile ID.not configuredprofile: runclaudy setup <provider>to add credentials.- Channel status unhealthy: run
claudy channel status, then restart withclaudy channel stopandclaudy channel start. - Channel bot not responding: check
~/.claudy/channel/logs/server.logfor errors. Verify bot token in~/.claudy/secrets.envand thatallowed_usersincludes your chat user ID. - Permission prompt not appearing: ensure Claude CLI is not running with
--dangerously-skip-permissions. The prompt only triggers when Claude needs explicit approval for tool use. - Binary not found after install: see the PATH note in the Verify section.
- Agent not showing in MCP: ensure the agent binary is on
PATH(e.g.which codex). Only installed agents appear intools/list. - Agent timeout: increase timeout in
config.yamlagents field (default: 120s). - MCP not registered: run
claudy mcponce manually, or check~/.claude/settings.jsonfor themcpServers.claudyentry. - Agent output truncated: agent stdout is capped at 10MB. For large outputs, redirect the agent to write to a file instead.
- Analytics data missing: run
claudy analytics ingestto populate from~/.claude/projects/. Use--fullto re-ingest everything. 400 Invalid signature in thinking blockwhen resuming: the session was created with a non-Anthropic provider (e.g. Z.AI). Runclaudy session sanitizeto convert the invalid thinking blocks, then resume normally.
cargo build
cargo test
cargo fmt
cargo clippy -- -D warnings
# Test analytics backend (uses local DB)
cargo run --example test_dashboard --features analytics-ui
# Launch analytics dashboard (requires analytics-ui feature)
cargo run --features analytics-ui -- analytics dashboardContributions are welcome! Here is how to get started:
- Fork the repository and create a feature branch.
- Make your changes with tests where appropriate.
- Run
cargo test && cargo clippy -- -D warningsbefore submitting. - Open a Pull Request at https://github.com/epicsagas/claudy.
Bug reports and feature requests are welcome via GitHub Issues.
This project was inspired by Clother, a Go-based multi-provider launcher for Claude CLI. Claudy is an independent Rust implementation, redesigned from the ground up with RAII-based session guards, signal forwarding, launcher symlinks, and deep ecosystem integrations including a full-featured Channel Bridge (Telegram/Slack/Discord), the Agent MCP Bridge for cross-agent delegation, and a high-performance Analytics Dashboard built with Tauri 2. These additions reflect Claudy's transition from a simple launcher to a comprehensive operational toolkit for Claude CLI users.
