Content
# Kolega Code
**A terminal coding agent where the model writes its own multi-agent workflows.**
[](https://pypi.org/project/kolega-code/)
[](https://pypi.org/project/kolega-code/)
[](https://github.com/kolega-ai/kolega-code/actions/workflows/ci.yml)
[](https://github.com/kolega-ai/kolega-code/actions/workflows/ci.yml)
[](https://kolega-ai.github.io/kolega-code/)
[](CHANGELOG.md)
Kolega Code is a local-first terminal coding agent. For work that is too broad
for one agent loop, its **Gigacode** engine has the model write a Python program
that orchestrates multiple sub-agents. The runtime then executes that program.
## Gigacode: model-authored orchestration
For a repo-wide review, a migration, or a plan with independent workstreams, the
model writes an orchestration program instead of delegating workers one at a
time. The program can combine parallel phases, pipelines, adversarial
verification, judge panels, and synthesis gates to fit the task. The runtime
saves the script so it can be inspected and run again.
Claude Code uses the same model-authored approach for its dynamic workflows
(ultracode). Kolega Code provides an open, provider-agnostic implementation
whose runtime source is available in this repository.
The runtime journals each completed agent call to disk. Resume is content-keyed
rather than positional: when you use `resume_from_run_id`, calls with unchanged
semantic inputs replay from the journal at zero token cost. This still works if
the script was edited or reordered, and it works across sessions and process
restarts.
Read [how gigacode works](how-gigacode-works.md) for the architecture, or an
[unedited model-authored workflow](examples/parallel-code-review.py) with its
full provenance and execution record.
## How it works
The model investigates your repo, then writes a Python program against a small
runtime API (`agent`, `parallel`, `pipeline`, `phase`, `budget`). The runtime
enforces concurrency caps, an agent-count backstop, and token-budget accounting.
It dispatches typed sub-agents, including read-only investigators, coders, and
browser agents, whose activity streams into the TUI's sub-agent inspector.
As the run progresses, the runtime writes the script, per-call results,
transcripts, and final result to disk. An interrupted or budget-capped run keeps
its journal and can be resumed, with unchanged calls replaying free. The
mechanics, guarantees, and limitations are documented in
[how-gigacode-works.md](how-gigacode-works.md).
## The rest of the agent
Gigacode is off by default. Enable it with `/gigacode on`. For focused changes,
use Kolega Code as an ordinary terminal coding agent:
- **Plan/Build modes:** read-only Plan mode for investigation and a reviewable
task list, Build mode to implement (`Shift+Tab` to switch). In Plan mode,
workflow sub-agents are forced read-only too.
- **Repo tools:** read and search code, create files, apply precise edits, and
inspect session changes/diffs.
- **Terminal execution:** run shell commands with streamed output and
project-level permission controls.
- **Web search and browsing:** DuckDuckGo by default with no key; Firecrawl,
Tavily, and SearXNG configurable; direct URL fetch; a Playwright-powered
browser agent for interactive sites.
- **MCP servers:** connect `streamable_http`, `sse`, and `stdio` MCP servers
(including OAuth-enabled HTTP servers) as permission-gated tools.
- **Interactive or scriptable:** Textual TUI with queued follow-ups, one-shot
`kolega-code ask` with JSON output, session list/export/resume, `doctor`.
- **Editor integration:** drive the full agent from Zed or VS Code over the
Agent Client Protocol — streamed responses, tool cards, diffs, permission
prompts, plan/build approval, session restore, slash commands, and sub-agent
transcripts ([docs](https://kolega-ai.github.io/kolega-code/editor-integration/)).
- **Extensibility:** agent skills, project prompt-template overrides
([docs](https://kolega-ai.github.io/kolega-code/configuration/prompt-overrides/)),
lifecycle hooks, persistent project permission rules.
- **Local-first state:** sessions, settings, permissions, OAuth tokens, and
API-key settings stay on your machine with restrictive permissions where
applicable.
## Editor integration (ACP)
`kolega-code acp` serves the Agent Client Protocol, so Zed and VS Code can host
the full agent — including permissions, plan/build modes, and sub-agent
transcripts. Configure Zed with:
```json
{
"agent_servers": {
"Kolega Code": {
"command": "/absolute/path/to/bin/kolega-code",
"args": ["acp", "--permission-mode", "ask"]
}
}
}
```
Use an absolute binary path: a bare `kolega-code` resolves to whatever is on the
editor's `PATH`, so an installed release can shadow a dev checkout. Full setup
for Zed, VS Code, and other ACP clients is in the
[editor integration docs](https://kolega-ai.github.io/kolega-code/editor-integration/).
## Quick start
**1. Install** with the script:
```bash
curl -fsSL https://kolega.dev/install-kolega-code.sh | sh
```
Or with [uv](https://docs.astral.sh/uv/) (or `pip`):
```bash
uv tool install kolega-code
# or: pip install kolega-code
```
Verify the install:
```bash
kolega-code --version
```
**2. Start a session** in your project:
```bash
kolega-code .
```
**3. Connect a model.** Complete the first-run wizard with ChatGPT sign-in or an
API key. Later, open Settings from the sidebar or with `/settings`. Use
`Shift+Tab` to switch between **Plan** and **Build** mode, or run `/gigacode on`
when a task is broad enough for fan-out.
Resume a previous conversation:
```bash
kolega-code . --resume # latest session
kolega-code . --resume <id> # a specific Resume ID from `sessions list`
```
## Two ways to use it
| Mode | Command | Best for |
| --- | --- | --- |
| **Interactive TUI** | `kolega-code .` | Day-to-day development, exploration, orchestration |
| **One-shot** | `kolega-code ask "…"` | Scripting, automation, quick questions, CI |
Helper commands for sessions and setup:
```bash
kolega-code ask "summarize this repository" --project .
kolega-code sessions list --project .
kolega-code doctor --project .
```
## Models and routing
Kolega Code can route models by role. You can use a strong long-context model
for the main loop, a faster model for utility calls, and a dedicated model for
extended thinking. Per-agent-role overrides are available for planning,
building, investigation, general, and browser agents. A Gigacode workflow can
also pin cheaper models to individual calls with `model_override`, allowing one
model to write the orchestration while cheaper models run its agents.
Supported model providers:
- Anthropic
- OpenAI API
- OpenAI via ChatGPT subscription sign-in
- Google
- Groq
- Together.ai
- Fireworks.ai
- xAI / Grok
- DashScope / Qwen
- OpenRouter (gateway to 250+ tool-capable models)
- Moonshot / Kimi
- DeepSeek
- Z.AI / GLM Coding Plan
- Kimi Coding Plan
- Ollama Cloud
- local Llama
With a paid **ChatGPT** plan (Plus, Pro, or Business), `/login chatgpt` runs
OpenAI models without a separate API key; tokens are stored locally (chmod `600`)
and refreshed automatically. See
[Sign in with ChatGPT](https://kolega-ai.github.io/kolega-code/configuration/sign-in-with-chatgpt/).
Web search backends include DuckDuckGo (the default, with no key), Firecrawl,
Tavily, and self-hosted SearXNG. Choose one in Settings or with
`KOLEGA_CODE_WEB_SEARCH_BACKEND`.
See [Providers & Models](https://kolega-ai.github.io/kolega-code/configuration/providers-and-models/)
for model IDs, role configuration, API-key variables, and thinking-effort options.
## Configuration
Set provider, model, and API keys from onboarding or the Settings editor, or via
environment variables and flags for non-interactive use:
```bash
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 and model explicitly
or save them in Settings. Local session state lives under your platform's state
directory unless `KOLEGA_CODE_STATE_DIR` is set. See the
[Configuration docs](https://kolega-ai.github.io/kolega-code/configuration/settings-and-api-keys/)
for the full story.
## Requirements
- **Python 3.11+**
- An **API key**, ChatGPT sign-in, or local model for at least one supported model provider
- A terminal that supports a modern TUI (most do)
## Documentation
This repo includes the [Gigacode architecture document](how-gigacode-works.md)
and an [unedited model-authored example workflow](examples/parallel-code-review.py).
Full documentation lives at **[kolega-ai.github.io/kolega-code](https://kolega-ai.github.io/kolega-code/)**:
- [Gigacode user guide](https://kolega-ai.github.io/kolega-code/gigacode/)
- [Quick Start](https://kolega-ai.github.io/kolega-code/getting-started/quick-start/)
- [CLI overview](https://kolega-ai.github.io/kolega-code/cli/overview/)
- [How it works & concepts](https://kolega-ai.github.io/kolega-code/concepts/how-it-works/)
- [Configuration](https://kolega-ai.github.io/kolega-code/configuration/settings-and-api-keys/)
## Project resources
- [Documentation](https://kolega-ai.github.io/kolega-code/)
- [Releases](https://github.com/kolega-ai/kolega-code/releases)
- [Changelog](CHANGELOG.md)
- [Contributing](CONTRIBUTING.md)
- [Security policy](SECURITY.md)
- [Issue tracker](https://github.com/kolega-ai/kolega-code/issues)
- [Discord community](https://discord.gg/kaS8PKKp4)
## Contributing
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup,
running the test suite, and building the docs site. Please report security issues
privately per [SECURITY.md](SECURITY.md).
## Join the community
Building something with Kolega Code, hit a rough edge, or want to shape where
Gigacode goes next? Come talk to us.
[](https://discord.gg/kaS8PKKp4)
**→ [Join the Kolega Code Discord](https://discord.gg/kaS8PKKp4)** — share workflows,
get help, and hear about releases first.
Connection Info
You Might Also Like
No recommendations available