kon-coding-agent 0.3.11

Minimal coding agent

░█░█░█▀█░█▀█
░█▀▄░█░█░█░█
░▀░▀░▀▀▀░▀░▀

Minimal coding agent harness

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,deepseek,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,deepseek,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 .

[!WARNING] Kon currently targets macOS and Linux. Windows is not tested yet.

---

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:

Tool	What it does	Why it matters
read	Read file contents with pagination and image support	Keeps file inspection structured and token-efficient
edit	Exact text replacement	Good for surgical code changes
write	Create or fully overwrite files	Good for new files or full rewrites
bash	Run shell commands	For tests, git, builds, scripts, package managers
grep	Regex search inside files	Faster and cleaner than shelling out for content search
find	Glob-based file discovery	Fast repo navigation with .gitignore awareness

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:

Tool	Purpose	How to enable
web_search	Search the web with DuckDuckGo	--extra-tools web_search,web_fetch or config
web_fetch	Fetch and extract clean page content	Usually paired with web_search

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

Feature	How it works
File reference	Type @ to fuzzy-search files and folders in the current project
Path completion	Press Tab to complete paths like ./, ../, ~, quoted paths, and absolute paths
Queued prompts	Press Enter while the agent is running to queue a follow-up prompt
Steer queue	Press Alt+Enter to queue a steer message that is processed before normal queued prompts
Queue limit	Up to 5 normal queued prompts and 5 steer messages
Model switching	Use /model to switch interactively
Session browsing	Use /resume to browse prior sessions

Slash commands

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

Command	Description
/new	Start a new conversation and reload project context
/resume	Browse and restore a saved session
/model	Switch model via picker
/session	Show session file, ids, message counts, and token stats
/compact	Compact the current conversation immediately
/handoff	Create a focused handoff into a new session
/themes	Switch UI themes
/permissions	Switch permission mode
/thinking	Switch thinking level for the current session
/notifications	Toggle notification sounds
/export	Export current session to standalone HTML
/copy	Copy the last assistant response to the clipboard
/login	Authenticate with a supported OAuth provider
/logout	Remove provider credentials
/clear	Clear the current conversation
/help	Show help and keybindings
/<custom>	Custom skills registered as slash commands, shown in the /cmd popup for manual triggering
/quit (/exit, /q)	Quit Kon

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:

Prefix	Behavior
!command	Run the command and show the result in chat
!!command	Run the command, show the result, and send the output to the LLM for follow-up

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
• DeepSeek
• 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
  • OpenAI/default: OPENAI_API_KEY only
  • DeepSeek: DEEPSEEK_API_KEY first, then OPENAI_API_KEY
  • ZhiPu/ZAI: ZAI_API_KEY first, then OPENAI_API_KEY
• 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"
kon --provider deepseek --model deepseek-v4-flash

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:

Mode	Behavior
prompt	Ask before mutating tool calls
auto	Skip approval prompts

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