kairo

README

Kairo

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

Kairo is a Go port of clauver, rewritten from Bash to provide:

• Cross-platform single binary - Works on Linux, macOS, and Windows
• Enhanced security - Type-safe Go implementation with comprehensive validation
• Easier maintenance - Go modules, structured testing, and standardized code organization

Overview

Feature	Description
Multi-Provider	Switch between Native Anthropic, Z.AI, MiniMax, Kimi, DeepSeek, custom
Secure Encryption	All API keys encrypted with age (X25519) encryption
Key Rotation	Periodically rotate encryption keys for enhanced security
Interactive Setup	Guided configuration wizard
Provider Testing	Test connectivity and configuration
Auto-Update	Notifies when new version available

Quick Start

# Install
curl -sSL https://raw.githubusercontent.com/dkmnx/kairo/main/scripts/install.sh | sh

# Setup
kairo setup

# List providers
kairo list

# Test provider
kairo test zai

# Switch and use Claude
kairo switch zai "Help me write a function"

# Passing arguments directly
kairo -- --continue

# Rotate encryption key (security best practice)
kairo rotate

# Update to latest version
kairo update

Commands

Command	Description
kairo setup	Interactive setup wizard
kairo config <provider>	Configure provider
kairo list	List configured providers
kairo status	Test all providers
kairo test <provider>	Test specific provider
kairo switch <provider>	Switch and exec Claude
kairo default [provider]	Get/set default provider
kairo reset <provider/all>	Remove provider config
kairo rotate	Rotate encryption key
kairo -- "query"	Query mode (default provider)
kairo version	Show version + check for updates
kairo update	Check for and update to latest

Supported Providers

Provider	API Key Required
Native Anthropic	No
Z.AI	Yes
MiniMax	Yes
Kimi (Moonshot)	Yes
DeepSeek	Yes
Custom	Yes

Modules

Package	Purpose	Documentation
cmd/	CLI commands (Cobra)	cmd/README.md
internal/config/	Configuration loading	internal/README.md
internal/crypto/	Age encryption	internal/README.md
internal/providers/	Provider registry	internal/README.md
internal/validate/	Input validation	internal/README.md
pkg/env/	Environment utilities	pkg/README.md

Documentation

• User Guide: docs/guides/user-guide.md
• Development Guide: docs/guides/development-guide.md
• Architecture: docs/architecture/README.md
• Troubleshooting: docs/troubleshooting/README.md
• Contributing: docs/contributing/README.md

Configuration

Location: ~/.config/kairo/

File	Purpose	Permissions
config	Provider configurations (YAML)	0600
secrets.age	Encrypted API keys	0600
age.key	Encryption private key	0600

Building

make build    # Build to dist/kairo
make test     # Run tests with race detection
make lint     # Run code quality checks
make install  # Install to ~/.local/bin

Security

• Age (X25519) encryption for all API keys
• 0600 permissions on sensitive files
• Secrets decrypted in-memory only
• Keys generated on first run (backup recommended)
• Key rotation - use kairo rotate to periodically regenerate encryption key

License

MIT (c) 2025 dkmnx

Resources

• GitHub Repository
• Report Issues
• Changelog