kolega-code 0.8.0

Local-first AI coding agent for the terminal

Kolega Code

An AI coding agent that runs in your terminal — local-first, model-agnostic, plan-then-build.

Point Kolega Code at a project directory and it opens an interactive UI where you talk to an agent that can read and edit your code, run shell commands, search the codebase, browse the web, and dispatch specialized sub-agents to get work done.

It's local-first: the agent operates on your actual filesystem and terminal, and your sessions, settings, and API keys stay on your own machine.

Why Kolega Code

• Plans before it builds. A read-only Plan mode produces a reviewable plan and a shared task list before anything changes; Build mode implements it. Toggle with Shift+Tab.
• Orchestrates many agents. For larger jobs, the main agent dispatches specialized sub-agents (investigation, browser, coding, general) and can fan them out in parallel for broad audits, large migrations, or implementing a plan's independent parts at once.
• Local-first by design. It works on your real files and terminal; sessions, settings, and credentials live on your machine, not in someone else's cloud.
• Bring your own model. Talks to a range of providers and lets you assign different models to different roles.

What it does

• Reads and edits your code. Opens files, searches across the codebase, creates new files, and applies precise edits.
• Runs commands. Executes shell commands and watches their output in a dedicated terminal view.
• Plans before it builds. Plan mode investigates and proposes; Build mode executes.
• Searches and browses the web. The agent can search for relevant pages, fetch URLs directly, or use the built-in browser agent (powered by Playwright) when a task needs site interaction.
• Dispatches sub-agents. Hands work off to specialized agents and tracks their activity live.
• Orchestrates workflows. With gigacode, it fans out many sub-agents in parallel.
• Works non-interactively too. Run a single prompt with kolega-code ask, get JSON output, and save or resume sessions.

Quick start

1. Install with the script:

curl -fsSL https://kolega.dev/install-kolega-code.sh | sh

Or with uv (or pip):

uv tool install kolega-code
# or: pip install kolega-code

Verify the install:

kolega-code --version

2. Start a session in your project:

kolega-code .

3. Add a provider key. Open the Settings tab to pick a provider and model and save your API key. Then press Shift+Tab anytime to switch between Plan and Build mode.

Resume a previous conversation:

kolega-code . --resume            # latest session
kolega-code . --resume <id>       # a specific thread or session

Two ways to use it

Mode	Command	Best for
Interactive TUI	kolega-code .	Day-to-day development, exploration, pair-programming
One-shot	kolega-code ask "…"	Scripting, automation, quick questions, CI

There are also helper commands for managing sessions and checking your setup:

kolega-code ask "summarize this repository" --project .
kolega-code sessions list --project .
kolega-code doctor --project .

Bring your own model

Kolega Code talks to a range of LLM providers — including Anthropic, OpenAI, Google, Moonshot, and DeepSeek — and lets you assign different models to different roles: a strong long-context model for coding, a fast cheap model for small utility calls, and one for extended "thinking". See Providers & Models.

Sign in with ChatGPT

If you have a paid ChatGPT plan (Plus, Pro, or Business), you can use it to run OpenAI models instead of a separate API key. Run /login chatgpt in the TUI, complete the browser sign-in, and Kolega Code switches to the OpenAI (ChatGPT subscription) provider (default gpt-5.5). Tokens are stored locally (chmod 600) and refreshed automatically; /logout chatgpt removes them. See Sign in with ChatGPT.

Configuration

Set your provider, model, and API keys from the Settings tab in the UI, or via environment variables and flags for non-interactive use:

export KOLEGA_CODE_PROVIDER=deepseek
export DEEPSEEK_API_KEY=...
kolega-code ask "summarize this repository" --project . --provider deepseek --model deepseek-v4-pro

API key variables only provide credentials — pick a provider/model explicitly or save one in Settings. Local session state lives under your platform's state directory unless KOLEGA_CODE_STATE_DIR is set. See the Configuration docs for the full story.

The web_search tool uses DuckDuckGo by default without a key. To choose another backend, set it in Settings or export KOLEGA_CODE_WEB_SEARCH_BACKEND as firecrawl, tavily, or searxng; use FIRECRAWL_API_KEY, TAVILY_API_KEY, or SEARXNG_BASE_URL as needed.

Requirements

• Python 3.11+
• An API key for at least one supported provider
• A terminal that supports a modern TUI (most do)

Documentation

Full documentation lives at kolega-ai.github.io/kolega-code:

• Quick Start
• CLI overview
• How it works & concepts
• Configuration

Contributing

Contributions are welcome. See CONTRIBUTING.md for local setup, running the test suite, and building the docs site. Please report security issues privately per SECURITY.md.

License

Released under the MIT License.