Kongen

AI coding agent for your terminal — reads, writes, edits files and runs commands using free LLM APIs.

⚠️ Beta Software — Kongen is currently in active development and is not yet stable. Features may change, bugs may exist, and breaking changes can happen between versions. We are working hard to reach a stable release. Use in production at your own risk and always review file changes before approving them.

What is Kongen?

Kongen is a terminal-based AI coding assistant that can read, write, and edit files in your project — just by talking to it. It uses free-tier APIs from Groq, Mistral, Cerebras, and OpenRouter, automatically falling back between providers if one is rate-limited.

No subscriptions. No credit card. Just add a free API key and start coding.

╰▶ Read my package.json and tell me what dependencies are outdated
╰▶ Add input validation to src/routes/auth.js
╰▶ Create a debounce utility in src/utils/debounce.ts
╰▶ Run the tests and fix any failures

Requirements

• Node.js v18 or higher
• At least one free API key (see Providers)

Installation

Install globally via npm:

npm install -g kongen

Verify the install:

kongen --version

Quick Start

1. Initialize your project

Navigate to any project folder and run:

cd my-project
kongen --init

This creates a .env file in your current directory:

# Kongen API Keys — add at least one
GROQ_API_KEY=
MISTRAL_API_KEY=
CEREBRAS_API_KEY=
OPENROUTER_API_KEY=

2. Add at least one API key

Get a free key from any of these providers (no credit card required):

| Provider | Free Tier | Sign Up | |---|---|---| | Groq | 14,400 req/day · fastest | https://console.groq.com | | Mistral | 1M tokens/day | https://console.mistral.ai | | Cerebras | 100K tokens/day · ultra fast | https://cloud.cerebras.ai | | OpenRouter | Free models available | https://openrouter.ai |

3. Start Kongen

kongen

Global Setup (use kongen anywhere)

To use Kongen across all your projects without a .env in each folder, create a global config:

# macOS / Linux
mkdir -p ~/.kongen
echo "GROQ_API_KEY=your_key_here" > ~/.kongen/.env

# Windows (PowerShell)
mkdir "$env:USERPROFILE\.kongen"
"GROQ_API_KEY=your_key_here" | Out-File "$env:USERPROFILE\.kongen\.env"

Kongen looks for .env in this order:

1. Current directory
2. Parent directory
3. ~/.kongen/.env (global fallback)

Usage

Once started, just type naturally. Kongen has full filesystem access in your current working directory.

Example prompts

# Understand your codebase
╰▶ Give me an overview of this project structure

# Read and explain
╰▶ Read src/auth.js and explain how authentication works

# Make changes
╰▶ Add rate limiting to the /api/login route in src/routes/auth.js

# Create new files
╰▶ Create a reusable Modal component in src/components/Modal.tsx

# Run commands
╰▶ Run npm test and fix any failing tests

# Debug
╰▶ Search for all TODO comments in the codebase

Commands

| Command | Description | |---|---| | /help | Show all available commands | | /status | Session stats, token usage, provider info | | /providers | List all configured providers and their status | | /history | View conversation history | | /context | Inspect context size breakdown | | /compact | Prune old tool results to free up context | | /undo | Revert the last file write, edit, or delete | | /cwd <path> | Change the working directory | | /clear | Reset conversation and start fresh | | /exit | Quit Kongen |

Providers

Kongen supports multiple providers and automatically falls back if one fails or is rate-limited. Configure as many as you want — more providers means more reliability.

| Provider | Default Model | Tool Use | Speed | Context | |---|---|---|---|---| | Groq | llama-3.3-70b-versatile | ✅ | ⚡⚡⚡ | unlimited | | Mistral | mistral-small-latest | ✅ | ⚡⚡ | unlimited | | OpenRouter | openai/gpt-oss-120b:free | ✅ | ⚡ | 60k chars | | Cerebras | llama3.1-8b | ❌ | ⚡⚡⚡ | 16k chars |

Cerebras is used for conversational replies only (no file tools) due to its lack of tool-call support.

Override default models

Add these to your .env to use a different model for any provider:

KONGEN_GROQ_MODEL=llama-3.3-70b-versatile
KONGEN_MISTRAL_MODEL=mistral-small-latest
KONGEN_CEREBRAS_MODEL=llama3.1-8b
KONGEN_OPENROUTER_MODEL=openai/gpt-oss-120b:free

File Tools

Kongen has access to the following tools. All write operations show a diff and ask for your approval before making changes.

| Tool | Description | Approval | |---|---|---| | read_file | Read any file | — | | write_file | Create or overwrite a file | ✅ diff + confirm | | edit_file | Replace an exact string in a file | ✅ diff + confirm | | list_files | List files in a directory | — | | search_files | Search for a pattern across files | — | | run_command | Run a shell command | — | | delete_file | Delete a file | ✅ confirm |

Configuration Reference

Full list of supported .env variables:

# API Keys
GROQ_API_KEY=
MISTRAL_API_KEY=
CEREBRAS_API_KEY=
OPENROUTER_API_KEY=

# Model overrides (optional)
KONGEN_GROQ_MODEL=llama-3.3-70b-versatile
KONGEN_MISTRAL_MODEL=mistral-small-latest
KONGEN_CEREBRAS_MODEL=llama3.1-8b
KONGEN_OPENROUTER_MODEL=openai/gpt-oss-120b:free

Known Limitations (Beta)

We are actively working on these. Contributions and bug reports are welcome.

• Provider fallback — rate limits and context size errors are handled automatically, but edge cases may still cause unexpected failures
• Large files — files over ~20k tokens may exceed provider context limits; use /compact to manage context
• Streaming — some providers do not support streaming and will fall back to a single response dump
• Windows paths — path resolution on Windows has known edge cases with deeply nested directories
• No persistent memory — conversation history is in-memory only and lost when you exit
• Tool approval UX — the diff viewer for large file rewrites can be hard to read in some terminals

If you run into issues, please open an issue and include your Node.js version, OS, and the provider you were using.

Troubleshooting

No API keys configured error

Make sure your .env file exists and has at least one key filled in. Run kongen --init to create the template.

Rate limited on every request

You've hit the free tier limit for the day. Either wait until the limit resets or add keys for additional providers so Kongen can fall back automatically.

kongen: command not found

The global npm bin directory may not be in your PATH. Run:

npm config get prefix
# Add the /bin subfolder of that path to your PATH

Response cuts off or context too large

Run /compact to prune old tool results from the context, or /clear to start a fresh conversation.

License

MIT © Kongen

See LICENSE for full text.