kairo

README

Kairo

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

Secure CLI for managing Claude Code API providers with age (X25519) encryption, multi-provider support, and audit logging.

Prerequisites

Required: Claude Code CLI

Kairo acts as a wrapper around Claude Code CLI to enable multi-provider support. You need to install Claude Code first.

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
  

Verify installation:

claude --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-Provider	Native Anthropic, Z.AI, MiniMax, Kimi, DeepSeek, custom
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|all>	Remove provider config

Execution

Command	Description
kairo switch <provider>	Switch and exec Claude
kairo <provider> [args]	Shorthand for switch
kairo -- "query"	Query mode (default provider)

Maintenance

Command	Description
kairo rotate	Rotate encryption key
kairo audit <list|export>	View/export audit logs
kairo update	Check for updates
kairo completion <shell>	Shell completion
kairo version	Show version info

Full Command Reference

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
Command Reference	CLI command details
Internal Packages	Core modules reference
Troubleshooting	Common issues and solutions
Changelog	Version history

Building

# Build
task build        # or: go build -o dist/kairo .

# Test
task test         # or: go test -race ./...

# Lint
task lint         # or: gofmt -w . && go vet ./...

# Format
task format       # or: gofmt -w .

Security

• Age (X25519) encryption for all API keys
• 0600 permissions on sensitive files
• Secrets decrypted in-memory only
• 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