Kōan User Manual

From beginner to power user — everything Kōan can do.

This manual is organized in three progressive tiers. Start with the basics, then unlock more advanced workflows as you grow comfortable.

New here? Make sure you've completed the Quick Start or Full Install Guide first. This manual assumes Kōan is already running.

Beginner — Daily Basics
Intermediate — Productivity Workflows
Power User — Advanced Configuration
Quick Reference

Beginner — Daily Basics

Everything you need to use Kōan day-to-day. If you've just installed Kōan, start here.

Your First Mission

Send a message to Kōan via Telegram (or Slack). If it looks like a task, Kōan automatically queues it as a mission:

"Audit the auth module for security issues"

For explicit control, use the /mission command:

/mission Refactor the payment service to use async/await

/mission — Queue a new mission for the agent to work on.

Usage: /mission <description>
Options:
- /mission --now <description> — Insert at the top of the queue (next to run)
- /mission [project:webapp] <description> — Target a specific project

Use cases

/mission Add input validation to the signup form — Queue a feature task
/mission --now Fix the broken CI pipeline — Urgent fix, skip the queue
/mission [project:api] Write integration tests for the /users endpoint — Target a specific project

Mission Lifecycle

Every mission flows through a simple lifecycle:

Pending  →  In Progress  →  Done ✓
                          →  Failed ✗

Pending — Queued and waiting. Kōan picks missions from the top of the queue.
In Progress — Kōan is actively working on it via Claude Code CLI.
Done — Completed successfully. Code is in a koan/* branch, often with a draft PR.
Failed — Something went wrong. Kōan logs the reason and moves on.

By default, Kōan processes one mission at a time. When idle, it picks the next pending mission automatically. For concurrent execution, see Parallel Sessions.

Chatting with Kōan

Just send a regular message — Kōan classifies it automatically. Short conversational messages get instant replies (chat mode). Task-like messages get queued as missions.

If Kōan misclassifies your message, use /chat to force chat mode:

/chat — Force a message to be treated as chat, not a mission.

Usage: /chat <message>

Use cases

/chat What do you think about using Redis for caching? — Ask for an opinion without creating a mission
/chat How's your day going? — Just talk

Managing Your Queue

/list — See all pending and in-progress missions.

Aliases: /queue, /ls

Use cases

/list — Check what's queued up before adding more work
/ls — Quick glance at the queue

/cancel — Remove a pending mission from the queue.

Usage: /cancel <number> or /cancel <keyword>
Aliases: /remove, /clear

Use cases

/cancel 3 — Cancel the 3rd pending mission
/cancel auth — Cancel the mission matching "auth"

/priority — Move a pending mission to a different position in the queue.

Usage: /priority <n> (move to top) or /priority <n> <position>

Use cases

/priority 5 — Move mission #5 to the top of the queue
/priority 3 2 — Move mission #3 to position #2

Checking Progress

/status — Get a quick overview of Kōan's state: what's running, what's queued, loop health.

Aliases: /st
Related: /ping (is the loop alive?), /usage (detailed quota), /metrics (success rates)

Use cases

/status — "Is Kōan working? What's it doing?"
/ping — Quick health check
/metrics — See mission success/failure rates

/live — See real-time progress from the currently running mission.

Aliases: /progress

Use cases

/live — Check what Kōan is doing right now during a long mission

/logs — Show the last 10 lines from run.log and awake.log, formatted in code blocks.

Use cases

/logs — Quick check of recent agent and bridge output without SSH access

/quota — Check remaining API quota (live, no cache).

Aliases: /q

Use cases

/quota — See how much API budget is left before adding heavy missions

/verbose / /silent — Toggle real-time progress updates. When verbose is on, Kōan sends progress messages as it works.

Use cases

/verbose — Turn on updates when you want to follow along
/silent — Turn off updates when you're busy (default)

Branch Isolation & Reviewing Work

Kōan never commits to main. All work happens in koan/* branches (the prefix is configurable). After completing a mission, Kōan typically:

Creates a branch like koan/refactor-payment-service
Commits changes with clear messages
Pushes the branch and creates a draft PR

Your workflow:

# See what Kōan produced
git log koan/refactor-payment-service

# Review the PR on GitHub
# Merge when you're satisfied — or ask Kōan to iterate

The agent proposes. The human decides. — You always have the final say.

Multi-Project Basics

Kōan can manage multiple projects simultaneously. It rotates between them based on queue priority and quota.

/projects — List all configured projects.

Aliases: /proj

Use cases

/projects — See which repos Kōan is managing

/focus — Lock Kōan to a single project. While focused, it only processes missions for that project and skips exploration/reflection.

Usage: /focus [duration] (default: 5 hours)
Examples: /focus, /focus 3h, /focus 2h30m

/unfocus — Exit focus mode, resume normal multi-project rotation.

Use cases

/focus — "I need all attention on the webapp for the next few hours"
/focus 1h — Short focused sprint
/unfocus — "OK, back to normal"

Intermediate — Productivity Workflows

These features turn Kōan from a task runner into a full development workflow partner.

Code Operations

/brainstorm — Decompose a broad topic into multiple linked GitHub issues grouped under a master tracking issue.

Usage: /brainstorm <topic>, /brainstorm <project> <topic>, /brainstorm <topic> --tag <label>
GitHub @mention: @koan-bot /brainstorm <topic> on an issue

Use cases

/brainstorm Improve caching strategy for API responses — Creates 3-8 sub-issues + master issue
/brainstorm koan Add observability and monitoring — Target a specific project
/brainstorm Refactor auth module --tag auth-refactor — With explicit tag for grouping

/plan — Deep-think an idea and produce a structured implementation plan as a GitHub issue.

Usage: /plan <idea>, /plan <project> <idea>, /plan <issue-url> (iterate on existing)
GitHub @mention: @koan-bot /plan <idea> on an issue

Use cases

/plan Add WebSocket support for real-time notifications — Get a phased plan before writing any code
/plan https://github.com/org/repo/issues/42 — Iterate on an existing issue's plan
/plan webapp Add rate limiting to public API endpoints — Target a specific project

/implement — Queue an implementation mission for a GitHub issue.

Usage: /implement <issue-url> [additional context]
Aliases: /impl
GitHub @mention: @koan-bot /implement on an issue

Use cases

/implement https://github.com/org/repo/issues/42 — Implement what the issue describes
/implement https://github.com/org/repo/issues/42 Focus on the backend only — Add guidance

/fix — Fix a GitHub issue end-to-end: understand, plan, test, implement, and submit a PR.

Usage: /fix <issue-url> [additional context]
GitHub @mention: @koan-bot /fix on an issue

Use cases

/fix https://github.com/org/repo/issues/99 — Full bug-fix pipeline
/fix https://github.com/org/repo/issues/99 Regression from v2.3 — Provide extra context

/review — Queue a code review for a pull request or issue.

Usage: /review <github-pr-or-issue-url> [--architecture]
Aliases: /rv
GitHub @mention: @koan-bot /review on a PR
Flags:
- --architecture — Architecture-focused review (SOLID principles, layering, coupling, abstraction boundaries)

Use cases

/review https://github.com/org/repo/pull/55 — Get a thorough code review
/rv https://github.com/org/repo/pull/55 — Same thing, shorter
/review https://github.com/org/repo/pull/55 --architecture — Architecture-focused review

/refactor — Queue a targeted refactoring mission.

Usage: /refactor <github-url-or-path>
Aliases: /rf
GitHub @mention: @koan-bot /refactor on a PR or issue

Use cases

/refactor https://github.com/org/repo/pull/60 — Refactor code in a PR
/rf https://github.com/org/repo/issues/70 — Refactor based on an issue description

PR Management

/ask — Ask a question about a GitHub PR or issue and get an AI-generated reply posted directly to the thread.

Usage: /ask <github-comment-url>
GitHub @mention: @koan-bot ask <your question> on any PR or issue

Use cases

@koan-bot ask why does this test fail? — Kōan investigates the thread context and replies on GitHub
@koan-bot ask what is the purpose of this PR? — Get a structured explanation with context summary
/ask https://github.com/org/repo/issues/42#issuecomment-123456 — Reply to a specific comment

/rebase — Rebase a PR onto its base branch.

Usage: /rebase <pr-url>
Aliases: /rb
GitHub @mention: @koan-bot /rebase on a PR

Use cases

/rebase https://github.com/org/repo/pull/42 — Resolve conflicts and update the PR

/recreate — Re-implement a PR from scratch on a fresh branch. Useful when a PR has diverged too far.

Usage: /recreate <pr-url>
Aliases: /rc
GitHub @mention: @koan-bot /recreate on a PR

Use cases

/recreate https://github.com/org/repo/pull/42 — Start fresh when rebasing won't cut it

/pr — Review and update a GitHub pull request (interactive).

Usage: /pr <pr-url>

Use cases

/pr https://github.com/org/repo/pull/55 — Review a PR and apply updates

/check — Run project health checks on a PR or issue (rebase, review, plan as needed).

Usage: /check <pr-or-issue-url>
Aliases: /inspect

Use cases

/check https://github.com/org/repo/pull/42 — Let Kōan decide what a PR needs

/gh_request — Route a natural-language GitHub request to the appropriate action.

Usage: /gh_request <github-url> <request text>
GitHub @mention: Used automatically when natural_language: true is enabled — free-form @mentions are routed here instead of failing with URL validation errors.

Use cases

/gh_request https://github.com/org/repo/pull/42 can you review this? — Classifies as /review and queues
/gh_request https://github.com/org/repo/issues/10 please fix this — Classifies as /fix and queues
@koan-bot can you rebase this PR? — Automatically routed to /gh_request when natural_language is on

Project Maintenance

/claudemd — Refresh or create a project's CLAUDE.md based on recent architectural changes.

Usage: /claudemd [project-name]
Aliases: /claude, /claude.md, /claude_md

Use cases

/claudemd webapp — Update the CLAUDE.md after a big refactor
/claudemd — Refresh for the default/focused project

/gha_audit — Scan GitHub Actions workflows for security vulnerabilities.

Usage: /gha_audit [project-name]
Aliases: /gha

Use cases

/gha_audit — Quick security check of your CI/CD pipelines
/gha_audit api — Audit a specific project's workflows

/changelog — Generate a changelog from recent commits and journal entries.

Usage: /changelog [project] [--since=YYYY-MM-DD] [--format=md|telegram]
Aliases: /changes

Use cases

/changelog — What changed recently?
/changelog webapp --since=2025-01-01 — Changes since a specific date
/changelog --format=md — Get markdown output for release notes

/done — List PRs merged in the last 24 hours across all projects.

Usage: /done [project] [--hours=N]
Aliases: /merged

Use cases

/done — What got merged today?
/done webapp — Merged PRs for a specific project
/done --hours=48 — Merged PRs in the last 2 days

Scheduling Work

Kōan supports recurring missions that automatically re-queue at set intervals.

/daily — Schedule a mission to run every day.

Usage: /daily <text> [project:<name>]

/hourly — Schedule a mission to run every hour.

Usage: /hourly <text> [project:<name>]

/weekly — Schedule a mission to run every week.

Usage: /weekly <text> [project:<name>]

/recurring — List all active recurring missions.

/cancel_recurring — Cancel a recurring mission.

Usage: /cancel_recurring <n> or /cancel_recurring <keyword>
Aliases: —

Use cases

/daily Review open PRs and summarize status [project:webapp] — Daily PR digest
/weekly Run the full test suite and report flaky tests — Weekly health check
/hourly Check CI status [project:api] — Frequent monitoring
/recurring — See what's scheduled
/cancel_recurring 2 — Stop a recurring mission

Ideas Backlog

Not ready to commit to a mission? Save it as an idea.

/idea — Add an idea to the backlog, or manage existing ideas.

Usage:
- /idea <text> — Add a new idea
- /idea <project> <text> — Add idea for a specific project
- /idea promote <n> — Promote idea #n to a mission
- /idea delete <n> — Delete idea #n
Aliases: /buffer

/ideas — List all ideas in the backlog.

Use cases

/idea Maybe we should add GraphQL support — Save for later
/ideas — Browse the backlog
/idea promote 3 — "OK, let's do idea #3"

Reflection & Journal

/reflect — Write a reflection to the shared journal. Both you and Kōan contribute to this shared space.

Usage: /reflect <observation>
Aliases: /think

Use cases

/reflect The new caching layer reduced API latency by 40% — Share an observation
/reflect I think we should prioritize mobile performance next quarter

/journal — View journal entries.

Usage: /journal [project] [date]
Aliases: /log

Use cases

/journal — Today's journal entries
/journal webapp — Journal for a specific project
/journal 2025-03-01 — Historical entries

Email Digests

/email — Check email digest status or send a test email.

Usage: /email, /email test

Use cases

/email — Check if email digests are configured
/email test — Send a test email to verify setup

Statistics

/stats — View session outcome statistics per project: success rates, mission counts, productivity trends.

Usage: /stats [project]

Use cases

/stats — Overall productivity snapshot
/stats webapp — How's Kōan doing on a specific project?

Understanding Quota Modes

Kōan automatically adapts its work intensity based on remaining API quota:

Mode	Quota	Behavior
DEEP	>40%	Strategic work, thorough exploration, comprehensive reviews
IMPLEMENT	15–40%	Focused development, quick wins, efficient execution
REVIEW	<15%	Read-only analysis, code audits, lightweight tasks
WAIT	<5%	Graceful pause until quota resets

You don't need to manage this — Kōan adjusts automatically. Use /quota to see the current mode.

Exploration Mode

When exploration is enabled, Kōan may autonomously explore a project's codebase between missions — discovering improvements, noting issues, and building context.

/explore — Enable exploration or show status.

Usage: /explore [project|all|none]
Aliases: /exploration

/noexplore — Disable exploration for a project.

Usage: /noexplore [project]

Use cases

/explore webapp — Let Kōan explore the webapp codebase
/explore all — Enable exploration for all projects
/noexplore — Disable exploration (focus on missions only)

Workflow Example: Feature from Idea to PR

Here's a typical multi-step workflow combining several commands:

1. /idea Add rate limiting to the public API          # Save the idea
2. /idea promote 1                                     # Ready to work on it
3. /plan Add rate limiting to the public API           # Get a structured plan
4. /implement https://github.com/org/repo/issues/123   # Implement the plan
5. /review https://github.com/org/repo/pull/124        # Review the result
6. # Merge the PR on GitHub when satisfied

Power User — Advanced Configuration

Unlock Kōan's full potential with advanced configuration and extensibility features.

Parallel Sessions

Kōan can work on multiple missions simultaneously using git worktrees for isolation. Each parallel session runs in its own worktree with a dedicated branch, so sessions never interfere with each other.

How It Works

When parallel sessions are enabled, Kōan can pick up additional pending missions while one is already running. Each session gets:

Isolated worktree — a separate checkout of the repository under .worktrees/
Dedicated branch — koan/session-<id> branches created automatically
Independent subprocess — a Claude Code process running in the worktree

Sessions are coordinated through a persistent registry (instance/sessions.json) with file-level locking for process safety.

Configuration

Add max_parallel_sessions to your instance/config.yaml:

# Parallel session configuration
max_parallel_sessions: 2    # Number of concurrent sessions (1-5, default: 2)

Set to 1 to disable parallel execution and use the classic sequential mode.

Shared Dependencies

To avoid duplicating heavy dependency directories across worktrees, configure shared_deps in your project's projects.yaml:

projects:
  webapp:
    path: ~/Code/webapp
    shared_deps:
      - node_modules
      - .venv

These directories are symlinked from the main project into each worktree, saving disk space and setup time.

Note: Shared deps are best used for read-only caches. If a mission's build step modifies dependencies (e.g., npm install), it may affect other sessions sharing the same directory.

Monitoring

Parallel sessions appear in the standard status commands:

/status — Shows count of active parallel sessions
/live — Shows progress of all running sessions

Session output is captured to temporary files and collected when each session completes.

Cleanup

Worktrees and session branches are automatically cleaned up when a session finishes (success or failure). On startup, Kōan also recovers stale sessions from previous crashes — marking them as failed and removing their worktrees.

To manually clean up orphaned worktrees:

# From the project directory
git worktree list    # See all worktrees
git worktree prune   # Remove stale references

Deep Exploration

/ai — Queue an AI exploration mission. Runs as a full agent mission with codebase access — deeper and more thorough than /magic.

Usage: /ai [project]
Aliases: /ia

Use cases

/ai webapp — Deep dive into a project, discover insights, suggest improvements
/ai — Explore the default/focused project

/magic — Instant creative exploration. Quick single-turn analysis without queuing a mission.

Usage: /magic [project]

Use cases

/magic — "Surprise me — what's interesting in this codebase?"
/magic api — Quick creative scan of a specific project

/sparring — Start a strategic sparring session. This is about thinking, not code — Kōan challenges your assumptions and pushes your ideas.

Use cases

/sparring — "Challenge me on my architecture decisions"

Configuration Deep-Dive

All behavioral config lives in instance/config.yaml. Key settings:

# Work intensity
max_runs_per_day: 10          # Max missions per day
interval_seconds: 60          # Seconds between mission checks

# Model selection
models:
  mission: null               # Default (sonnet) for mission work
  chat: null                  # Default for chat replies
  lightweight: haiku          # Quick tasks (formatting, picking)

# Budget thresholds
budget:
  warn_at_percent: 20         # Warn when quota drops below
  stop_at_percent: 5          # Stop working below this

# Tool restrictions (limit what the agent can do)
tools:
  allowed: []                 # Whitelist (empty = all allowed)
  blocked: []                 # Blacklist specific tools

# Start on pause — boot directly into pause mode
# Useful for scheduled launches (cron, launchd) where you want
# the stack running but idle until you explicitly /resume.
start_on_pause: false

# Schedule (when Kōan is allowed to work)
schedule:
  timezone: UTC
  active_hours: "00:00-23:59" # Default: always active

# Skill execution limits
skill_timeout: 3600           # Max seconds for /fix, /implement, /incident
skill_max_turns: 200          # Max agentic turns for heavy skills

# Prompt guard (content safety)
prompt_guard: true            # Enable prompt injection detection

See instance.example/config.yaml for all available options.

Per-Project Overrides

Projects are configured in projects.yaml at KOAN_ROOT. Each project can override defaults:

defaults:
  git_auto_merge:
    enabled: false
    strategy: squash

projects:
  webapp:
    path: ~/Code/webapp
    cli_provider: claude       # CLI provider override
    models:
      mission: opus            # Use Opus for this project
    tools:
      blocked: [WebSearch]     # Restrict certain tools
    git_auto_merge:
      enabled: true            # Auto-merge for this project
      strategy: squash
    authorized_users:          # Who can trigger via GitHub @mention
      - username1

Key per-project settings:

cli_provider — claude, copilot, or local
models — Override model selection per role
tools — Restrict available tools
git_auto_merge — Auto-merge completed PRs (strategy: squash/merge/rebase)
authorized_users — GitHub users allowed to trigger via @mention
exploration — Enable/disable autonomous exploration

Custom Skills

Kōan's skill system is fully extensible. Install skills from Git repos or create your own.

Install from Git:

/skill install https://github.com/your-org/koan-skills.git
/skill update <scope>
/skill remove <scope>

Create your own: Add a SKILL.md file in instance/skills/<scope>/<name>/:

---
name: my-skill
scope: my-scope
description: What this skill does
audience: bridge
commands:
  - name: mycommand
    description: One-line description
    usage: /mycommand <args>
handler: handler.py
---

The handler follows a simple pattern:

def handle(ctx):
    # ctx.args — command arguments
    # ctx.project — current project
    # ctx.instance_dir — instance directory path
    return "Response message"  # or None for no reply

For prompt-only skills (no handler), put the prompt text after the YAML frontmatter — it's sent directly to Claude.

Scaffold a skill from a description:

Instead of writing SKILL.md and handler.py by hand, use /scaffold_skill to generate them:

/scaffold_skill myteam deploy Deploy to production with rollback support

This invokes Claude to produce a valid SKILL.md + handler.py stub in instance/skills/myteam/deploy/, validated against the parser before writing. Restart the bridge to load the new skill.

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

GitHub @mention Integration

Ten skills can be triggered by commenting @koan-bot <command> on GitHub issues and PRs:

Skill	GitHub trigger
`/brainstorm`	`@koan-bot /brainstorm <topic>` on an issue
`/implement`	`@koan-bot /implement` on an issue
`/fix`	`@koan-bot /fix` on an issue
`/review`	`@koan-bot /review` on a PR
`/rebase`	`@koan-bot /rebase` on a PR
`/recreate`	`@koan-bot /recreate` on a PR
`/refactor`	`@koan-bot /refactor` on a PR or issue
`/plan`	`@koan-bot /plan <idea>` on an issue
`/profile`	`@koan-bot /profile` on a PR or issue

Setup requires configuring github_nickname and github_commands_enabled in config.yaml. See docs/github-commands.md for full setup and configuration details.

CLI Providers

Kōan supports multiple CLI backends. Configure globally via KOAN_CLI_PROVIDER env var or per-project in projects.yaml.

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

Language Preference

/language — Set or reset the reply language.

Usage: /language <lang>, /language reset
Aliases: /lng

/french / /english — Quick language switches.

Aliases: /fr, /francais, /français / /en, /anglais

Use cases

/fr — Switch to French replies
/en — Switch back to English
/language reset — Use default language

System Management

/pause — Pause mission processing. Kōan stays running but won't pick up new missions.

Aliases: /sleep

Use cases

/pause — Temporarily stop mission work without shutting down
Resume with /resume when ready

/resume — Resume mission processing after a pause (manual or automatic).

Aliases: /work, /awake, /run, /start

Use cases

/resume — Unpause after a manual /pause or quota exhaustion

/shutdown — Shutdown both the agent loop and the messaging bridge.

Use cases

/shutdown — Gracefully stop everything (e.g., before system maintenance)

/update — Pull the latest Kōan code from upstream and restart.

Aliases: /upgrade
Only restarts when new code is pulled. Use /restart to force a restart without pulling.

Use cases

/update — Get the latest features and fixes

/restart — Restart both agent and bridge processes without pulling new code.

Use cases

/restart — Force a restart when Kōan is already up to date but you need a fresh start

/snapshot — Export memory state to a portable snapshot file for backup or migration.

Use cases

/snapshot — Back up Kōan's memory before a major change

Memory System

Kōan maintains persistent memory across sessions through several interconnected files:

memory/summary.md — Global summary of learnings across all projects
memory/projects/<name>/ — Per-project learnings and context
journal/YYYY-MM-DD/project.md — Daily logs of what Kōan did
soul.md — Agent personality definition (see Personality Customization)

Memory is automatically compacted over time. Kōan uses it to build context for each mission, remembering past decisions, patterns, and mistakes.

Personality Customization

Edit instance/soul.md to define Kōan's personality. This file shapes how Kōan communicates, what tone it uses, and what personality traits it exhibits. It's loaded into every interaction.

The design principle: code is generic and open source; instance data (including personality) is private. Fork the repo, write your own soul.

Auto-Update

Kōan can automatically check for and apply updates from upstream. Configure in config.yaml:

auto_update:
  enabled: true
  check_interval: 3600    # Seconds between checks
  notify: true             # Notify via Telegram when updating

See docs/auto-update.md for details.

Adding New Projects

/add_project — Clone a GitHub repo and add it to the workspace.

Usage: /add_project <github-url> [name]
Aliases: —

Use cases

/add_project https://github.com/org/new-repo — Add a new repo for Kōan to manage
/add_project https://github.com/org/new-repo myproject — Add with a custom name

Removing Projects

/delete_project — Remove a project from the workspace.

Usage: /delete_project <project-name>
Aliases: /delete, /del

Use cases

/delete_project myrepo — Remove a project directory and its projects.yaml entry
/del myrepo — Same, using short alias

Performance Profiling

/profile — Queue a performance profiling mission for a project.

Usage: /profile <project-name-or-pr-url>
Aliases: /perf, /benchmark
GitHub @mention: @koan-bot /profile on a PR or issue

Use cases

/profile webapp — Profile the webapp project for performance issues
/profile https://github.com/org/repo/pull/42 — Profile changes in a PR

Tech Debt Scan

/tech_debt — Scan a project for duplicated code, complex functions, testing gaps, and infrastructure issues. Produces a prioritized debt register saved to project learnings, and optionally queues the top improvement missions.

Usage: /tech_debt [project-name] [--no-queue]
Aliases: /td, /debt

Use cases

/tech_debt koan — Scan the koan project for tech debt
/td webapp --no-queue — Scan without queuing follow-up missions
/debt — Scan the default project

Dead Code Scan

/dead_code — Scan a project for unused imports, functions, classes, variables, and dead branches. Produces a certainty-classified report saved to project memory, and optionally queues the top removal missions.

Usage: /dead_code [project-name] [--no-queue]
Aliases: /dc

Use cases

/dead_code koan — Scan the koan project for unused code
/dc webapp --no-queue — Scan without queuing follow-up missions
/dead_code — Scan the default project

Incident Triage

/incident — Triage a production error from a stack trace or log snippet. Kōan will parse the error, identify the root cause, propose a fix with tests, and submit a draft PR.

Usage: /incident <error text or stack trace>

Use cases

/incident TypeError: Cannot read property 'id' of undefined at UserService.getUser (user.js:42) — Paste a stack trace and get a fix

Web Dashboard

Run make dashboard to start a local web UI on port 5001. The dashboard provides:

Real-time status overview
Mission queue management
Chat interface
Journal browsing

The dashboard binds to localhost only — not accessible from the network.

Deployment

For advanced deployment scenarios, see the existing documentation:

Quick Reference

All commands at a glance. Tier: B = Beginner, I = Intermediate, P = Power User.

Command	Aliases	Tier	Description
`/mission <text>`	—	B	Queue a new mission (`--now` for top priority)
`/list`	`/queue`, `/ls`	B	List pending and in-progress missions
`/cancel <n>`	`/remove`, `/clear`	B	Cancel a pending mission
`/priority <n>`	—	B	Reorder a pending mission in the queue
`/status`	`/st`	B	Quick status overview
`/ping`	—	B	Check if the agent loop is alive
`/usage`	—	B	Detailed quota and progress
`/metrics`	—	B	Mission success rates and reliability stats
`/live`	`/progress`	B	Show live progress of current mission
`/logs`	—	B	Show last 10 lines from run and awake logs
`/quota`	`/q`	B	Check LLM quota (live)
`/chat <msg>`	—	B	Force chat mode (bypass mission detection)
`/verbose`	—	B	Enable real-time progress updates
`/silent`	—	B	Disable real-time progress updates
`/projects`	`/proj`	B	List configured projects
`/focus [duration]`	—	B	Lock agent to one project
`/unfocus`	—	B	Exit focus mode
`/brainstorm <topic>`	—	I	Decompose topic into linked sub-issues + master issue
`/plan <desc>`	—	I	Create a structured implementation plan
`/implement <issue>`	`/impl`	I	Implement a GitHub issue
`/fix <issue>`	—	I	Full bug-fix pipeline (understand → plan → test → fix → PR)
`/review <PR> [--architecture]`	`/rv`	I	Review a pull request
`/refactor <desc>`	`/rf`	I	Targeted refactoring mission
`/ask <comment-url>`	—	I	Ask a question about a PR/issue — posts AI reply to GitHub
`/rebase <PR>`	`/rb`	I	Rebase a PR onto its base branch
`/recreate <PR>`	`/rc`	I	Re-implement a PR from scratch
`/pr <PR>`	—	I	Review and update a GitHub PR
`/check <url>`	`/inspect`	I	Run project health checks on a PR/issue
`/gh_request <url> <text>`	—	I	Route natural-language GitHub request to the right skill
`/claudemd [project]`	`/claude`, `/claude.md`, `/claude_md`	I	Refresh a project's CLAUDE.md
`/gha_audit [project]`	`/gha`	I	Audit GitHub Actions for security issues
`/changelog [project]`	`/changes`	I	Generate changelog from commits/journal
`/daily <text>`	—	I	Schedule a daily recurring mission
`/hourly <text>`	—	I	Schedule an hourly recurring mission
`/weekly <text>`	—	I	Schedule a weekly recurring mission
`/recurring`	—	I	List all recurring missions
`/cancel_recurring <n>`	`/cancel_recurring`	I	Cancel a recurring mission
`/idea <text>`	`/buffer`	I	Add to the ideas backlog
`/ideas`	—	I	List all ideas
`/reflect <msg>`	`/think`	I	Write a reflection to the shared journal
`/journal`	`/log`	I	View journal entries
`/email`	—	I	Email digest status or test
`/stats [project]`	—	I	Session outcome statistics
`/done [project]`	`/merged`	I	List PRs merged in the last 24 hours
`/explore [project]`	`/exploration`	I	Enable/show exploration mode
`/noexplore [project]`	—	I	Disable exploration mode
`/ai [project]`	`/ia`	P	Queue an AI exploration mission
`/magic [project]`	—	P	Instant creative exploration
`/sparring`	—	P	Strategic sparring session
`/language <lang>`	`/lng`	P	Set reply language
`/french`	`/fr`, `/francais`, `/français`	P	Switch to French
`/english`	`/en`, `/anglais`	P	Switch to English
`/pause`	`/sleep`	P	Pause mission processing
`/resume`	`/work`, `/awake`, `/run`, `/start`	P	Resume mission processing
`/shutdown`	—	P	Shutdown all processes
`/update`	`/upgrade`	P	Update Kōan and restart
`/restart`	—	P	Restart processes (no code pull)
`/snapshot`	—	P	Export memory state
`/add_project <url>`	`/add_project`	P	Add a project from GitHub
`/delete_project <name>`	`/delete`, `/del`	P	Remove a project from workspace
`/profile <project>`	`/perf`, `/benchmark`	P	Performance profiling mission
`/tech_debt [project]`	`/td`, `/debt`	P	Scan project for tech debt
`/dead_code [project]`	`/dc`	P	Scan for unused code
`/incident <error>`	—	P	Triage a production error
`/scaffold_skill <scope> <name> <desc>`	`/scaffold`, `/new_skill`	P	Generate SKILL.md + handler.py for a new custom skill

Skills marked with GitHub @mention support: /brainstorm, /plan, /implement, /fix, /review, /rebase, /recreate, /refactor, /profile, /gh_request. See GitHub Commands for details.

This manual covers all 41 core skills. For the full command reference with tabular format, see docs/skills.md. For skill authoring, see koan/skills/README.md.

FilesExpand file tree

user-manual.md

Latest commit

History

user-manual.md

File metadata and controls

Kōan User Manual

Table of Contents

Beginner — Daily Basics

Your First Mission

Mission Lifecycle

Chatting with Kōan

Managing Your Queue

Checking Progress

Branch Isolation & Reviewing Work

Multi-Project Basics

Intermediate — Productivity Workflows

Code Operations

PR Management

Project Maintenance

Scheduling Work

Ideas Backlog

Reflection & Journal

Email Digests

Statistics

Understanding Quota Modes

Exploration Mode

Workflow Example: Feature from Idea to PR

Power User — Advanced Configuration

Parallel Sessions

How It Works

Configuration

Shared Dependencies

Monitoring

Cleanup

Deep Exploration

Configuration Deep-Dive

Per-Project Overrides

Custom Skills

GitHub @mention Integration

CLI Providers

Language Preference

System Management

Memory System

Personality Customization

Auto-Update

Adding New Projects

Removing Projects

Performance Profiling

Tech Debt Scan

Dead Code Scan

Incident Triage

Web Dashboard

Deployment

Quick Reference