Kōan

An autonomous AI agent that works while you sleep.
Turns idle Claude Max quota into code reviews, bug fixes, and strategic insights.

Quick Start • How It Works • Features • Skills • Configuration • Full Install Guide

---

What Is This?

You pay for Claude Max. 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 Claude Code CLI, 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 agent loop + messaging bridge

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.

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 Claude Code CLI, 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 trivial)
• Persistent memory — Session summaries, per-project learnings, personality evolution
• Contemplative mode — Occasional reflection sessions between missions (configurable probability)
• Daily reports — Digest messages at session boundaries
• Post-mission reflection — Writes deeper insights to a shared journal after significant work

Git & GitHub

• Branch isolation — All work happens in koan/* branches. Never commits to main
• Auto-merge — Configurable per-project merge strategies (squash/merge/rebase)
• Git sync awareness — Tracks branch state, detects merges, reports sync status
• GitHub integration — Draft PRs, issue creation, PR reviews, rebasing — all via gh CLI
• GitHub @mention triggers — Koan responds to @mentions on issues and PRs

Communication

• Telegram & Slack — Pluggable messaging with flood protection
• Email digests — Optional SMTP email notifications for session summaries (rate-limited, deduplicated)
• Personality-aware formatting — Every outbox message passes through Claude with soul + memory context
• Verbose mode — Real-time progress updates streamed to your phone
• Spontaneous messages — Koan occasionally initiates conversation when something feels worth saying

Developer Experience

• 31 slash commands — From /plan to /review to /sparring — see Skills
• Web dashboard — Local Flask UI for status, missions, chat, and journal browsing
• Setup wizard — Web-based guided setup (make install)
• 4500+ tests — Comprehensive test suite with make test

Skills

Skills are pluggable commands — some are instant, others spawn Claude work sessions. A few highlights:

Command	What it does
/mission <text>	Queue a new mission
/plan <desc>	Create an implementation plan
/implement <desc>	Write code for a feature or fix
/review <PR>	Review a pull request
/rebase <PR>	Rebase a PR onto its base branch
/recreate <PR>	Re-implement a PR from scratch on a fresh branch
/check <project>	Run project health checks
/claudemd	Refresh a project's CLAUDE.md
/refactor <desc>	Targeted refactoring mission
/sparring	Strategic challenge — not code, thinking
/reflect <msg>	Write to the shared journal
/status	Quick status overview
/focus <project>	Lock agent to one project
/quota	Check API usage and budget
/journal	Read today's journal entries
/verbose / /silent	Toggle real-time updates

Full list: run /help in Telegram. Skills are extensible — drop a SKILL.md in instance/skills/ or install from a Git repo with /skill install <url>.

See koan/skills/README.md for the authoring guide.

Configuration

All behavioral config lives in instance/config.yaml. Secrets stay in .env.

# How hard should Kōan work
max_runs_per_day: 10
interval_seconds: 60

# Model selection per role
models:
  mission: null        # Default (sonnet)
  chat: null           # Default (sonnet)
  lightweight: haiku   # Quick tasks (formatting, picking)

# Budget thresholds
budget:
  warn_at_percent: 20
  stop_at_percent: 5

Multi-Project Setup

Define your projects in projects.yaml at KOAN_ROOT:

defaults:
  git_auto_merge:
    enabled: false

projects:
  webapp:
    path: ~/Code/webapp
  api:
    path: ~/Code/api
    cli_provider: copilot    # Per-project provider override
    models:
      mission: opus

CLI Providers

Koan isn't locked to Claude. Swap the backend per-project:

Provider	Best for
Claude Code (default)	Full-featured agent, best reasoning
GitHub Copilot	Teams with existing Copilot licenses
Local LLM	Offline, privacy, zero API cost

See provider guides in docs/.

Architecture

koan/
  app/                    # Core Python modules (24K LOC)
    run.py                #   Main agent loop
    awake.py              #   Messaging bridge
    missions.py           #   Mission parsing & lifecycle
    mission_runner.py     #   Execution pipeline
    skill_dispatch.py     #   Direct skill execution
    memory_manager.py     #   Per-project memory isolation
    usage_tracker.py      #   Budget tracking & mode selection
    provider/             #   CLI provider abstraction
      claude.py           #     Claude Code CLI
      copilot.py          #     GitHub Copilot CLI
  skills/                 # Pluggable command system (31 core skills)
  system-prompts/         # All LLM prompts (14 files, no inline prompts)
  templates/              # Dashboard Jinja2 templates
  tests/                  # 4500+ tests (pytest)
instance/                 # Your private data (gitignored)
  soul.md                 #   Agent personality — this is who Kōan is
  missions.md             #   Task queue
  config.yaml             #   Behavioral settings
  memory/                 #   Persistent context across sessions
  journal/                #   Daily logs (YYYY-MM-DD/project.md)

Design principle: Code is generic and open source. Instance data is private. Fork the repo, write your own soul.

Make Targets

Target	Description
make install	Interactive web-based setup wizard
make start	Start full stack (agent + bridge)
make stop	Stop all processes
make status	Show running process status
make logs	Tail live output
make run	Agent loop (foreground)
make awake	Messaging bridge (foreground)
make dashboard	Web UI (port 5001)
make test	Run test suite
make say m="..."	Send a test message
make install-systemctl-service	Install systemd service (Linux only)
make uninstall-systemctl-service	Remove systemd service
make clean	Remove virtualenv

Philosophy

Koan was born from a simple question: what do you do with a Claude Max subscription when you're not at your desk?

The answer: you build a collaborator. Not an assistant — a sparring partner. One that reads your code before suggesting changes, tracks its own mistakes, and has the spine to say "I think this is wrong" when it means it.

It works in koan/* branches. It never merges to main. It writes a journal. It evolves. And at the end of every session, it writes a koan — a zen question born from the work it just did. Because reflection matters more than velocity.

The agent proposes. The human decides.

Security

Koan is designed for local, single-user operation. It is not a web service.

• All work happens in isolated koan/* branches — your main is never modified
• Chat tools are restricted (read-only) vs. mission tools (full access) to limit prompt injection surface
• Dashboard binds to localhost only — no external access by default
• Telegram/Slack auth uses platform-level identity verification

Do not expose Koan services to the public internet. For remote access, use SSH tunnels.

Contributing

Koan is open source under GPL-3.0. Contributions welcome.

make setup
KOAN_ROOT=/tmp/test-koan make test   # Run the test suite

Check CLAUDE.md for coding conventions and architecture details.

License

GPL-3.0 — Free as in freedom.