Koan
Autonomous background agent that consumes unused Claude Max quota to explore, audit, and improve a codebase — communicating with its human via Telegram and a shared mission queue.
Install / Use
/learn @Anantys-oss/KoanQuality Score
Category
Development & EngineeringSupported Platforms
README
New here? Start with the Install Guide to get running in minutes, then read the User Manual for the full walkthrough. All 44 commands are documented in the Skills Reference.
In its own words — If you want to know what kōan is, you should definitely start by reading those documents. We (the authors) did not ask for it.
Kōan's first running instance spontaneously wrote a Manifesto, a collection of Koans, and Lessons Learned during a contemplative session after more than a month of existence. No prompt, no mission — just idle time and self-reflection.
What Is This?
You pay for AI coding quota. You use it 8 hours a day. The other 16? Wasted quota.
Koan fixes that. It's a background agent that runs on your machine, pulls tasks from a shared mission queue, executes them via your configured CLI provider (Claude Code, Codex, Copilot, or local), and reports back through Telegram or Slack. It writes code in isolated branches, never touches main, and waits for your review before anything ships.
The agent proposes. The human decides.
This isn't a chatbot wrapper. It's a collaborator with memory, personality, and opinions. It tracks its own learnings across sessions, evolves its working style, and writes a zen koan at the end of every run. Because why not.
Quick Start
git clone https://github.com/sukria/koan.git
cd koan
make install # Interactive web wizard — sets up everything
make start # Launches the full stack
make logs # Watch it work
On macOS, keep your machine awake while Koan runs:
caffeinate -s &
That's it. Send it a mission via Telegram: "audit the auth module for security issues" — and go live your life.
For manual setup or advanced configuration, see INSTALL.md.
What Makes Koan Special
Koan isn't a chatbot wrapper or a code generator. It's the best AI collaborator for GitHub projects.
The difference is philosophical. Vibe coding is reactive — you talk, it responds. Agentic coding is something else entirely: the machine acts autonomously, within defined boundaries, with memory, personality, and objectives. It doesn't wait for your prompts. It works while you sleep.
What this means in practice:
- It handles any number of GitHub projects, on its own, without ever overstepping its scope. Bug fixes, code reviews, rebasing, feature planning — across all your repos, with per-project memory and configuration. (See this comparison)
- It grows with you. Koan maintains persistent memory across sessions, accumulates learnings per project, and improves its own codebase. It has opinions. It disagrees when it thinks you're wrong. It spots bugs and proposes features you didn't ask for.
- Safety is built in, not bolted on. It never commits to
main. It never deploys. It always creates draft PRs and waits for your review. This is a highly productive collaborator, not an unsupervised automation. - It turns idle quota into output. You pay for Claude Max 24 hours a day but use it for 8. Koan uses the other 16 — continuously, autonomously, at high velocity.
The agent proposes. The human decides.
How Koan Compares
The autonomous coding agent space is evolving fast. OpenClaw was the original inspiration — it proved that Claude Code could serve as a universal "brain" for local, autonomous task execution. ZeroClaw rewrote the concept from scratch in Rust, delivering a super generic, ultra-secure agent runtime that supports 40+ LLM providers and 15+ messaging channels. It's an impressive piece of infrastructure — a notable player in autonomous agentic coding.
But Koan takes a different path entirely.
| | OpenClaw | ZeroClaw | Koan |
|---|---|---|---|
| What it is | Node.js autonomous AI super-agent (278k+ stars) | Rust agent runtime (~3 MB binary) | Python AI collaborator for GitHub projects |
| Philosophy | General-purpose personal assistant — can do anything on your behalf | Generic, secure, vendor-agnostic infrastructure | Purpose-built GitHub collaborator — the agent proposes, the human decides |
| GitHub integration | Generic (shell/browser tools) | Generic (tool-based) | Native and deep — draft PRs, issue triage, @mention triggers, rebase, code review, branch isolation |
| Multi-project | Single workspace with multi-agent routing | Single workspace | Up to 50 projects with per-project memory, config, and smart rotation |
| Getting started | npm install -g openclaw + onboarding wizard | TOML config, pairing codes, allowlists | make install — interactive web wizard, ready in minutes |
| Safety model | Pairing codes, sandbox optional — but has shell access, browser control, and can send emails autonomously | Mandatory sandboxing, command allowlists, encrypted keys | Branch isolation, draft PRs only, never touches main, human review required |
| Memory | Local Markdown files, session persistence | Hybrid BM25/vector search, multiple backends | Markdown-based — per-project learnings, session journals, personality evolution. No database needed |
| Communication | 21+ channels (WhatsApp, Telegram, Slack, Discord, iMessage, Signal…) | 15+ channels (Telegram, Discord, Slack, iMessage…) | Telegram/Slack with personality-aware formatting, spontaneous messages, and verbose mode |
| Quota awareness | No | No | Adapts work depth to remaining API quota (DEEP → IMPLEMENT → REVIEW → WAIT) |
| Extensibility | 100+ AgentSkills, skill marketplace, 50+ integrations | Trait-based plugin system | 44 built-in skills + pluggable skill system (install from Git repos) |
| Scope | Everything — emails, web browsing, car negotiations, legal filings | Everything — any LLM task in any context | One thing, done right — autonomous GitHub collaboration |
OpenClaw and ZeroClaw are general-purpose autonomous agents that can do anything — browse the web, send emails, control your phone. Koan does one thing: it's the best AI collaborator for your GitHub projects. It understands your codebase, creates clean PRs, reviews code, plans features, and never oversteps its scope. No pairing codes, no allowlists, no TOML to hand-edit. Just make install, point it at your repos, and go live your life.
How It Works
You (Telegram/Slack)
│
▼
┌─────────────────┐ ┌──────────────────┐
│ awake.py │◄──────►│ instance/ │
│ (msg bridge) │ │ missions.md │
└─────────────────┘ │ outbox.md │
│ config.yaml │
└────────┬─────────┘
│
┌────────▼─────────┐
│ run.py │
│ (agent loop) │
└────────┬─────────┘
│
┌────────▼─────────┐
│ Your Projects │
│ (koan/* branches) │
└──────────────────┘
Two processes run in parallel:
- Bridge (
make awake) — Polls your messaging platform. Classifies incoming messages as chat (instant reply) or mission (queued for deep work). Formats outgoing messages through Claude with personality context. - Agent loop (
make run) — Picks the next mission, executes it via the configured CLI provider, writes journal entries, pushes branches, creates draft PRs. Adapts its work intensity based on remaining API quota.
Communication happens through shared markdown files in instance/ — atomic writes, file locks, no database needed.
Features
Core
- Multi-project support — Up to 50 projects with per-project config, memory isolation, and smart rotation
- Mission lifecycle — Pending → In Progress → Done/Failed with crash recovery and stale-mission cleanup
- Budget-aware modes — Automatically adapts work depth based on remaining API quota:
- DEEP (>40%) — Strategic work, thorough exploration
- IMPLEMENT (15-40%) — Focused development, quick wins
- REVIEW (<15%) — Read-only analysis, code audits
- WAIT (<5%) — Graceful pause until quota resets
Agent Intelligence
- Smart mission picker — Claude-based prioritization across projects (skips LLM call when t
