kairo

README

Kairo

 █████                 ███
░░███                 ░░░
 ░███ █████  ██████   ████  ████████   ██████
 ░███░░███  ░░░░░███ ░░███ ░░███░░███ ███░░███
 ░██████░    ███████  ░███  ░███ ░░░ ░███ ░███
 ░███░░███  ███░░███  ░███  ░███     ░███ ░███
 ████ █████░░████████ █████ █████    ░░██████
░░░░░ ░░░░░  ░░░░░░░░ ░░░░░ ░░░░░     ░░░░░░

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: https://claude.com/product/claude-code

• Or via package managers:

  # Homebrew (macOS)
  brew install --cask claude-code
  
  # npm
  npm install -g @anthropic-ai/claude-code
  

Install Qwen Code:

• Visit: https://qwenlm.github.io/qwen-code-docs/

• Or via package managers:

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

{
  "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:

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 | Build from Source

Setup

# 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

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

# Enable for current session
kairo metrics enable

# Or set environment variable
export KAIRO_METRICS_ENABLED=true

Viewing Metrics

# 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 <provider>	Configure a provider
kairo list	List configured providers
kairo status	Test all providers
kairo test <provider>	Test specific provider
kairo default <provider>	Get/set default provider
kairo reset <provider>	Remove provider config
kairo reset all	Remove all provider configs

Execution

Command	Description
kairo switch <provider>	Switch and exec CLI (claude or qwen)
kairo switch <provider> --harness qwen	Switch using Qwen CLI
kairo harness get	Get current default harness
kairo harness set <harness>	Set default harness (claude or qwen)
kairo <provider> [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 <file>	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>	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	Installation and basic usage
Audit Guide	Audit log usage
Advanced Configuration	Complex scenarios

Developer Resources

Resource	Description
Development Guide	Setup and contribution
Architecture	System design and diagrams
Wrapper Scripts	Security design and rationale
Contributing	Contribution workflow

Reference

Resource	Description
Development Guide	Setup and contribution
Architecture	System design and diagrams
Wrapper Scripts	Security design and rationale
Contributing	Contribution workflow
Troubleshooting	Common issues and solutions
Changelog	Version history

Building

# 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

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
• Report Issues

---

License: MIT | Author: dkmnx