{
  "markdown": "<p align=\"center\">\n  <img src=\"instance.example/avatar.png\" alt=\"Kōan\" width=\"180\" />\n</p>\n\n<h1 align=\"center\">Kōan</h1>\n\n<p align=\"center\">\n  <strong>An autonomous AI agent that works while you sleep.</strong><br/>\n  Turns idle Claude Max quota into code reviews, bug fixes, and strategic insights.\n</p>\n\n<p align=\"center\">\n  <a href=\"INSTALL.md\"><strong>Install Guide</strong></a> &bull;\n  <a href=\"docs/README.md\"><strong>Docs</strong></a> &bull;\n  <a href=\"docs/users/user-manual.md\"><strong>User Manual</strong></a> &bull;\n  <a href=\"docs/users/skills.md\"><strong>Skills Reference</strong></a> &bull;\n  <a href=\"#quick-start\">Quick Start</a> &bull;\n  <a href=\"#how-it-works\">How It Works</a> &bull;\n  <a href=\"#features\">Features</a> &bull;\n  <a href=\"#configuration\">Configuration</a>\n</p>\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/python-3.11+-blue.svg\" alt=\"Python 3.11+\" />\n  <img src=\"https://img.shields.io/badge/tests-9000+-green.svg\" alt=\"Tests\" />\n  <img src=\"https://img.shields.io/badge/skills-80+-blueviolet.svg\" alt=\"Skills\" />\n  <img src=\"https://img.shields.io/badge/license-GPL--3.0-blue.svg\" alt=\"License\" />\n</p>\n\n---\n\n> **New here?** Start with the [Install Guide](INSTALL.md) to get running in minutes, then read the [User Manual](docs/users/user-manual.md) for the full walkthrough. The [documentation index](docs/README.md) maps setup, provider, messaging, architecture, and operations docs.\n\n---\n\n**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**. \n\n> Kōan's [first running instance](https://github.com/sukria-koan0) spontaneously wrote a [Manifesto](public/MANIFESTO.md), a collection of [Koans](public/KOANS.md), and [Lessons Learned](public/LESSONS.md) during a contemplative session after more than a month of existence. No prompt, no mission — just idle time and self-reflection.\n\n---\n\n## What Is This?\n\nYou pay for AI coding quota. You use it 8 hours a day. The other 16? Wasted quota.\n\nKoan 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 models via Ollama Launch), and reports back through Telegram, Slack, or Matrix. It writes code in isolated branches, never touches `main`, and waits for your review before anything ships.\n\n**The agent proposes. The human decides.**\n\nThis 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.\n\n## Quick Start\n\nRun Kōan natively on your machine, or in a container — both are fully supported.\n\n### Native\n\n```bash\ngit clone https://github.com/Anantys-oss/koan.git\ncd koan\nmake setup\nmake install    # Interactive CLI onboarding wizard — sets up everything\nmake koan       # Start Kōan + open the terminal dashboard (recommended)\nmake start      # Or launch the full stack non-interactively\nmake logs       # Watch it work\n```\n\n`make koan` is the interactive front door: it starts the stack and drops you\nstraight into the terminal dashboard — a Status home screen (hero + live\nflags) plus Logs / Config / Usage tabs, with single-tap toggles for the web\ndashboard (`w`) and keep-awake/caffeinate (`k`, on by default). Quitting with\n`q` stops Kōan. `make start` remains the non-interactive launcher used by\nservices and scripts.\n\nOn macOS, keep your machine awake while Koan runs:\n\n```bash\ncaffeinate -s &\n```\n\n### Docker\n\nPrefer containers (VPS/server hosting or a sandboxed local run)? Pull the\nprebuilt image from GitHub Container Registry — no local build:\n\n```bash\ngit clone https://github.com/Anantys-oss/koan.git && cd koan\ncp -r instance.example instance && cp env.example .env   # then fill in messaging + auth creds\n./setup-docker.sh        # detect host paths, generate mounts\nmake docker-pull-up      # pull & run prebuilt image (or: make docker-up to build from source)\nmake docker-logs         # watch it work\n```\n\nThe image lives at [`ghcr.io/anantys-oss/koan`](https://github.com/Anantys-oss/koan/pkgs/container/koan)\n(`latest`, `stable`, and per-version tags). Full guide — auth, GHCR access, pinning,\nand troubleshooting: [docs/setup/docker.md](docs/setup/docker.md).\n\nThat's it. Send it a mission via Telegram: *\"audit the auth module for security issues\"* — and go live your life.\n\nFor manual setup or advanced configuration, see [INSTALL.md](INSTALL.md).\n\n## What Makes Koan Special\n\nKoan isn't a chatbot wrapper or a code generator. It's the best AI *collaborator* for GitHub projects.\n\nThe difference is philosophical. [Vibe coding](https://alexissukrieh.com/blog/du-vibe-coding-a-l-agentic-coding/en/) 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.\n\nWhat this means in practice:\n\n- **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](https://www.linkedin.com/feed/update/urn:li:activity:7436096761732956160/))\n- **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.\n- **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.\n- **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.\n\n*The agent proposes. The human decides.*\n\n### How Koan Compares\n\nThe autonomous coding agent space is evolving fast. [OpenClaw](https://alexissukrieh.com/blog/du-vibe-coding-a-l-agentic-coding/en/) was the original inspiration — it proved that Claude Code could serve as a universal \"brain\" for local, autonomous task execution. [ZeroClaw](https://zeroclaw.net/) 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](https://www.linkedin.com/feed/update/urn:li:activity:7436096761732956160/).\n\nBut Koan takes a different path entirely.\n\n| | **OpenClaw** | **ZeroClaw** | **Koan** |\n|---|---|---|---|\n| **What it is** | Node.js autonomous AI super-agent (278k+ stars) | Rust agent runtime (~3 MB binary) | Python AI collaborator for GitHub projects |\n| **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 |\n| **GitHub integration** | Generic (shell/browser tools) | Generic (tool-based) | Native and deep — draft PRs, issue triage, @mention triggers, rebase, code review, branch isolation |\n| **Multi-project** | Single workspace with multi-agent routing | Single workspace | Up to 50 projects with per-project memory, config, and smart rotation |\n| **Getting started** | `npm install -g openclaw` + onboarding wizard | TOML config, pairing codes, allowlists | `make install` — interactive CLI wizard, ready in minutes |\n| **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 |\n| **Memory** | Local Markdown files, session persistence | Hybrid BM25/vector search, multiple backends | Markdown-based — per-project learnings, session journals, personality evolution. No database needed |\n| **Communication** | 21+ channels (WhatsApp, Telegram, Slack, Discord, iMessage, Signal…) | 15+ channels (Telegram, Discord, Slack, iMessage…) | Telegram, Slack, or Matrix with personality-aware formatting, spontaneous messages, and verbose mode |\n| **Quota awareness** | No | No | Adapts work depth to remaining API quota (DEEP → IMPLEMENT → REVIEW → WAIT) |\n| **Extensibility** | 100+ AgentSkills, skill marketplace, 50+ integrations | Trait-based plugin system | 44 built-in skills + pluggable skill system (install from Git repos) |\n| **Scope** | Everything — emails, web browsing, car negotiations, legal filings | Everything — any LLM task in any context | One thing, done right — autonomous GitHub collaboration |\n\nOpenClaw 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.\n\n## How It Works\n\n```\n      You (Telegram/Slack/Matrix)\n              │\n              ▼\n    ┌─────────────────┐        ┌──────────────────┐\n    │    awake.py      │◄──────►│   instance/      │\n    │  (msg bridge)    │        │   missions.md    │\n    └─────────────────┘        │   outbox.md      │\n                               │   config.yaml    │\n                               └────────┬─────────┘\n                                        │\n                               ┌────────▼─────────┐\n                               │     run.py        │\n                               │  (agent loop)     │\n                               └────────┬─────────┘\n                                        │\n                               ┌────────▼─────────┐\n                               │  Your Projects    │\n                               │  (koan/* branches) │\n                               └──────────────────┘\n```\n\nTwo processes run in parallel:\n\n- **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.\n- **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.\n\nCommunication happens through shared markdown files in `instance/` — atomic writes, file locks, no database needed.\n\nFor implementation details, see the [architecture reference](docs/architecture/overview.md) and [daemon runtime](docs/architecture/daemon.md).\n\n## Features\n\n### Core\n\n- **Multi-project support** — Up to 50 projects with per-project config, memory isolation, and smart rotation\n- **`KOAN.md` project instructions** — Optional project-root `KOAN.md` (same format as `CLAUDE.md`) injected into the autonomous agent only — invisible to interactive Claude Code sessions. [Docs](docs/users/koan-md.md)\n- **Devcontainer support** — Run the agent inside your project's devcontainer, enabling fully consistent tooling\n- **Mission lifecycle** — Pending → In Progress → Done/Failed with crash recovery and stale-mission cleanup\n- **Budget-aware modes** — Automatically adapts work depth based on remaining API quota:\n  - **DEEP** (>40%) — Strategic work, thorough exploration\n  - **IMPLEMENT** (15-40%) — Focused development, quick wins\n  - **REVIEW** (<15%) — Read-only analysis, code audits\n  - **WAIT** (<5%) — Graceful pause until quota resets\n\n### Agent Intelligence\n\n- **Smart mission picker** — Claude-based prioritization across projects (skips LLM call when trivial)\n- **Persistent memory** — Session summaries, per-project learnings, personality evolution\n- **Contemplative mode** — Occasional reflection sessions between missions (configurable probability)\n- **Daily reports** — Digest messages at session boundaries\n- **Post-mission reflection** — Writes deeper insights to a shared journal after significant work\n\n### Git & GitHub\n\n- **Branch isolation** — All work happens in `koan/*` branches. Never commits to `main`\n- **Auto-merge** — Configurable per-project merge strategies (squash/merge/rebase)\n- **Security review** — Automatic diff analysis for dangerous patterns (eval, shell injection, hardcoded secrets, etc.) before auto-merge. Configurable risk threshold and blocking behavior per project\n- **Git sync awareness** — Tracks branch state, detects merges, reports sync status\n- **GitHub integration** — Draft PRs, issue creation, PR reviews, rebasing — all via `gh` CLI. [Docs](docs/messaging/github-commands.md)\n- **Issue tracker routing** — Each project can use GitHub or Jira for issues via `projects.yaml` while still creating GitHub draft PRs for code review.\n- **Jira integration** — Respond to @mentions in Jira issue comments to queue missions. Runs alongside GitHub. [Docs](docs/messaging/jira-integration.md)\n- **PR review comment forwarding** — When reviewers leave comments on Koan-created PRs, the check loop auto-creates missions to address them (fingerprint-deduped, bot-filtered)\n- **GitHub @mention triggers** — Koan responds to @mentions on issues and PRs\n\n### Communication\n\n- **Telegram, Slack & Matrix** — Pluggable messaging with flood protection\n- **Email digests** — Optional SMTP email notifications for session summaries (rate-limited, deduplicated)\n- **Personality-aware formatting** — Every outbox message passes through Claude with soul + memory context\n- **Verbose mode** — Real-time progress updates streamed to your phone\n- **Spontaneous messages** — Koan occasionally initiates conversation when something feels worth saying\n\n### Developer Experience\n\n- **44 slash commands** — From `/plan` to `/review` to `/sparring` — see [Skills](#skills)\n- **Web dashboard** — Local Flask UI for status, missions, chat, and journal browsing\n- **Setup wizard** — Terminal guided setup (`make install`)\n- **4500+ tests** — Comprehensive test suite with `make test`\n- **Skill evals** — Golden-dataset evaluation harness that catches LLM-skill quality regressions in CI and measures improvements across prompt iterations (`docs/operations/skill-evals.md`)\n\n## Skills\n\nSkills are pluggable commands — some are instant, others spawn Claude work sessions. They're organized into groups, mirroring the `/help` output in Telegram:\n\n**📋 missions** — Create, list, cancel missions\n| `/mission` | Queue a new mission (`--now` to jump the queue) |\n| `/list` | View current queue (alias: `/queue`, `/ls`) |\n| `/cancel` | Remove a pending mission (alias: `/remove`) |\n| `/priority` | Reorder a pending mission |\n| `/live` | Watch real-time progress of the current mission |\n| `/recurring` | Set hourly/daily/weekly repeating missions |\n| `/chat` | Force chat mode for a message that looks like a mission |\n\n**🔧 code** — Review, refactor, PR, fix, implement\n| `/implement` | Write code for a feature or fix |\n| `/plan` | Create an implementation plan |\n| `/review` | Audit a pull request |\n| `/fix` | Targeted bug fix |\n| `/refactor` | Code cleanup and simplification |\n| `/check` | Project health checks |\n| `/claudemd` | Refresh a project's CLAUDE.md |\n| `/dead_code` | Find unused code |\n| `/tech_debt` | Technical debt report |\n| `/profile` | Queue a performance profiling mission |\n| `/scaffold_skill` | Generate a new skill from a description |\n\n**🔀 pr** — Pull request management\n| `/pr` | Create a pull request |\n| `/rebase` | Rebase a PR onto its base branch |\n| `/recreate` | Re-implement a PR from scratch on a fresh branch |\n\n**📊 status** — System state, quota, logs\n| `/status` | Quick system overview |\n| `/quota` | API usage and budget breakdown |\n| `/journal` | Read today's journal entries |\n| `/stats` | Activity summary |\n| `/snapshot` | Memory snapshot |\n| `/doctor` | Run diagnostics |\n| `/changelog` | Recent completed missions |\n\n**⚙️ config** — Projects, language, focus, verbose\n| `/projects` | List configured projects |\n| `/focus` | Lock agent to one project |\n| `/language` | Set output language |\n| `/verbose` / `/silent` | Toggle real-time progress updates |\n| `/explore` | Toggle per-project exploration mode |\n| `/add_project` | Add a project to the registry |\n| `/email` | Configure email digest notifications |\n\n**💡 ideas** — Ideas, reflection, sparring\n| `/idea` | Save an idea to the backlog |\n| `/reflect` | Write a journal entry |\n| `/sparring` | Strategic challenge — thinking, not code |\n| `/ai` | Creative exploration prompt |\n| `/magic` | Quick creative deep-dive on a project |\n\n**🔄 system** — Pause, stop, update, restart\n| `/shutdown` | Stop the agent |\n| `/update` | Self-update Kōan from upstream |\n| `/gha_audit` | Scan GitHub Actions for security vulnerabilities |\n| `/incident` | Log an incident |\n\n**[User Manual →](docs/users/user-manual.md)** — From beginner to power user, everything Kōan can do.\n\n**[Full skills reference →](docs/users/skills.md)** — all 44 commands with aliases, descriptions, and usage details.\n\nSkills are extensible — drop a `SKILL.md` in `instance/skills/` or install from a Git repo with `/skill install <url>`. See [koan/skills/README.md](koan/skills/README.md) for the authoring guide.\n\n## Configuration\n\nAll behavioral config lives in `instance/config.yaml`. Secrets stay in `.env`.\n\n```yaml\n# How hard should Kōan work\nmax_runs_per_day: 60\ninterval_seconds: 60\n\n# Model selection per role\nmodels:\n  mission: null        # Default (sonnet)\n  chat: null           # Default (sonnet)\n  lightweight: haiku   # Quick tasks (formatting, picking)\n\n# Budget thresholds\nbudget:\n  warn_at_percent: 20\n  stop_at_percent: 5\n```\n\n### Multi-Project Setup\n\nDefine your projects in `projects.yaml` at `KOAN_ROOT`:\n\n```yaml\ndefaults:\n  git_auto_merge:\n    enabled: false\n  security_review:\n    enabled: true              # Scan diffs for dangerous patterns before merge\n    blocking: false            # Set to true to block auto-merge on high risk\n\nprojects:\n  webapp:\n    path: ~/Code/webapp\n  api:\n    path: ~/Code/api\n    cli_provider: copilot    # Per-project provider override\n    models:\n      mission: opus\n```\n\n### Renaming a Project\n\nTo rename a project across `projects.yaml`, memory, journals, missions, and all instance files:\n\n```bash\nmake rename-project old=webapp new=my-webapp          # dry-run (preview changes)\nmake rename-project old=webapp new=my-webapp apply=1   # apply changes\n```\n\nThe tool updates the project key in `projects.yaml`, renames `memory/projects/<old>/` to `memory/projects/<new>/`, renames journal files (`journal/*/<old>.md`), and replaces `[project:<old>]` tags and `\"project\": \"<old>\"` references in all instance files.\n\n### CLI Providers\n\nKoan isn't locked to Claude. Swap the backend per-project:\n\n| Provider | Best for |\n|----------|----------|\n| **Claude Code** (default) | Full-featured agent, best reasoning |\n| **OpenAI Codex** | ChatGPT users (Plus/Pro/Business/Edu/Enterprise) |\n| **GitHub Copilot** | Teams with existing Copilot licenses |\n| **Ollama Launch** | Local/offline models behind the Claude CLI harness |\n\nSee provider guides:\n- [docs/providers/claude.md](docs/providers/claude.md)\n- [docs/providers/codex.md](docs/providers/codex.md)\n- [docs/providers/copilot.md](docs/providers/copilot.md)\n- [docs/providers/ollama-launch.md](docs/providers/ollama-launch.md)\n\n### Dashboard Configuration\n\nThe web dashboard (`make dashboard`) binds to `127.0.0.1:5001` by default (local-only access). To expose it on your network or change the port:\n\n**Via environment variables** (add to `.env`):\n```bash\nKOAN_DASHBOARD_HOST=0.0.0.0   # Bind to all interfaces\nKOAN_DASHBOARD_PORT=5001      # Custom port (optional)\n```\n\n**Via command-line arguments**:\n```bash\npython3 koan/app/dashboard/__main__.py --host 0.0.0.0 --port 8080\n```\n\n**Security note**: The dashboard has no authentication. Only expose it to trusted networks.\n\n## Architecture\n\nThe full current-design reference lives under [docs/architecture/](docs/architecture/), with durable design rules in [docs/design/decisions.md](docs/design/decisions.md).\n\n```\nkoan/\n  app/                    # Core Python modules (24K LOC)\n    run.py                #   Main agent loop\n    awake.py              #   Messaging bridge\n    missions.py           #   Mission parsing & lifecycle\n    mission_runner.py     #   Execution pipeline\n    skill_dispatch.py     #   Direct skill execution\n    memory_manager.py     #   Per-project memory isolation\n    usage_tracker.py      #   Budget tracking & mode selection\n    provider/             #   CLI provider abstraction\n      claude.py           #     Claude Code CLI\n      codex.py            #     OpenAI Codex CLI\n      copilot.py          #     GitHub Copilot CLI\n      ollama_launch.py    #     Ollama Launch (local models via ollama)\n  skills/                 # Pluggable command system (44 core skills)\n  system-prompts/         # All LLM prompts (20 files, no inline prompts)\n  templates/              # Dashboard Jinja2 templates\n  tests/                  # 4500+ tests (pytest)\ninstance/                 # Your private data (gitignored)\n  soul.md                 #   Agent personality — this is who Kōan is\n  missions.md             #   Task queue\n  config.yaml             #   Behavioral settings\n  memory/                 #   Persistent context across sessions\n  journal/                #   Daily logs (YYYY-MM-DD/project.md)\n```\n\n**Design principle:** Code is generic and open source. Instance data is private. Fork the repo, write your own soul.\n\n## Make Targets\n\n| Target | Description |\n|--------|-------------|\n| `make install` | Interactive CLI onboarding wizard |\n| `make koan` | Start Kōan + terminal dashboard (Status/Logs/Config/Usage) |\n| `make start` | Start full stack (agent + bridge), non-interactive |\n| `make logs` | Tail live output from all processes |\n| `make stop` | Stop all processes |\n| `make status` | Show running process status |\n| `make missions` | List the mission queue directly from the store (break-glass; works when the bridge is down) |\n| `make mission-rm sel=i1` | Remove/abort a mission by selector when the bridge is unresponsive ([docs](docs/operations/mission-cli.md)) |\n| `make dashboard` | Web UI (default: http://127.0.0.1:5001) |\n| `make test` | Run test suite |\n| `make say m=\"...\"` | Send a test message |\n| `make docker-pull-up` | Pull the prebuilt GHCR image and run in Docker (recommended) |\n| `make docker-up` | Build the image from source and run in Docker |\n| `make rename-project old=X new=Y` | Rename a project everywhere (dry-run by default, add `apply=1` to execute) |\n| `make clean` | Remove virtualenv |\n\n## Philosophy\n\nKoan was born from a simple question: *what do you do with a Claude Max subscription when you're not at your desk?*\n\nThe 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.\n\nIt 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.\n\n*The agent proposes. The human decides.*\n\n## Security\n\nKoan is designed for **local, single-user operation**. It is not a web service.\n\n- All work happens in isolated `koan/*` branches — your `main` is never modified\n- Chat tools are restricted (read-only) vs. mission tools (full access) to limit prompt injection surface\n- Dashboard binds to `localhost` only — no external access by default\n- Telegram/Slack auth uses platform-level identity verification\n\nDo not expose Koan services to the public internet. For remote access, use SSH tunnels.\n\n## Contributing\n\nKoan is open source under GPL-3.0. Contributions welcome.\n\n```bash\nmake setup\nmake test   # Run the test suite\n```\n\nCheck [CLAUDE.md](CLAUDE.md) for coding conventions and architecture details.\n\n## AI Policy\n\nThis project uses AI tools to assist development. Humans review and approve every change before it is merged. See [AI_POLICY.md](AI_POLICY.md) for details.\n\n## License\n\n[GPL-3.0](LICENSE) — Free as in freedom.\n",
  "bytes": 24554,
  "sha": "5fc1997856d043b2609096b024dd1fa13b532760c530dd3643e775454b0c6e63",
  "repo_slug": "anantys-oss/koan",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_anantys_oss_koan_specs_index_md_64bda517/readme"
}