A minimal terminal coding agent with a small core, strong defaults, and user-owned context.

Kon is a minimal coding agent focused on a tiny core prompt, a small built-in toolset, and project-specific context layered on top only when you want it. The default system prompt stays under 270 tokens, and even including the built-in tool descriptions and parameter schemas, the fixed harness stays at about ~1,000 tokens. The core experience is built around just 6 default tools plus 2 optional web tools.

Kon is named after the artificial soul from Bleach.

Table of Contents

• Quick Start
• Why Kon
  • Minimal by design
  • Configuration
  • Core tools
  • Extra tools
• Interactive TUI
  • Editor and navigation
  • Slash commands
  • Shell commands
  • Themes
• Sessions
  • Resume and continue
  • Handoff
  • Export and copy
  • Compaction
• Context Loading
  • AGENTS.md
  • Skills
• Providers and Models
  • OAuth and API keys
  • Local models
• Permissions
• Tool binaries
• Documentation
• Acknowledgements
• License

Quick Start

Install

uv tool install kon-coding-agent

Run

kon

usage: kon [-h] [--model MODEL]
           [--provider {azure-ai-foundry,github-copilot,openai,openai-codex,openai-responses,zhipu}]
           [--api-key API_KEY] [--base-url BASE_URL] [--continue]
           [--resume RESUME_SESSION] [--version]
           [--extra-tools EXTRA_TOOLS]

Kon TUI

options:
  -h, --help            show this help message and exit
  --model, -m MODEL     Model to use
  --provider, -p {azure-ai-foundry,github-copilot,openai,openai-codex,openai-responses,zhipu}
                        Provider to use
  --api-key, -k API_KEY
                        API key
  --base-url, -u BASE_URL
                        Base URL for API
  --continue, -c        Resume the most recent session
  --resume, -r RESUME_SESSION
                        Resume a specific session by ID (full or unique prefix)
  --version             show program's version number and exit
  --extra-tools EXTRA_TOOLS
                        Comma-separated extra tools to enable (e.g. web_search,web_fetch)

Common examples

# choose a model explicitly
kon -p openai-codex -m gpt-5.4

# continue your latest session
kon -c

# resume a specific session by id or unique prefix
kon -r 3f2a8c1b-...

# enable the optional web tools
kon --extra-tools web_search,web_fetch

Once inside Kon, you can:

# Run shell commands directly
!ls -la
!git status

# Run commands and get LLM analysis
!!grep -r "TODO" src/
!!find . -name "*.py" | head -20

Install from source

git clone https://github.com/kuutsav/kon
cd kon
uv tool install .

Why Kon

Minimal by design

Kon tries to stay small in the places that matter most:

• System prompt under 270 tokens by default
• 6 core tools for everyday coding work
• 2 optional extra tools for web lookup and content extraction
• Project instructions are externalized through AGENTS.md
• Heavily configurable defaults that you can tune around model, prompt, permissions, compaction, tools, and UI
• Useful features are borrowed selectively from other agents, like /handoff inspired by Amp

That means the default harness stays lightweight, while your actual working behavior can still become rich through project context and configuration.

If you want a coding agent you can read, understand, fork, and adapt without inheriting a giant framework, that is the point of Kon.

Configuration

Kon stores config at:

~/.kon/config.toml

It is created automatically on first run, and old schemas are migrated forward automatically when needed.

Users are recommended to customize this config based on their model, workflow, safety preferences, and UI taste. For the shipped default config with inline comments, see src/kon/defaults/config.toml.

Here is the full config shape:

[meta]
config_version = 4

[llm]
default_provider = "openai-codex"
default_model = "gpt-5.4"
default_base_url = ""
default_thinking_level = "high"
tool_call_idle_timeout_seconds = 180

[llm.auth]
openai_compat = "auto"
anthropic_compat = "auto"

[llm.system_prompt]
git_context = true
content = """You are an expert coding assistant called Kon.
..."""

[compaction]
on_overflow = "continue"
buffer_tokens = 20000

[agent]
max_turns = 500
default_context_window = 200000

[tools]
extra = ["web_search", "web_fetch"]

[ui]
theme = "gruvbox-dark"

[notifications]
enabled = true
volume = 0.5

[permissions]
mode = "prompt"

Core tools

These are enabled by default:

This is the core experience: small, predictable, and enough for most coding tasks.

Extra tools

Kon also ships optional built-in tools you can turn on when needed:

Enable them from the CLI:

kon --extra-tools web_search,web_fetch

Or in ~/.kon/config.toml:

[tools]
extra = ["web_search", "web_fetch"]

Interactive TUI

Kon is built around a terminal UI that stays simple but practical.

Editor and navigation

Slash commands

Type / at the start of the input box to see available commands.

Themes

Kon includes built-in themes and supports switching from inside the app:

• ayu
• catppuccin-frappe
• catppuccin-latte
• catppuccin-macchiato
• catppuccin-mocha
• dracula
• everforest
• flexoki
• github-dark
• github-light
• gruvbox-dark
• gruvbox-light
• kanagawa
• monokai
• nightowl
• nord
• one-dark
• one-light
• palenight
• rosepine
• solarized-dark
• solarized-light
• tokyo-day
• tokyo-night

Set one interactively with /themes, or persist it in config:

[ui]
theme = "gruvbox-dark"

Shell commands

Kon supports direct shell command execution from the input box using two prefixes:

Examples:

!ls -la              # List files in current directory
!git status          # Show git status
!python -m pytest tests/ -v  # Run tests

!!grep -r "TODO" src/    # Search for TODOs and analyze results
!!find . -name "*.py" | head -20  # Find Python files and get LLM insights

Sessions

Kon stores sessions as append-only JSONL files in:

~/.kon/sessions/

That keeps sessions easy to inspect, archive, and move around.

Resume and continue

You can restore work from the CLI or inside the TUI:

kon --continue
kon --resume <session-id>

Inside Kon:

• /resume opens an interactive session picker
• /session shows metadata and token usage
• the session picker also supports deleting old saved sessions

Handoff

/handoff <query> starts a new focused session using a synthesized handoff prompt generated from the current conversation.

This is useful when a thread has grown broad and you want a fresh, narrower working context without losing the original session.

Export and copy

• /export writes a standalone HTML transcript into the current working directory
• /copy copies the latest assistant response text to your clipboard

Compaction

Long sessions eventually fill the context window. Kon supports both:

• manual compaction via /compact
• automatic compaction on overflow

Overflow behavior is configurable:

[compaction]
on_overflow = "continue" # or "pause"
buffer_tokens = 20000

The full session history still remains on disk in the JSONL file.

Context Loading

Kon keeps the built-in harness small by moving project-specific instructions out of the fixed prompt.

AGENTS.md

Kon loads project guidance from AGENTS.md or CLAUDE.md files into the system prompt.

Load order:

1. ~/.kon/AGENTS.md
2. matching ancestor directories from git root (or home) down to the current working directory

Use these files for repo conventions, test commands, code style notes, deployment steps, or anything else you want loaded automatically.

Skills

Skills are reusable instruction packs discovered from:

• project: .kon/skills/
• global: ~/.kon/skills/

Each skill lives in its own directory with a SKILL.md file.

Example:

---
name: my-skill
description: Brief description of what this skill does
register_cmd: true  # also registers the skill in the /cmd popup for manual triggering
cmd_info: Quick action shown in slash menu
---

# My Skill

Detailed instructions for the agent...

Important fields:

• name - skill identifier
• description - used for discovery and prompt context
• register_cmd - if true, exposes the skill as a slash command and includes it in the /cmd popup for manual triggering
• cmd_info - short help text for the slash menu

Validation highlights:

• lowercase letters, numbers, and - only
• no leading/trailing -
• no --
• max length for name: 64 chars

Skills are the main way to add reusable behaviors without bloating the default harness.

Providers and Models

Kon works with hosted models and local models exposed through an OpenAI-compatible /v1 API.

Built-in provider support includes:

• GitHub Copilot
• OpenAI Codex
• OpenAI Responses / OpenAI-compatible endpoints
• Azure AI Foundry
• ZhiPu

Use /model in the TUI to switch between available configured models.

OAuth and API keys

Kon supports both OAuth login flows and direct API-key configuration.

• GitHub Copilot OAuth: run /login and choose GitHub Copilot
• OpenAI OAuth: run /login and choose OpenAI
• OpenAI-compatible providers: use OPENAI_API_KEY or provider-specific equivalents
• Azure AI Foundry: set AZURE_AI_FOUNDRY_API_KEY and AZURE_AI_FOUNDRY_BASE_URL

You can also pass credentials directly on launch:

kon --provider openai --model some-model --api-key "$OPENAI_API_KEY"

Local models

Kon works well with local models served through an OpenAI-compatible endpoint. For one-off launches, you can force unauthenticated local behavior with --openai-compat-auth none or --anthropic-compat-auth none. To make that persistent across sessions, set [llm.auth] openai_compat = "auto"|"none" and/or anthropic_compat = "auto"|"none" in ~/.kon/config.toml.

More notes, tested models, and examples live in docs/local-models.md.

Permissions

Kon supports two permission modes:

In prompt mode, non-mutating tools are allowed automatically, and some clearly read-only shell commands are also allowed.

Use /permissions to switch modes for the current session and persist the change to config.

[permissions]
mode = "prompt" # or "auto"

Tool binaries

Kon depends on a few fast CLI tools for file discovery and search:

• fd - required for fast file discovery
• ripgrep - required for fast content search

If fd or rg are missing, Kon can download them automatically.

Acknowledgements

• Kon takes significant inspiration from pi coding-agent, especially around philosophy and UI direction.
• Kon also borrows ideas from Amp, Claude Code, and other terminal coding agents.

License

MIT