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.
- 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.
- 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.
1. Install with the script:
curl -fsSL https://kolega.dev/install-kolega-code.sh | shOr with uv (or pip):
uv tool install kolega-code
# or: pip install kolega-codeVerify the install:
kolega-code --version2. 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| 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 .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.
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.
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-proAPI 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.
- Python 3.11+
- An API key for at least one supported provider
- A terminal that supports a modern TUI (most do)
Full documentation lives at kolega-ai.github.io/kolega-code:
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.
Released under the MIT License.