https://github.com/dkmnx/kairo
Go port of clauver - A secure CLI tool for managing and switching between Claude Code API providers including Anthropic, Z.AI, MiniMax, and custom providers with age (X25519) encryption.
https://github.com/dkmnx/kairo
agentic-coding anthropic claude claude-code clauver cli deepseek deepseek-v3-2 glm-4-7 kimi kimi-k2 minimax minimax-m2-1 zai
Last synced: 22 days ago
JSON representation
Go port of clauver - A secure CLI tool for managing and switching between Claude Code API providers including Anthropic, Z.AI, MiniMax, and custom providers with age (X25519) encryption.
- Host: GitHub
- URL: https://github.com/dkmnx/kairo
- Owner: dkmnx
- License: mit
- Created: 2025-12-25T11:42:52.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-02-09T15:09:05.000Z (about 1 month ago)
- Last Synced: 2026-02-09T19:56:30.529Z (about 1 month ago)
- Topics: agentic-coding, anthropic, claude, claude-code, clauver, cli, deepseek, deepseek-v3-2, glm-4-7, kimi, kimi-k2, minimax, minimax-m2-1, zai
- Language: Go
- Homepage:
- Size: 511 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing/README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Kairo
```text
█████ ███
░░███ ░░░
░███ █████ ██████ ████ ████████ ██████
░███░░███ ░░░░░███ ░░███ ░░███░░███ ███░░███
░██████░ ███████ ░███ ░███ ░░░ ░███ ░███
░███░░███ ███░░███ ░███ ░███ ░███ ░███
████ █████░░████████ █████ █████ ░░██████
░░░░░ ░░░░░ ░░░░░░░░ ░░░░░ ░░░░░ ░░░░░░
```
[](https://github.com/dkmnx/kairo/releases)
[](https://go.dev/dl/)
[](https://github.com/dkmnx/kairo/actions)
[](LICENSE)
**Anthropic-powered CLI for multi-provider management with X25519 encryption and integrated audit trails.**
## Prerequisites
### Required: Claude Code CLI or Qwen Code CLI
Kairo acts as a wrapper around Claude Code or Qwen Code CLI to enable multi-provider support. You need to install at least one of them.
**Install Claude Code:**
- Visit:
- Or via package managers:
```bash
# Homebrew (macOS)
brew install --cask claude-code
# npm
npm install -g @anthropic-ai/claude-code
```
**Install Qwen Code:**
- Visit:
- Or via package managers:
```bash
# npm
npm install -g @qwen-code/qwen-code@latest
```
**Configure Qwen Code:**
Qwen Code requires model providers to be configured in `~/.qwen/settings.json`. Create this file with your providers:
> Note: Only Anthropic API providers are supported.
```json
{
"modelProviders": {
"anthropic": [
{
"id": "glm-4.7",
"name": "GLM-4.7 [Z.AI Coding Plan] - Anthropic",
"envKey": "ANTHROPIC_API_KEY",
"baseUrl": "https://api.z.ai/api/anthropic"
}
]
}
}
```
Kairo automatically sets `ANTHROPIC_API_KEY` when using the Qwen harness.
**Verify installation:**
```bash
claude --version
# or
qwen --version
```
## Quick Start
### Install
| Platform | Command |
| ------------- | ----------------------------------------------------------------------------------------- |
| Linux/macOS | `curl -sSL https://raw.githubusercontent.com/dkmnx/kairo/main/scripts/install.sh \| sh` |
| Windows | `irm https://raw.githubusercontent.com/dkmnx/kairo/main/scripts/install.ps1 \| iex` |
[Manual Installation](docs/guides/user-guide.md#manual-installation) | [Build from Source](docs/guides/development-guide.md#building)
### Setup
```bash
# Interactive setup
kairo setup
# Configure a provider
kairo config zai
# Test provider
kairo test zai
# Switch and query
kairo switch zai "Help me write a function"
# Or use default provider
kairo -- "Quick question"
```
## System Architecture
```mermaid
flowchart TB
subgraph User[User]
CLI[kairo CLI]
end
subgraph Kairo
Config[config/] --> Providers[providers/]
Config --> Crypto[crypto/]
Config --> Audit[audit/]
Crypto --> Age[age X25519]
Audit --> Log[audit.log]
end
subgraph Storage[~/.config/kairo/]
YAML[config.yaml]
AGE[secrets.age]
KEY[age.key]
LOG[audit.log]
end
CLI --> Config
CLI --> Providers
CLI --> Crypto
CLI --> Audit
Crypto --> AGE
Crypto --> KEY
Age --> KEY
```
## Features
| Feature | Description |
| ---------------------- | ---------------------------------------- |
| **Multi-Harness** | Claude Code (default), Qwen Code |
| **Secure Encryption** | Age (X25519) encryption for all API keys |
| **Key Rotation** | Regenerate encryption keys periodically |
| **Audit Logging** | Track all configuration changes |
| **Cross-Platform** | Linux, macOS, Windows support |
## Metrics
Performance metrics are opt-in for privacy. When enabled, kairo tracks:
- API call durations per provider
- Configuration operation timing
- Success/failure rates
### Enabling Metrics
```bash
# Enable for current session
kairo metrics enable
# Or set environment variable
export KAIRO_METRICS_ENABLED=true
```
### Viewing Metrics
```bash
# Display metrics in terminal
kairo metrics
# Export to JSON file
kairo metrics --output metrics.json
# Reset all metrics
kairo metrics reset
```
### Metrics Reference
| Metric | Description |
| ----------------- | ------------------------------------------ |
| `operation` | Type of operation (switch, config, etc.) |
| `provider` | Provider name |
| `count` | Number of operations |
| `total_duration` | Cumulative time spent |
| `avg_duration` | Average operation time |
| `min_duration` | Fastest operation |
| `max_duration` | Slowest operation |
| `failure_count` | Number of failures |
## Commands
### Provider Management
| Command | Description |
| -------------------------------- | ------------------------------------ |
| `kairo setup` | Interactive setup wizard |
| `kairo config ` | Configure a provider |
| `kairo list` | List configured providers |
| `kairo status` | Test all providers |
| `kairo test ` | Test specific provider |
| `kairo default ` | Get/set default provider |
| `kairo reset ` | Remove provider config |
| `kairo reset all` | Remove all provider configs |
### Execution
| Command | Description |
| ----------------------------------------- | ------------------------------------ |
| `kairo switch ` | Switch and exec CLI (claude or qwen) |
| `kairo switch --harness qwen` | Switch using Qwen CLI |
| `kairo harness get` | Get current default harness |
| `kairo harness set ` | Set default harness (claude or qwen) |
| `kairo [args]` | Shorthand for switch |
| `kairo -- "query"` | Query mode (default provider) |
### Maintenance
| Command | Description |
| ------------------------------- | ---------------------------------- |
| `kairo rotate` | Rotate encryption key |
| `kairo backup` | Create backup of configuration |
| `kairo restore ` | Restore from backup |
| `kairo recover` | Generate/restore recovery phrase |
| `kairo audit` | View/export audit logs |
| `kairo metrics` | View performance metrics |
| `kairo update` | Check for updates |
| `kairo completion ` | Shell completion |
| `kairo version` | Show version info |
## Configuration
| OS | Location |
| ---------- | -------------------------------------------- |
| Linux | `~/.config/kairo/` |
| macOS | `~/Library/Application Support/kairo/` |
| Windows | `%APPDATA%\kairo\` |
| File | Purpose | Permissions |
| ------------- | ---------------------------------- | ------------- |
| `config.yaml` | Provider configurations (YAML) | 0600 |
| `secrets.age` | Encrypted API keys | 0600 |
| `age.key` | Encryption private key | 0600 |
| `audit.log` | Configuration change history | 0600 |
## Documentation
### User Guides
| Guide | Description |
| --------------------------------------------------------------- | ---------------------------- |
| [User Guide](docs/guides/user-guide.md) | Installation and basic usage |
| [Audit Guide](docs/guides/audit-guide.md) | Audit log usage |
| [Advanced Configuration](docs/guides/advanced-configuration.md) | Complex scenarios |
### Developer Resources
| Resource | Description |
| --------------------------------------------------------------- | -------------------------------- |
| [Development Guide](docs/guides/development-guide.md) | Setup and contribution |
| [Architecture](docs/architecture/README.md) | System design and diagrams |
| [Wrapper Scripts](docs/architecture/wrapper-scripts.md) | Security design and rationale |
| [Contributing](docs/contributing/README.md) | Contribution workflow |
### Reference
| Resource | Description |
| --------------------------------------------------------------- | -------------------------------------- |
| [Development Guide](docs/guides/development-guide.md) | Setup and contribution |
| [Architecture](docs/architecture/README.md) | System design and diagrams |
| [Wrapper Scripts](docs/architecture/wrapper-scripts.md) | Security design and rationale |
| [Contributing](docs/contributing/README.md) | Contribution workflow |
| [Troubleshooting](docs/troubleshooting/README.md) | Common issues and solutions |
| [Changelog](CHANGELOG.md) | Version history |
## Building
```bash
# Build
just build # or: go build -o dist/kairo .
# Test
just test # or: go test -race ./...
# Lint
just lint # or: gofmt -w . && go vet ./...
# Format
just format # or: gofmt -w .
```
## Security
- Age (X25519) encryption for all API keys
- 0600 permissions on sensitive files
- Secrets decrypted in-memory only
- Secure wrapper scripts for both Claude and Qwen harnesses
- Key generation on first run
- Use `kairo rotate` for periodic key rotation
## Project Structure
```text
kairo/
├── cmd/ # CLI commands (Cobra)
│ ├── setup.go # Interactive wizard
│ ├── config.go # Provider configuration
│ ├── switch.go # Provider switching
│ └── ...
├── internal/ # Business logic
│ ├── audit/ # Audit logging
│ ├── config/ # YAML loading
│ ├── crypto/ # Age encryption
│ ├── providers/ # Provider registry
│ └── ...
└── pkg/ # Reusable utilities
└── env/ # Cross-platform config dir
```
## Resources
- [GitHub](https://github.com/dkmnx/kairo)
- [Report Issues](https://github.com/dkmnx/kairo/issues)
---
**License:** [MIT](LICENSE) | **Author:** [dkmnx](https://github.com/dkmnx)