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

• Multi-Provider Support: Switch between Native Anthropic, Z.AI, MiniMax, Kimi, DeepSeek, and custom providers
• Secure Encryption: All API keys encrypted with age (X25519) encryption
• Interactive Setup: Guided configuration wizard
• Provider Testing: Test connectivity and configuration
• Auto-Update Notifications: 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 switch zai -- --continue

# 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 "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)

License

MIT (c) 2025 dkmnx

Resources

• GitHub Repository
• Report Issues
• Changelog