# OpenKoi
[](https://github.com/openkoi-ai/openkoi/actions/workflows/ci.yml)
[](https://crates.io/crates/openkoi)
[](https://crates.io/crates/openkoi)
[](https://github.com/openkoi-ai/openkoi/releases)
[](LICENSE)
[](https://openkoi.ai)
**Executive Function as a Service.** Stop babysitting your AI. OpenKoi thinks before it acts, deliberates internally, and iterates until the code is right.
AI coding tools generate a first draft and leave you to fix it. You review, correct, re-prompt — and become the AI's QA department. OpenKoi is different. It follows a **Plan-Execute-Evaluate-Refine** loop, iterating on its own output until results meet your quality standards. The agent is its own reviewer.
Ships as a single static binary. Zero runtime dependencies. Works with any model.
## Three Steps
```bash
# 1. Install
brew tap openkoi-ai/openkoi
brew install openkoi
# or
cargo install openkoi
# or
# 2. Think — OpenKoi deliberates before it acts
openkoi think "Refactor the auth module to use JWT tokens"
# 3. Ship — it iterates until the code passes its own review
# [SOVEREIGN] "Direct, test-driven, security-conscious"
# [PARLIAMENT] Guardian=APPROVE Economist=APPROVE Scholar=APPROVE+
# [EXEC] Rewriting token.rs, middleware.rs, handlers.rs
# [EVAL] correctness=9.2 safety=9.5 style=8.8
# [REFN] Style below 9.0 — tightening error types
# [EVAL] correctness=9.4 safety=9.5 style=9.3
# [LEARNED] "JWT refresh tokens need constant-time comparison"
# ✓ Done. 3 iterations. 4 files changed.
```
No config file needed. No setup wizard. OpenKoi detects your API keys from environment variables, existing CLI tools, and local model servers — and picks the best available model.
## What Changes
| `agent run "do X"` → output | `openkoi think "do X"` → deliberation → parliament → output |
| You see the result | You see **how it decided**, not just what it decided |
| You manually review every AI output | The agent evaluates its own work against rubrics |
| You re-prompt corrections 3-5 times | Automatic iteration, stops when quality threshold is met |
| Learnings vanish between sessions | Sessions persist with transcripts; resume any chat; patterns and skills improve over time |
| Memory is hidden | World model is inspectable: `openkoi world`, `openkoi mind` |
| Locked to one provider | Switch providers with a flag; different models per role |
| Data on someone else's cloud | Everything stays on your machine |
| 500ms startup, 100MB memory | <10ms startup, ~5MB idle, ~20MB binary |
## Features
- **Self-iteration** — Plan, execute, evaluate, refine. The agent is its own reviewer.
- **8+ providers** — Anthropic, OpenAI, Google, Ollama, AWS Bedrock, Groq, DeepSeek, Moonshot/Kimi, MiniMax, and any OpenAI-compatible endpoint.
- **Dynamic model discovery** — Probes provider APIs for available models, caches results locally. Fuzzy validation with "did you mean?" suggestions for typos.
- **Role-based models** — Assign different models to executor, evaluator, planner, and embedder roles. Auto-resolves a small/fast model for cost-sensitive internal tasks.
- **Automatic retry** — Rate limits, server errors, and timeouts are retried with exponential backoff and jitter. Context overflow is detected and handled separately.
- **Real-time progress** — Structured progress output on stderr showing plan, iterations, scores, tool calls, and costs. Suppress with `--quiet`.
- **Live task monitoring** — `openkoi status --live` polls the running task every second with a progress bar, score, cost, and recent history.
- **Session lifecycle** — Every task and chat creates a tracked session with status (active/paused/ended), transcript, and per-task output files. Browse with `openkoi session list`, resume chats with `openkoi chat --resume <id>`.
- **Task output persistence** — Task outputs are saved to `~/.local/share/openkoi/sessions/<session-id>/<task-id>.md`. Replay any past output with `openkoi task replay <id>`.
- **Task state persistence** — Current task state written to `~/.openkoi/state/last-task.json`; completed tasks appended to `task-history.jsonl` with auto-rotation.
- **HTTP API** — Localhost REST API (port 9742) for submitting tasks, querying status, and reading cost data. Optional Bearer token auth.
- **Webhooks** — Fire HTTP callbacks on `task.complete`, `task.failed`, and `budget.warning` events.
- **Smart truncation** — Tool outputs exceeding 2000 lines or 50KB are truncated with the full output saved to `~/.openkoi/tool-output/`.
- **Context overflow handling** — Detects overflow errors from all major providers and prunes context instead of failing.
- **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.
- **Rich messaging** — Slack, Discord, and Telegram integrations send structured task results with fields, colors, and thread support.
- **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.
- **Cognitive CLI** — `think` replaces `run`: deliberation before execution. Inspect the Parliament, World Map, Trust levels, and Reflection loops from the terminal.
- **Society of Mind** — Five agencies (Guardian, Economist, Empath, Scholar, Strategist) deliberate on every task. View verdicts with `openkoi mind`.
- **World model** — Tool Atlas tracks reliability and failure modes. Domain Atlas captures learned expertise. Human Atlas models your preferences.
- **Trust & delegation** — Grant autonomous action per domain, revoke anytime, audit every decision the agent made on its own.
- **Reflection loops** — Daily, weekly, and deep self-assessment. Epistemic honesty audit shows where the agent was wrong and what it learned.
- **Sensitive information redaction** — Enterprise-ready preprocessor that scans and redacts secrets (API keys, passwords, PII, private keys, connection strings) before content reaches AI providers, then restores them in responses. Opt-in via `--redact` flag or config.
## CLI
### Core
```bash
openkoi "task" # Run a task (default 3 iterations)
openkoi think "task" # EFaaS pipeline: Sovereign → Parliament → Execute → Learn
openkoi think "task" --simulate # Simulate futures without executing
openkoi think "task" --verbose # Show full parliamentary deliberation
openkoi chat # Interactive REPL
openkoi chat --resume abc1 # Resume a previous chat session
openkoi learn # Review proposed skills (interactive picker)
openkoi status # Show costs, memory, active models
openkoi status --live # Watch the running task in real-time
openkoi setup # First-time setup, diagnostics, provider connections
openkoi dashboard # TUI dashboard for tasks, costs, learnings, plugins
openkoi disconnect # Interactive picker: choose from connected providers
openkoi update # Self-update
```
### Sessions & Tasks
```bash
openkoi session list # List recent sessions with status, cost, task count
openkoi session show abc1 # Show session details and tasks (prefix match)
openkoi session resume abc1 # Resume an ended chat session
openkoi session delete abc1 # Delete a session and its data
openkoi task list # List recent tasks across all sessions
openkoi task list --session abc1 # Filter tasks by session
openkoi task show abc1 # Show task details and output preview
openkoi task replay abc1 # Replay full task output to stdout (pipeable)
```
### Cognitive Commands
Introspect the agent's mind. Every command works with no arguments (shows overview) or with a subcommand for detail.
```bash
# Soul — Sovereign identity
openkoi soul show # Display current SOUL.md + Value Model + Trajectory
openkoi soul evolve # Trigger soul evolution check from accumulated learnings
openkoi soul diff # Show proposed changes with evidence
openkoi soul history # Show evolution timeline
# Mind — Society of Mind introspection
openkoi mind parliament # Show last parliamentary deliberation
openkoi mind agencies # List active agencies + recent verdicts
openkoi mind dissent # Show cases where agencies disagreed
openkoi mind calibrate # Review agency prediction accuracy vs. outcomes
# World — World model inspection
openkoi world tools # Tool Atlas: reliability, failure modes, call history
openkoi world tools <name> # Drill into a specific tool
openkoi world domains # Domain Atlas: learned domain knowledge
openkoi world human # Human Atlas: what the agent knows about you
openkoi world map # Full World Map overview
# Reflect — Feedback loops & self-assessment
openkoi reflect today # Tight loop: today's tasks, decisions, outcomes
openkoi reflect week # Medium loop: weekly patterns and behavioral trends
openkoi reflect growth # Deep loop: maturity stage and unlock progress
openkoi reflect honest # Epistemic audit: where was I wrong? what did I learn?
# Trust — Trust & delegation management
openkoi trust show # Current trust level per domain
openkoi trust grant <domain> <level> # Delegate a domain (levels: ask, suggest, act, autonomous)
openkoi trust revoke <domain> # Revoke delegation
openkoi trust audit [domain] # Audit autonomous actions taken
```
### Task flags
```bash
openkoi "task" -i 5 # Set max iterations (default 3)
openkoi "task" --quality 0.9 # Set quality threshold (default 0.8)
openkoi "task" --quiet # Suppress progress output; only emit final result
openkoi "task" --redact # Redact secrets before sending to AI providers
openkoi "task" -m claude-sonnet-4 # Use a specific model
```
All commands that accept an argument also work without one — omitting the argument shows an interactive selection menu. Explicit arguments still work exactly as before.
## Providers
### Subscription-based (OAuth login, free with your existing plan)
Use `openkoi connect` to authenticate via device-code flow. No API key needed.
| GitHub Copilot | `openkoi connect copilot` | Device code (GitHub login) |
| ChatGPT Plus/Pro | `openkoi connect chatgpt` | Device code (OpenAI login) |
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`.
| Anthropic | `ANTHROPIC_API_KEY` |
| OpenAI | `OPENAI_API_KEY` |
| Google | `GOOGLE_API_KEY` |
| AWS Bedrock | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` |
| Groq | `GROQ_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Together | `TOGETHER_API_KEY` |
| DeepSeek | `DEEPSEEK_API_KEY` |
| MiniMax | `MINIMAX_API_KEY` |
| Moonshot/Kimi | `MOONSHOT_API_KEY` |
| xAI | `XAI_API_KEY` |
| Qwen | `QWEN_API_KEY` |
API keys are saved to `~/.openkoi/credentials/<provider>.key` (owner-only permissions).
### Local
| Ollama | Auto-detected at `localhost:11434` |
| Custom (OpenAI-compatible) | `openkoi connect` picker or `config.toml` |
## 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
```bash
# Interactive picker (shows all providers and integrations)
openkoi connect
# Or specify directly
openkoi connect copilot # GitHub Copilot
openkoi connect chatgpt # ChatGPT Plus/Pro
# Interactive disconnect (shows only currently connected providers)
openkoi disconnect
# Or specify directly
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
```
## HTTP API
The daemon exposes a localhost REST API on port 9742 for external tools, scripts, and web UIs.
| `POST` | `/api/v1/tasks` | Submit a new task |
| `GET` | `/api/v1/tasks` | List recent tasks |
| `GET` | `/api/v1/tasks/{id}` | Get task details |
| `POST` | `/api/v1/tasks/{id}/cancel` | Cancel a running task |
| `GET` | `/api/v1/status` | System status (version, daemon state, active task) |
| `GET` | `/api/v1/cost` | Cost summary for last 24 hours |
| `GET` | `/api/v1/health` | Health check |
```bash
# Submit a task
curl -X POST http://localhost:9742/api/v1/tasks \
-H "Content-Type: application/json" \
-d '{"description": "Fix the login bug", "max_iterations": 5}'
# Check status
curl http://localhost:9742/api/v1/status
```
Configure in `config.toml`:
```toml
[api]
enabled = true
port = 9742
token = "your-secret-token" # Optional Bearer auth
[api.webhooks]
on_task_complete = "https://example.com/hooks/complete"
on_task_failed = "https://example.com/hooks/failed"
on_budget_warning = "https://example.com/hooks/budget"
```
## Architecture
```
┌─────────────────┐
│ Sovereign │ ← Soul (SOUL.md + Value Model + Trajectory)
│ Directive │
└────────┬────────┘
│
┌────────▼────────┐
│ Parliament │ ← Mind (Guardian, Economist, Empath, Scholar, Strategist)
└────────┬────────┘
│
┌────────▼────────┐
│ Orchestrator │
└────────┬────────┘
┌───────┬───────┼───────┬──────────┐
▼ ▼ ▼ ▼ ▼
Executor Evaluator Learner Pattern Integrations
│ Miner
▼
Tools (MCP / WASM / Rhai)
│
▼
World Model ← World (Tool Atlas + Domain Atlas + Human Atlas)
```
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:
| Bundled | Embedded in binary | Lowest |
| Managed | `~/.openkoi/skills/managed/` | |
| Workspace | `.agents/skills/` in your project | |
| User global | `~/.openkoi/skills/user/` | |
| Pattern-proposed | `~/.openkoi/skills/proposed/` | Highest |
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:
| `self-iterate` | task | Guides OpenKoi when modifying its own codebase |
| `general` | evaluator | Fallback evaluator for any task |
| `code-review` | evaluator | Evaluates code for correctness, safety, style |
| `prose-quality` | evaluator | Evaluates writing for clarity, accuracy, tone |
| `sql-safety` | evaluator | Evaluates SQL for correctness, safety, performance |
| `api-design` | evaluator | Evaluates APIs for consistency, error handling |
| `test-quality` | evaluator | Evaluates tests for coverage, assertions, isolation |
### Writing a custom skill
Create a directory with a `SKILL.md` file:
```bash
mkdir -p .agents/skills/my-skill
```
```markdown
---
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:
```markdown
---
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
```bash
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.
## Environment
All paths default to `~/.openkoi/` (config) and `~/.local/share/openkoi/` (data). Set `OPENKOI_HOME` to relocate everything under a single directory:
```bash
export OPENKOI_HOME=/tmp/openkoi-test
openkoi status # config at /tmp/openkoi-test/, data at /tmp/openkoi-test/data/
```
| `OPENKOI_HOME` | Override all config and data paths. Config lives at `$OPENKOI_HOME/`, data at `$OPENKOI_HOME/data/`. |
| `OPENKOI_CONFIG` | Override the config file path only. Default: `~/.openkoi/config.toml`. |
| `OPENKOI_DATA` | Override the data directory only. Default: `~/.local/share/openkoi`. |
| `OPENKOI_MODEL` | Default model in `provider/model` format. |
| `OPENKOI_LOG_LEVEL` | Log verbosity: `error`, `warn`, `info`, `debug`, `trace`. |
## Sensitive Information Redaction
For enterprise environments where source code, config files, or tool outputs may contain secrets, OpenKoi can redact sensitive information before it reaches AI providers and restore it in responses.
```bash
# Enable for a single run
openkoi --redact "fix the database connection in config.yaml"
```
Or enable persistently in `~/.openkoi/config.toml`:
```toml
[redaction]
enabled = true
[redaction.categories]
api_keys = true # AWS, GitHub, OpenAI, Anthropic, Slack, Stripe tokens
passwords = true # password=, secret=, client_secret= assignments
private_keys = true # PEM blocks (RSA, EC, DSA, OPENSSH)
connection_strings = true # postgres://, mysql://, mongodb:// with credentials
jwt_tokens = true # JWT token strings
high_entropy = false # High-entropy hex strings (opt-in, may have false positives)
# Custom patterns (regex)
[[redaction.custom_patterns]]
name = "CORP_ID"
pattern = "CORP-[A-Z0-9]{8}"
# Known secrets to always redact (literal match)
literal_secrets = ["my-known-secret-value"]
```
Secrets are replaced with deterministic placeholders (`<<REDACTED_AWS_KEY_1>>`, `<<REDACTED_PASSWORD_2>>`, etc.) so the AI can still reason about the structure of your code. The same secret always maps to the same placeholder within a session, and all placeholders are restored in the final output.
## Install
```bash
# Via Homebrew (macOS / Linux)
brew tap openkoi-ai/openkoi
brew install openkoi
# Via Cargo (source build)
cargo install openkoi
# Via shell installer
Full documentation at [openkoi.ai](https://openkoi.ai).
## Acknowledgments
OpenKoi was built with significant help from AI coding assistants, including **Claude Code**, **Codex**, and **Gemini**.
Several design patterns and implementations draw from the open source community:
- **[OpenCode](https://github.com/anomalyco/opencode)** — The scout/explore subagent pattern, history compaction strategy (the `prune_messages()` implementation in `token_optimizer.rs` is modeled after OpenCode's `compaction.ts`), and permission rules system were inspired by or adapted from OpenCode's architecture. Model catalog data in the GitHub Copilot provider also references OpenCode's `models.dev/api.json` source.
- **[OpenClaw](https://github.com/openclaw)** — The `.SKILL.md` skill format is OpenClaw-compatible, enabling skill portability across tools.
## License
[MIT](LICENSE)
[](https://star-history.com/#openkoi-ai/openkoi&Date)
