<h1 align="center">claudy</h1>
<p align="center"><b>One command. Any provider. Full control over Claude CLI.</b></p>
<p align="center">
Stop juggling environment variables and config files.<br/>
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.
</p>
<p align="center">
<b>Multi-provider · Config isolation · Channel bridge · Local agent bridge · Usage analytics</b>
</p>
---
<p align="center">
<a href="docs/i18n/README.ko.md">🇰🇷 한국어</a> •
<a href="docs/i18n/README.zh-Hans.md">🇨🇳 中文</a> •
<a href="docs/i18n/README.ja.md">🇯🇵 日本語</a> •
<a href="docs/i18n/README.de.md">🇩🇪 Deutsch</a> •
<a href="docs/i18n/README.fr.md">🇫🇷 Français</a> •
<a href="docs/i18n/README.es.md">🇪🇸 Español</a> •
<a href="docs/i18n/README.hi.md">🇮🇳 हिन्दी</a> •
<a href="docs/i18n/README.pt-BR.md">🇧🇷 Português</a> •
<a href="docs/i18n/README.id.md">🇮🇩 Bahasa</a> •
<a href="docs/i18n/README.ar.md">🇸🇦 العربية</a>
</p>
<p align="center">
<a href="https://github.com/epicsagas/claudy/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/epicsagas/claudy?style=for-the-badge&labelColor=0d1117&color=ffd700&logo=github&logoColor=white" /></a>
<a href="https://github.com/epicsagas/claudy/network/members"><img alt="Forks" src="https://img.shields.io/github/forks/epicsagas/claudy?style=for-the-badge&labelColor=0d1117&color=2ecc71&logo=github&logoColor=white" /></a>
<a href="https://github.com/epicsagas/claudy/issues"><img alt="Issues" src="https://img.shields.io/github/issues/epicsagas/claudy?style=for-the-badge&labelColor=0d1117&color=ff6b6b&logo=github&logoColor=white" /></a>
<a href="https://github.com/epicsagas/claudy/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/epicsagas/claudy?style=for-the-badge&labelColor=0d1117&color=58a6ff&logo=git&logoColor=white" /></a>
</p>
<p align="center">
<a href="https://crates.io/crates/claudy"><img alt="Crates.io" src="https://img.shields.io/crates/v/claudy?style=for-the-badge&labelColor=0d1117&color=fc8d62&logo=rust&logoColor=white" /></a>
<a href="https://crates.io/crates/claudy"><img alt="Downloads" src="https://img.shields.io/crates/d/claudy?style=for-the-badge&labelColor=0d1117&color=3498db&logo=rust&logoColor=white" /></a>
<a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-3fb950?style=for-the-badge&labelColor=0d1117" /></a>
<img alt="Rust" src="https://img.shields.io/badge/rust-1.92+-d73a49?style=for-the-badge&labelColor=0d1117&logo=rust&logoColor=white" />
<a href="https://github.com/epicsagas/claudy/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/epicsagas/claudy/ci.yml?style=for-the-badge&labelColor=0d1117&color=e67e22&logo=githubactions&logoColor=white" /></a>
<a href="https://buymeacoffee.com/epicsaga"><img alt="Buy Me a Coffee" src="https://img.shields.io/badge/buy_me_a_coffee-FFDD00?style=for-the-badge&labelColor=0d1117&logo=buymeacoffee&logoColor=black" /></a>
</p>
---
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/features-2048.png">
<img alt="Why Claudy" src="docs/assets/features-2048.png" width="100%">
</picture>
## Why Claudy
| | 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 Gemini, 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 |
## Supported Providers
> Claudy was inspired by [Clother](https://github.com/jolehuit/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](https://github.com/epicsagas/claudy/issues).
| Provider | Status | Notes |
|---|---|---|
| Built-in (Anthropic) | ✅ Tested | Default |
| Z.AI | ✅ Tested | |
| OpenRouter alias | ⚠️ Experimental | Not fully tested — report issues on GitHub |
| Ollama | ⚠️ Experimental | Not fully tested — report issues on GitHub |
| Custom endpoint | ⚠️ Experimental | Not fully tested — report issues on GitHub |
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/demo.gif">
<img alt="demo" src="docs/assets/demo.gif" width="100%">
</picture>
## Quick Start
**1. Install**
macOS / Linux:
```bash
brew install epicsagas/tap/claudy
```
No Homebrew? Use the installer script:
```bash
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/epicsagas/claudy/releases/latest/download/install.sh | sh
```
Windows:
```powershell
irm https://github.com/epicsagas/claudy/releases/latest/download/install.ps1 | iex
```
Via Rust toolchain:
```bash
cargo binstall claudy # pre-built binary (fast)
cargo install claudy # build from source
```
**2. Configure**
```bash
claudy install # initialize dirs, config, secrets
echo 'ANTHROPIC_API_KEY=your-key' >> ~/.claudy/secrets.env
```
**3. Launch**
```bash
claudy # default provider
claudy zai # Z.AI provider
claudy openrouter sonnet # OpenRouter alias
```
**4. Update**
```bash
brew upgrade claudy # Homebrew
claudy update # built-in updater
# or re-run the installer script / cargo binstall claudy@latest
claudy --version
```
<details>
<summary>Provider credentials</summary>
| 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.
</details>
<details>
<summary>config.yaml schema</summary>
All configuration lives in `~/.claudy/config.yaml`. Only add the sections you need — defaults are used for anything omitted.
```yaml
# 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
```
</details>
---
## 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:
```bash
claudy <profile> <mode> [args...]
```
Claudy sets:
```bash
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](https://github.com/garrytan/gstack), [superpowers](https://github.com/obra/superpowers), [ecc](https://github.com/affaan-m/everything-claude-code), or any custom harness. Instead of polluting your default config, isolate each framework in its own mode:
```bash
# 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.
<details>
<summary>Command Reference</summary>
## 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
```bash
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)
```bash
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
| 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 |
#### 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](#provider-credentials-secretsenv) for full format):
```env
TELEGRAM_BOT_TOKEN=...
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
DISCORD_BOT_TOKEN=...
DISCORD_APPLICATION_ID=...
DISCORD_PUBLIC_KEY=...
```
</details>
## 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.
```bash
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`):
```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:
```json
{ "agent": "gemini", "prompt": "Explain this module", "working_directory": "/path/to/project" }
```
### Verify MCP registration
```bash
# 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)
| Agent | Binary | Headless command |
|-------|--------|-----------------|
| Gemini CLI | `gemini` | `gemini -p "..." --output-format text` |
| Codex CLI | `codex` | `codex exec "..."` |
| Cursor Agent | `agent` | `agent -p "..." --output-format text` |
| 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 "..."` |
### Custom agents
Add agents in `~/.claudy/config.yaml` under the `agents` key (see [Configuration](#configyaml-schema) for full schema):
```yaml
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.
```bash
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`](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
```bash
claudy analytics dashboard
```
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/analytics-dashboard.png">
<img alt="Analytics Dashboard" src="docs/assets/analytics-dashboard.png" width="100%">
</picture>
---
## 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`:
```bash
# 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:
```text
~/.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
```bash
claudy setup
claudy <profile>
```
### Use a mode with a provider
```bash
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:
```bash
# 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:
```bash
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
```bash
# 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
```bash
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](#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
```bash
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](https://github.com/epicsagas/claudy/issues).
## Acknowledgements
This project was inspired by [Clother](https://github.com/jolehuit/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](LICENSE)