OpenKoi

A self-iterating AI agent system. Single binary, local-first, model-agnostic.

OpenKoi follows a Plan-Execute-Evaluate-Refine cycle — iterating on its own output until results meet your quality standards. It ships as a single static binary with zero runtime dependencies.

Quick Start

# Install via Cargo
cargo install openkoi

# Or use the shell installer
curl -fsSL https://openkoi.ai/install.sh | sh

openkoi "Refactor the auth module to use JWT tokens"

OpenKoi detects your API keys from the environment, picks the best available model, and starts working. No config file needed.

Features

• Self-iteration — Plan, execute, evaluate, refine. The agent is its own reviewer.
• 6 providers — Anthropic, OpenAI, Google, Ollama, AWS Bedrock, any OpenAI-compatible endpoint.
• Role-based models — Assign different models to executor, evaluator, planner, and embedder roles.
• Persistent memory — SQLite + vector search. Learnings persist across sessions.
• Pattern mining — Observes your usage, proposes new skills to automate recurring workflows.
• Skill system — OpenClaw-compatible .SKILL.md format. Write once, use with any provider.
• 3-tier plugins — MCP (external tools), WASM (sandboxed), Rhai (scripting).
• 10 integrations — Slack, Discord, MS Teams, GitHub, Jira, Linear, Notion, Google Docs, Telegram, Email.
• TUI dashboard — Real-time view of tasks, costs, learnings, plugins, and config.
• Soul system — Optional personality that evolves with your interaction patterns.

CLI

openkoi "task"              # Run a task (default 3 iterations)
openkoi chat                # Interactive REPL
openkoi learn               # Review proposed skills
openkoi status              # Show costs, memory, active models
openkoi doctor              # Run diagnostics
openkoi connect copilot     # Login to GitHub Copilot
openkoi connect chatgpt     # Login to ChatGPT Plus/Pro
openkoi connect slack       # Connect an integration
openkoi disconnect copilot  # Remove stored credentials
openkoi export all          # Export data as JSON/YAML
openkoi update              # Self-update

Providers

Subscription-based (OAuth login, free with your existing plan)

Use openkoi connect to authenticate via device-code flow. No API key needed.

Tokens are stored in ~/.openkoi/auth.json and refreshed automatically.

API key providers

Set an environment variable or paste a key when prompted during openkoi init.

API keys are saved to ~/.openkoi/credentials/<provider>.key (owner-only permissions).

Local

Credential Discovery

OpenKoi auto-discovers credentials in this order:

1. Environment variables — ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, etc.
2. OAuth store — GitHub Copilot, ChatGPT tokens from openkoi connect
3. External CLIs — Claude CLI (~/.claude/.credentials.json), Qwen CLI
4. macOS Keychain — Claude Code credentials (macOS only)
5. Saved credentials — ~/.openkoi/credentials/*.key
6. Local probes — Ollama at localhost:11434

Connect and Disconnect

# Login to a subscription provider
openkoi connect copilot     # GitHub Copilot
openkoi connect chatgpt     # ChatGPT Plus/Pro

# Remove stored credentials
openkoi disconnect copilot
openkoi disconnect chatgpt
openkoi disconnect anthropic   # Remove saved API key
openkoi disconnect all         # Remove all OAuth tokens

# Show connection status
openkoi connect status

Architecture

              ┌─────────────────┐
              │   Orchestrator   │
              └────────┬────────┘
       ┌───────┬───────┼───────┬──────────┐
       ▼       ▼       ▼       ▼          ▼
   Executor Evaluator Learner Pattern   Integrations
       │                     Miner
       ▼
     Tools (MCP / WASM / Rhai)

Supported platforms: Linux (x86_64, ARM64) and macOS (Intel, Apple Silicon). Built with Rust + Tokio. < 10ms startup, ~5MB idle memory, ~20MB binary.

Skills

Skills are markdown files (SKILL.md) with YAML frontmatter that teach OpenKoi how to handle specific tasks. They use the same format as OpenClaw, so skills are portable between tools.

How skills work

OpenKoi loads skills from multiple sources in precedence order:

When you run a task, the skill selector ranks eligible skills by semantic similarity and historical effectiveness, then injects the most relevant ones into the prompt. You don't need to specify which skill to use — OpenKoi picks automatically.

Bundled skills

These ship with the binary and are always available:

Writing a custom skill

Create a directory with a SKILL.md file:

mkdir -p .agents/skills/my-skill

---
name: my-skill
description: Enforces our team's API conventions.
metadata:
  categories: ["api", "code"]
---

# My Skill

When building API endpoints for this project:

- Use snake_case for all field names
- Return 404 with `{"error": "not_found"}` for missing resources
- Always include `X-Request-Id` header in responses
- Validate all path parameters before database queries

Place it in .agents/skills/ for project-specific skills, or ~/.openkoi/skills/user/ for global skills. OpenKoi picks it up automatically on the next run.

Example: self-iterate

The self-iterate skill is how OpenKoi works on its own codebase. When a task targets the OpenKoi source tree, the skill selector activates it automatically based on category matching (self-improvement, rust, code, refactor).

It enforces architectural invariants that must never be violated:

• Single binary — everything embeds via include_str!, no runtime file dependencies
• Zero-dependency crypto — SHA-256 and base64 are hand-rolled, only getrandom for CSPRNG
• Provider parity — all providers implement the same ModelProvider trait
• Iteration safety — circuit breakers (token budget, time budget, max iterations) cannot be weakened
• Atomic writes — all credential/config files use write-to-temp-then-rename

It also defines hard boundaries on recursive self-improvement: OpenKoi can improve its own skills, providers, and memory system, but cannot disable its own safety circuit breakers or bypass evaluation.

Evaluator skills

Evaluator skills define how OpenKoi judges its own output. They specify scoring dimensions and rubrics:

---
name: my-evaluator
kind: evaluator
description: Evaluates database migrations for safety.
metadata:
  categories: ["database", "migration"]
  dimensions:
    - { name: reversibility, weight: 0.4 }
    - { name: data_safety, weight: 0.35 }
    - { name: performance, weight: 0.25 }
---

# Database Migration Evaluator

## Reversibility (40%)
- Is there a matching down migration?
- Can the migration be rolled back without data loss?
...

Place evaluator skills in .agents/evaluators/ (project) or ~/.openkoi/evaluators/user/ (global).

Managing skills

openkoi learn               # Review pattern-proposed skills
openkoi learn --install     # Install a managed skill
openkoi status              # See active skills and effectiveness scores

OpenKoi's pattern miner watches your usage and proposes new skills when it detects recurring workflows. Run openkoi learn to review and approve them.

Documentation

Full documentation at openkoi.ai.

License

MIT