claudy 0.3.0

Why Claudy

Supported Providers

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.

Quick Start

1. Install

macOS / Linux:

brew install epicsagas/tap/claudy

No Homebrew? Use the installer script:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/epicsagas/claudy/releases/latest/download/install.sh | sh

Windows:

irm https://github.com/epicsagas/claudy/releases/latest/download/install.ps1 | iex

Via Rust toolchain:

cargo binstall claudy   # pre-built binary (fast)
cargo install claudy    # build from source

2. Configure

claudy install                        # initialize dirs, config, secrets
echo 'ANTHROPIC_API_KEY=your-key' >> ~/.claudy/secrets.env

3. Launch

claudy                                # default provider
claudy zai                            # Z.AI provider
claudy openrouter sonnet              # OpenRouter alias

4. Update

brew upgrade claudy          # Homebrew
claudy update                # built-in updater
# or re-run the installer script / cargo binstall claudy@latest
claudy --version

Custom providers use the api_key_env variable defined in their custom_providers entry.

All configuration lives in ~/.claudy/config.yaml. Only add the sections you need — defaults are used for anything omitted.

# 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: 300

Core Concepts

Profile

A launch target that resolves provider metadata + auth strategy (built-in provider, OpenRouter alias, or custom provider).

Mode

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, 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> gstack

Each mode directory is a self-contained CLAUDE_CONFIG_DIR, so frameworks never conflict with each other or with your default setup.

Command Reference

Main commands

• 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.

Mode commands

claudy mode create <name>
claudy mode ls
claudy mode remove <name>

Mode name rule: [a-z0-9][a-z0-9_-]* (mode is reserved).

Channel commands (optional bridge)

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 disable

channel add guides you through bot token, allowed users, profile, and mode mapping.

Supported platforms

Channel bot commands

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.

Permission prompts

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.

Secrets

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=...

Agent MCP bridge

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 settings

claudy 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.

Usage example

Once registered, Claude Code can delegate tasks like this:

> Ask gemini to review the error handling in src/api.rs
> 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": "gemini", "prompt": "Explain this module", "working_directory": "/path/to/project" }

Verify MCP registration

# 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

Supported agents (auto-detected from PATH)

Custom agents

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: 180

Same key as a built-in agent overrides its defaults. {prompt} in args is replaced with the actual task.

Usage Analytics

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 project

Inside Claude Code: /analytics-insights

The 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.

What analytics tracks

• 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.

Analytics Dashboard

claudy analytics dashboard

Cross-Provider Session Continuity

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 --yes

Output 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.

Files and Directory Layout

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.

Environment Variables

• CLAUDY_HOME: override the Claudy home directory (default: ~/.claudy).
• CLAUDE_CONFIG_DIR: set automatically by Claudy when launching with a mode.

Common Workflows

Configure and launch a provider

claudy setup
claudy <profile>

Use a mode with a provider

claudy mode create work
claudy <profile> work --yolo

--yolo is claudy's shorthand for --dangerously-skip-permissions.

Run a dedicated Claude framework in its own mode

Frameworks like gstack, superpowers, or ecc 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> gstack

Switch 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

Delegate tasks to other agents via MCP

# 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 gemini to analyze this error"
#    "Ask aider to refactor the auth module"

Diagnose install/configuration state

claudy doctor
claudy ping

Troubleshooting

• profile not recognized: run claudy ls and choose a listed profile ID.
• not configured profile: run claudy setup <provider> to add credentials.
• Channel status unhealthy: run claudy channel status, then restart with claudy channel stop and claudy channel start.
• Channel bot not responding: check ~/.claudy/channel/logs/server.log for errors. Verify bot token in ~/.claudy/secrets.env and that allowed_users includes 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 (which gemini). Only installed agents appear in tools/list.
• Agent timeout: increase timeout in config.yaml agents field (default: 120s).
• MCP not registered: run claudy mcp once manually, or check ~/.claude/settings.json for the mcpServers.claudy entry.
• 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 ingest to populate from ~/.claude/projects/. Use --full to re-ingest everything.
• 400 Invalid signature in thinking block when resuming: the session was created with a non-Anthropic provider (e.g. Z.AI). Run claudy session sanitize to convert the invalid thinking blocks, then resume normally.

Development

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 dashboard

Contributing

Contributions are welcome! Here is how to get started:

1. Fork the repository and create a feature branch.
2. Make your changes with tests where appropriate.
3. Run cargo test && cargo clippy -- -D warnings before submitting.
4. Open a Pull Request at https://github.com/epicsagas/claudy.

Bug reports and feature requests are welcome via GitHub Issues.

Acknowledgements

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.

License

Apache-2.0