kolega-code 0.9.0__tar.gz → 0.11.0__tar.gz

{kolega_code-0.9.0 → kolega_code-0.11.0}/.env.example

@@ -1,5 +1,13 @@
-# Local test credentials. Copy this file to `.env` and fill only the keys you need.
-# `.env` is ignored by git; do not commit real secrets.
+# Developer/test credentials for this repository.
+#
+# Installed Kolega Code does NOT automatically load a target project's `.env`
+# for its own provider/model configuration. For normal CLI use, save keys in the
+# Settings tab or export environment variables in the shell that launches
+# `kolega-code`.
+#
+# This sample exists for repository-local development and live integration tests.
+# Copy it to `.env` only in this repo, fill only the keys you need, and never
+# commit real secrets.
 
 ANTHROPIC_API_KEY=
 OPENAI_API_KEY=

kolega_code-0.11.0/.github/workflows/ci.yml

@@ -0,0 +1,204 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, ready_for_review]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  changes:
+    name: Detect changed files
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      coverage-badge-only: ${{ steps.detect.outputs.coverage-badge-only }}
+    steps:
+      - name: Detect coverage-badge-only change
+        id: detect
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            files=$(gh api "repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files" --paginate --jq '.[].filename')
+          elif [ "${{ github.event_name }}" = "push" ]; then
+            files=$(gh api "repos/${{ github.repository }}/compare/${{ github.event.before }}...${{ github.sha }}" --jq '.files[].filename')
+          else
+            echo "coverage-badge-only=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "Changed files:"
+          echo "$files"
+
+          file_count=$(printf '%s\n' "$files" | sed '/^$/d' | wc -l | tr -d ' ')
+          if [ "$file_count" = "1" ] && [ "$files" = "docs/src/assets/coverage.svg" ]; then
+            echo "coverage-badge-only=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "coverage-badge-only=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  tests:
+    name: Python ${{ matrix.python-version }}
+    needs: changes
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Skip coverage-badge-only change
+        if: needs.changes.outputs.coverage-badge-only == 'true'
+        run: echo "Skipping Python checks for coverage badge-only change."
+
+      - name: Checkout
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        uses: actions/checkout@v5
+
+      - name: Setup Python
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup uv
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install dependencies
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        run: uv sync --extra dev --frozen
+
+      - name: Run pre-commit hooks
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        run: uv run pre-commit run --all-files --show-diff-on-failure
+
+      - name: Run fast tests with coverage
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        run: ./run_tests.sh --coverage
+
+      - name: Upload coverage report
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        uses: actions/upload-artifact@v6
+        with:
+          name: coverage-xml-python-${{ matrix.python-version }}
+          path: coverage.xml
+          if-no-files-found: error
+
+  coverage-badge:
+    name: Update coverage badge
+    needs: [changes, tests]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main' && needs.changes.outputs.coverage-badge-only != 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Download Python 3.11 coverage report
+        uses: actions/download-artifact@v8
+        with:
+          name: coverage-xml-python-3.11
+          path: coverage-artifact
+
+      - name: Generate coverage badge
+        run: |
+          uv run genbadge coverage -i coverage-artifact/coverage.xml -o docs/src/assets/coverage.svg
+          python - <<'PY'
+          from pathlib import Path
+
+          badge = Path("docs/src/assets/coverage.svg")
+          badge.write_text(badge.read_text().rstrip("\n") + "\n")
+          PY
+
+      - name: Verify coverage badge PR token
+        env:
+          COVERAGE_BADGE_PR_TOKEN: ${{ secrets.COVERAGE_BADGE_PR_TOKEN }}
+        run: |
+          if [ -z "$COVERAGE_BADGE_PR_TOKEN" ]; then
+            echo "::error::Set the COVERAGE_BADGE_PR_TOKEN repository secret to a trusted bot/user token."
+            exit 1
+          fi
+
+      - name: Create coverage badge pull request
+        id: cpr
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ secrets.COVERAGE_BADGE_PR_TOKEN }}
+          add-paths: docs/src/assets/coverage.svg
+          commit-message: "chore: update coverage badge"
+          committer: "${{ vars.COVERAGE_BADGE_COMMITTER || 'github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>' }}"
+          author: "${{ vars.COVERAGE_BADGE_AUTHOR || 'github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>' }}"
+          branch: chore/update-coverage-badge
+          delete-branch: true
+          title: "chore: update coverage badge"
+          body: |
+            Automated coverage badge update from CI after tests passed on `main`.
+
+      - name: Enable auto-merge for coverage badge PR
+        if: steps.cpr.outputs.pull-request-number != '' && steps.cpr.outputs.pull-request-operation != 'none'
+        env:
+          GH_TOKEN: ${{ secrets.COVERAGE_BADGE_PR_TOKEN }}
+        run: |
+          gh pr merge "${{ steps.cpr.outputs.pull-request-number }}" --auto --squash --delete-branch
+
+  dependency-audit:
+    name: Dependency audit
+    needs: changes
+    runs-on: ubuntu-latest
+    steps:
+      - name: Skip coverage-badge-only change
+        if: needs.changes.outputs.coverage-badge-only == 'true'
+        run: echo "Skipping dependency audit for coverage badge-only change."
+
+      - name: Checkout
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        uses: actions/checkout@v5
+
+      - name: Setup Python
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Setup uv
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Audit locked dependencies
+        if: needs.changes.outputs.coverage-badge-only != 'true'
+        run: uv audit --locked

{kolega_code-0.9.0 → kolega_code-0.11.0}/.gitignore

@@ -7,7 +7,7 @@ __pycache__/
 .env
 .env.*
 !.env.example
-.kolega/permissions.json
+.kolega/
 dist/
 build/
 *.egg-info/

{kolega_code-0.9.0 → kolega_code-0.11.0}/CHANGELOG.md

@@ -6,6 +6,41 @@ This project uses GitHub Releases for detailed generated release notes. This fil
 
 ## Unreleased
 
+## 0.11.0 - 2026-06-26
+
+### Added
+
+- Added queued follow-up messages in the TUI so users can submit additional
+  prompts while an active turn is still running.
+
+### Changed
+
+- Moved task-list status into the sidebar and refined sidebar presentation.
+- Updated documentation and positioning copy for gigacode and queued follow-up
+  messages.
+
+## 0.10.0 - 2026-06-25
+
+### Added
+
+- Added a session changes inspector to the TUI that shows git diffs for the
+  current session, renders added files as diffs, presents an empty state, and
+  hides captured edit events.
+- Added project prompt overrides, including variable rendering, override status
+  shown at startup, validation, and selective dump support.
+
+### Fixed
+
+- Preserved Ollama Cloud reasoning provider metadata.
+- Ignored project `.dotenv` files when loading model config.
+- Stabilized terminal rendering artifacts in the TUI.
+- Restored the generated root CLI help.
+- Surfaced prompt override render errors.
+
+### Changed
+
+- Split the LLM specs module into a package for maintainability.
+
 ## 0.9.0 - 2026-06-24
 
 ### Added

{kolega_code-0.9.0 → kolega_code-0.11.0}/CONTRIBUTING.md

@@ -101,6 +101,31 @@ npm run build
 
 Use `npm run dev` from `docs/` for local documentation development.
 
+## Maintainer automation
+
+The CI workflow updates `docs/src/assets/coverage.svg` by opening an automated pull
+request. Configure the repository secret `COVERAGE_BADGE_PR_TOKEN` with a trusted
+bot or maintainer token instead of `GITHUB_TOKEN`; GitHub requires manual approval
+before workflows run on pull requests opened by `github-actions[bot]`.
+
+Use a fine-grained personal access token or GitHub App token scoped to this
+repository with:
+
+- Contents: read and write
+- Pull requests: read and write
+- Metadata: read-only, included automatically
+
+The token owner should be a trusted repository member or bot account. Do not use
+a first-time external contributor account, and never commit the token value.
+
+Optional repository variables can customize the Git commit identity used for the
+badge update commit:
+
+- `COVERAGE_BADGE_AUTHOR`
+- `COVERAGE_BADGE_COMMITTER`
+
+Use values like `Name <email@example.com>`.
+
 ## Pull Requests
 
 - Keep changes focused and avoid unrelated refactors.

{kolega_code-0.9.0 → kolega_code-0.11.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.9.0
-Summary: Local-first AI coding agent for the terminal
+Version: 0.11.0
+Summary: Multi-agent coding in the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/
 Project-URL: Repository, https://github.com/kolega-ai/kolega-code
@@ -82,7 +82,7 @@ Description-Content-Type: text/markdown
 
 # Kolega Code
 
-**An AI coding agent that runs in your terminal — local-first, model-agnostic, plan-then-build.**
+**Multi-agent coding in the terminal.**
 
 [![PyPI version](https://img.shields.io/pypi/v/kolega-code)](https://pypi.org/project/kolega-code/)
 [![Python versions](https://img.shields.io/pypi/pyversions/kolega-code)](https://pypi.org/project/kolega-code/)
@@ -92,41 +92,65 @@ Description-Content-Type: text/markdown
 [![Docs](https://img.shields.io/badge/docs-kolega--ai.github.io-blue)](https://kolega-ai.github.io/kolega-code/)
 [![Changelog](https://img.shields.io/badge/changelog-keep%20up-blue)](CHANGELOG.md)
 
-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.
+Kolega Code is a local-first terminal coding agent built for work that is too wide
+for one loop: fan out specialized sub-agents with **Gigacode**, route different
+models to different jobs, search the web, drive a browser, and keep sessions,
+settings, permissions, and credentials on your machine.
 
 ![Kolega Code in action](docs/src/assets/demo.gif)
 
-## 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](https://kolega-ai.github.io/kolega-code/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.
+## Built for work one agent cannot cover
+
+Most terminal agents are strongest when one model can reason through one task at a
+time. Kolega Code keeps that familiar workflow, then adds orchestration for broad work:
+large audits, sweeping migrations, cross-file checks, adversarial reviews, and
+implementation plans whose pieces can run independently.
+
+With [Gigacode](https://kolega-ai.github.io/kolega-code/gigacode/), Kolega Code can:
+
+- **Fan out many sub-agents at once.** Split a wide codebase review by package,
+  assign independent implementation tasks, or run checks across many directories in
+  parallel.
+- **Use real workflow shapes.** The agent can generate parallel phases, pipelines,
+  loops, judge panels, and synthesis steps instead of only delegating one task at a
+  time.
+- **Keep orchestration visible.** Workflow phase headers and progress lines appear
+  in the transcript; the sub-agent inspector shows each agent's live trajectory.
+- **Save inspectable artifacts.** Each run keeps the generated workflow script,
+  result files, a Markdown transcript, raw JSONL, a resume journal, and debug
+  sub-agent transcripts under Kolega Code's state directory.
+- **Run in either mode.** In Plan mode, workflow sub-agents stay read-only for
+  parallel investigation. In Build mode, they can use the full coding toolset.
+- **Resume interrupted runs.** Finished workflow steps are journaled so a deliberate
+  resume does not have to restart the whole fan-out.
+
+Use normal chat for focused changes. Turn on Gigacode when the problem is broad
+enough that one serial agent pass would be the bottleneck.
+
+## Features
+
+- **Gigacode orchestration:** parallel, pipelined, looped, judged, and synthesized
+  multi-agent workflows with saved artifacts and resume support.
+- **Specialized sub-agents:** planning, building/coder, investigation, general, and
+  browser agents, with live activity tracking in the TUI.
+- **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.
+- **Plan/build workflow:** use read-only Plan mode for investigation and a reviewable
+  task list, then Build mode to implement.
+- **Web search and browsing:** DuckDuckGo works by default with no key; Firecrawl,
+  Tavily, and SearXNG are configurable search backends. Kolega Code can also fetch URLs
+  directly and use a Playwright-powered browser agent for interactive sites.
+- **Model routing:** choose provider/model combinations, set thinking effort, split
+  long-context/fast/thinking roles, and override models per agent role.
+- **Interactive or scriptable:** use the Textual TUI, queue follow-up prompts
+  while the agent is working, run `kolega-code ask`, request JSON output,
+  list/export/resume sessions, and diagnose setup with `doctor`.
+- **Extensibility:** add agent skills, override prompts with project templates, run
+  lifecycle hooks, and persist project permission rules.
+- **Local-first state:** sessions, settings, permissions, OAuth tokens, and API-key
+  settings stay on your machine with restrictive permissions where applicable.
 
 ## Quick start
 
@@ -155,8 +179,9 @@ kolega-code --version
 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.
+**3. Add a provider key.** Open the **Settings** tab to pick a provider/model and
+save your API key. 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:
 
@@ -169,7 +194,7 @@ kolega-code . --resume <id>       # a specific thread or session
 
 | Mode | Command | Best for |
 | --- | --- | --- |
-| **Interactive TUI** | `kolega-code .` | Day-to-day development, exploration, pair-programming |
+| **Interactive TUI** | `kolega-code .` | Day-to-day development, exploration, orchestration |
 | **One-shot** | `kolega-code ask "…"` | Scripting, automation, quick questions, CI |
 
 There are also helper commands for managing sessions and checking your setup:
@@ -180,25 +205,60 @@ kolega-code sessions list --project .
 kolega-code doctor --project .
 ```
 
-## Bring your own model
+## Supported providers
+
+Kolega Code supports a broad model-provider catalog and lets you route models by
+role instead of forcing one model to do every job.
+
+Supported model providers:
+
+- Anthropic
+- OpenAI API
+- OpenAI via ChatGPT subscription sign-in
+- Google
+- Groq
+- Together.ai
+- Fireworks.ai
+- xAI / Grok
+- DashScope / Qwen
+- Moonshot / Kimi
+- DeepSeek
+- Z.AI / GLM Coding Plan
+- Kimi Coding Plan
+- Ollama Cloud
+- local Llama
+
+Supported web-search backends:
 
-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](https://kolega-ai.github.io/kolega-code/configuration/providers-and-models/).
+- DuckDuckGo — default, no key required
+- Firecrawl
+- Tavily
+- SearXNG — self-hosted option
+
+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.
+
+## Model routing
+
+Kolega Code can assign different models to different operational roles: a strong
+long-context model for the main coding loop, a faster model for utility calls, and
+a dedicated model for extended thinking. You can also override models per agent
+role — planning, building, investigation, general, and browser — so wide workflows
+can use cheaper models where they fit and stronger models where they matter.
 
 ## 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
+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](https://kolega-ai.github.io/kolega-code/configuration/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:
+Set your provider, model, and API keys from the **Settings** tab in the UI, or via
+environment variables and flags for non-interactive use:
 
 ```bash
 export KOLEGA_CODE_PROVIDER=deepseek
@@ -206,20 +266,28 @@ 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
+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](https://kolega-ai.github.io/kolega-code/configuration/settings-and-api-keys/)
 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.
+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.
+
+Projects can override Kolega Code's base prompts with uppercase Markdown templates
+in `.kolega/prompts/`. Generate editable starters with Jinja replacement tags using
+`/prompts dump` in the TUI or `kolega-code prompts dump --project .` in a terminal.
+To dump only selected starters, pass prompt names such as `coder`, `planning`, or
+`compaction` (filename aliases like `CODER.md` work too). Validate existing
+overrides with `/prompts validate` or `kolega-code prompts validate --project .`.
 
 ## Requirements
 
 - **Python 3.11+**
-- An **API key** for at least one supported provider
+- 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
@@ -242,9 +310,9 @@ Full documentation lives at **[kolega-ai.github.io/kolega-code](https://kolega-a
 
 ## 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).
+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).
 
 ## License