kolega-code 0.3.2__tar.gz → 0.5.0__tar.gz

{kolega_code-0.3.2 → kolega_code-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.3.2
+Version: 0.5.0
 Summary: Local-first AI coding agent for the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/

{kolega_code-0.3.2 → kolega_code-0.5.0}/docs/astro.config.mjs

@@ -44,7 +44,7 @@ export default defineConfig({
         {
           label: "Getting Started",
           items: [
-            { label: "Introduction", slug: "getting-started/introduction" },
+            { label: "Introduction", link: "/" },
             { label: "Installation", slug: "getting-started/installation" },
             { label: "Quick Start", slug: "getting-started/quick-start" },
           ],
@@ -89,6 +89,14 @@ export default defineConfig({
           label: "Skills",
           items: [{ label: "Agent Skills", slug: "skills" }],
         },
+        {
+          label: "Hooks",
+          items: [{ label: "Lifecycle Hooks", slug: "hooks" }],
+        },
+        {
+          label: "Gigacode",
+          items: [{ label: "Workflow Orchestration", slug: "gigacode" }],
+        },
         {
           label: "How It Works",
           items: [

{kolega_code-0.3.2 → kolega_code-0.5.0}/docs/src/content/docs/concepts/agents.md

@@ -27,9 +27,16 @@ findings. The available dispatch targets include:
 - `dispatch_coding_agent` — hand off a self-contained coding task.
 - `dispatch_general_agent` — a general-purpose helper.
 
-Sub-agent activity is reported live: in the TUI you'll see it in the conversation
-and the **Logs** tab; with `ask` it surfaces as events (on stderr in plain mode, or
-as `event` objects with `--json`).
+When [gigacode](../../gigacode/) is enabled, the main agent can also orchestrate
+**many** of these sub-agents at once through a workflow — running them in parallel
+or in pipelines and collecting the results.
+
+Sub-agent activity is reported live. In the TUI each sub-agent gets a live card in
+the conversation, and pressing `Ctrl+G` opens the
+[sub-agent inspector](../../tui/interface/#sub-agent-inspector) — a full-screen view
+of every sub-agent's complete trajectory: its thinking, tool calls, and results.
+Lifecycle events also appear in the **Logs** tab. With `ask`, sub-agent activity
+surfaces as events (on stderr in plain mode, or as `event` objects with `--json`).
 
 ## Modes vs. agents
 

kolega_code-0.5.0/docs/src/content/docs/gigacode.mdx

@@ -0,0 +1,108 @@
+---
+title: Gigacode
+description: Dynamic multi-agent workflow orchestration — fan out many sub-agents with one command.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+**Gigacode** lets the agent take on work that's too big for a single pass by
+**orchestrating many sub-agents at once**. When it's enabled and a task calls for
+it, the agent writes a small workflow that fans sub-agents out in parallel,
+pipelines them, or loops over them — then collects the results.
+
+It's built for work that's wide rather than deep:
+
+- Broad audits and multi-file reviews.
+- Large migrations or mechanical changes spread across many files.
+- Judge panels and adversarial verification, where several agents cross-check each
+  other.
+- Implementing a plan whose parts are independent, in parallel.
+
+For a quick question or a small, focused edit, the agent just does it directly —
+gigacode is for genuine fan-out.
+
+## Turning it on
+
+Gigacode is **off by default**. Toggle it with the `/gigacode`
+[slash command](../tui/slash-commands/):
+
+| Command | Effect |
+| --- | --- |
+| `/gigacode` | Toggle gigacode on or off |
+| `/gigacode on` | Enable workflow orchestration for the session |
+| `/gigacode off` | Disable it |
+
+Once on, it stays on for the session, and the agent decides when a task is worth
+orchestrating. It works in both [Build and Plan modes](../tui/modes/) — see
+[Behavior and safety](#behavior-and-safety) for how each differs.
+
+## What you'll see
+
+When the agent runs a workflow, the transcript shows **phase headers** and short
+**progress lines** as it works. Each sub-agent it launches appears in the
+[sub-agent inspector](../tui/interface/#sub-agent-inspector) — press `Ctrl+G` to
+watch every agent's live trajectory, grouped by phase.
+
+## How it works
+
+Under the hood, the agent authors a short **Python script** and runs it with a
+single `run_workflow` tool call. The script uses a handful of primitives:
+
+| Primitive | What it does |
+| --- | --- |
+| `agent(...)` | Dispatch one sub-agent and get its result back |
+| `parallel([...])` | Run several sub-agents at once and wait for all of them |
+| `pipeline(items, ...)` | Run each item through a series of stages independently |
+| `phase(...)` / `log(...)` | Report progress to the UI |
+
+You don't write these scripts — the agent does. A sketch of what it generates:
+
+```python
+# Review three areas in parallel, then synthesize.
+phase("Review")
+findings = await parallel([
+    (lambda area=area: agent(f"Review the {area} module for bugs"))
+    for area in ["auth", "api", "cli"]
+])
+return findings
+```
+
+<Aside type="note">
+Workflows are deterministic and **resumable**. Each run is saved under Kolega
+Code's state directory (`workflows/<run-id>/`) with its script, a journal, and each
+sub-agent's transcript, so an interrupted run can pick up where it left off instead
+of redoing finished work.
+</Aside>
+
+## Behavior and safety
+
+How workflow sub-agents behave depends on the mode you're in.
+
+**Plan mode** — every workflow sub-agent is **read-only** (an investigation agent),
+no matter what the workflow asks for. Use it to fan out parallel research and
+synthesis while planning; it never edits your code.
+
+**Build mode** — sub-agents have the full toolset and can edit files and run
+commands.
+
+<Aside type="caution" title="Workflows run unattended">
+In Build mode, workflow sub-agents run in **auto permission mode** — they execute
+shell commands and file edits **without prompting**, even when your session is set
+to `ask`. A workflow is a deliberate batch operation, and pausing dozens of
+parallel agents for individual approvals isn't practical. Keep this in mind before
+running a workflow for risky changes.
+</Aside>
+
+A few more guarantees:
+
+- Workflow sub-agents don't touch your [task list](../tui/modes/) — only the main
+  agent manages it, so agents running in parallel can't clobber it.
+- Concurrency is capped, and there's a hard ceiling on the total number of agents a
+  single workflow can spawn, as a runaway-loop backstop.
+
+## See also
+
+- [Build & Plan Modes](../tui/modes/) — how modes shape what agents can do.
+- [Agents](../concepts/agents/) — the sub-agent types a workflow draws on.
+- [Slash Commands](../tui/slash-commands/) — the full command reference.
+- [Interface Tour](../tui/interface/#sub-agent-inspector) — the sub-agent inspector.

kolega_code-0.5.0/docs/src/content/docs/hooks.md

@@ -0,0 +1,247 @@
+---
+title: Hooks
+description: Run shell commands, Python callables, or LLM checks on agent lifecycle events to observe, block, or modify what the agent does.
+---
+
+**Hooks** let you attach handlers to the agent's **lifecycle events** — points like
+"before a tool runs", "a prompt was submitted", or "the agent is about to stop". A hook
+can **observe** (log, notify), **block** (deny a tool, end a turn, keep the agent
+working), or **modify** (rewrite a tool's input or output, inject context).
+
+This is how you add guardrails ("never run `rm -rf`"), automation ("format files after
+every edit"), and quality gates ("don't stop until the tests pass") without changing the
+agent itself.
+
+## Where hooks live
+
+Hooks are declared in JSON, in two places that are **merged** (global first, project last):
+
+- **Global / user:** `hooks.json` in the Kolega Code state directory — always active. The
+  state directory is platform-specific:
+  - macOS: `~/Library/Application Support/kolega-code/hooks.json`
+  - Linux: `$XDG_STATE_HOME/kolega-code/hooks.json` (defaults to `~/.local/state/kolega-code/hooks.json`)
+  - Windows: `%LOCALAPPDATA%\kolega-code\hooks.json`
+
+  Override the location with the `KOLEGA_CODE_STATE_DIR` environment variable or the
+  `--state-dir <dir>` flag (the file is then `<dir>/hooks.json`).
+- **Project:** `<project>/.kolega/hooks.json` — alongside `permissions.json`. Because a
+  project file can run arbitrary commands from a cloned repo, project hooks are
+  **disabled until you trust the project** (see [Trust](#trusting-project-hooks)).
+
+Both files use the same shape:
+
+```json
+{
+  "schema_version": 1,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "execute_terminal_command|run_command_tracked",
+        "hooks": [
+          { "type": "command", "command": "./.kolega/guard-bash.sh", "timeout": 30 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- The `hooks` map is keyed by **event name**.
+- Each entry has a **`matcher`** and a list of **hook handlers**.
+- `matcher` is tested against the tool name for tool events (or a source string for other
+  events): `""` or `"*"` matches everything; `"Edit|Write"` is an exact-name OR list;
+  anything else is a regular expression (e.g. `"mcp__.*"`).
+- Handler lists from the global and project files are concatenated, so the global handler
+  sees the action first and the project handler last.
+
+## Lifecycle events
+
+| Event | When it fires | What a "block" does |
+|---|---|---|
+| `SessionStart` | The agent session begins | Advisory; can inject starting context |
+| `UserPromptSubmit` | You submit a prompt, before the agent sees it | Ends the turn; the reason is shown as a warning |
+| `PreToolUse` | Before a tool runs (after the permission gate) | Denies the tool; the reason is returned to the agent as a tool error, so it can adjust |
+| `PostToolUse` | After a tool succeeds (and on failure) | Ends the turn; the reason is shown as a warning |
+| `PreCompact` | Before the conversation is compacted | Advisory |
+| `Stop` | The agent is about to finish its turn | Keeps the agent working; the reason becomes its next instruction |
+| `SubagentStop` | A dispatched sub-agent finished | Advisory; can annotate the result the parent sees |
+| `Notification` | A permission prompt is about to be shown | Advisory (desktop notifications, sounds) |
+| `SessionEnd` | The session ends | Advisory (cleanup, final logging) |
+
+Hooks can also **modify** rather than block:
+
+- `PreToolUse` can return `updatedInput` to rewrite the tool's arguments.
+- `PostToolUse` can return `updatedToolOutput` to replace what the model sees, or
+  `additionalContext` to append to it.
+- `SessionStart` / `UserPromptSubmit` can return `additionalContext` to inject text.
+
+## Hook types
+
+### `command` — run a shell program
+
+The event is sent as JSON on **stdin**. The hook communicates back through its exit code:
+
+- **exit 0** — success. Optional JSON on stdout controls behavior:
+  ```json
+  {
+    "hookSpecificOutput": {
+      "permissionDecision": "deny",
+      "permissionDecisionReason": "rm -rf is not allowed here",
+      "updatedInput": { "command": "ls" },
+      "updatedToolOutput": "…",
+      "additionalContext": "…"
+    },
+    "systemMessage": "shown to the user",
+    "continue": false
+  }
+  ```
+- **exit 2** — block. Whatever the hook wrote to **stderr** becomes the reason.
+- **any other code** — a non-blocking error: it is logged and the action proceeds.
+
+```json
+{ "type": "command", "command": "./.kolega/format.sh", "timeout": 30 }
+```
+
+Commands run with the project directory as the working directory and are split like a
+shell argument list (no shell features such as pipes — call a script if you need them).
+
+### `python` — run an in-process callable
+
+Point at an importable `module.path:function`. It receives a `LifecycleEvent` and returns
+a `HookOutcome` (or a dict with the same fields). Runs in the agent's process — best for
+first-party checks.
+
+```json
+{ "type": "python", "callable": "myproject.hooks:block_secrets", "timeout": 15 }
+```
+
+```python
+from kolega_code.hooks import HookOutcome
+
+def block_secrets(event):
+    inputs = event.payload.get("tool_input", {})
+    if "AWS_SECRET" in str(inputs):
+        return HookOutcome.deny("Refusing to write a secret to disk.")
+    return HookOutcome.empty()
+```
+
+### `prompt` and `agent` — let an LLM decide
+
+For judgment calls rather than deterministic rules. Both return a yes/no decision as
+`{"ok": true}` (allow) or `{"ok": false, "reason": "…"}` (block); the per-event meaning of
+a block is the same as the table above.
+
+- **`prompt`** sends your prompt plus the event data to a model (the fast model by
+  default; `"model"` may be `"fast"`, `"long"`, or `"thinking"`). Use `$EVENT` in the
+  prompt to interpolate the event JSON.
+
+  ```json
+  {
+    "type": "prompt",
+    "prompt": "Have all of the user's requested tasks been completed? $EVENT",
+    "model": "fast",
+    "timeout": 30
+  }
+  ```
+
+- **`agent`** spawns a full sub-agent that can read files, search the code, and run
+  commands to verify a condition before answering. Heavier, with a longer default timeout.
+  Because an agent hook uses tools, it is **not allowed on `PreToolUse`/`PostToolUse`**
+  (that would recurse); use it on `Stop`, `SubagentStop`, `UserPromptSubmit`, or the
+  session events.
+
+  ```json
+  {
+    "type": "agent",
+    "prompt": "Run the test suite. Only report ok:true if every test passes.",
+    "timeout": 120
+  }
+  ```
+
+  Tool calls made by an agent hook do **not** re-trigger tool hooks, so there is no
+  infinite loop.
+
+## Examples
+
+**Block dangerous shell commands (project, command hook):**
+
+```json
+{
+  "schema_version": 1,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "execute_terminal_command|run_command|run_command_tracked",
+        "hooks": [{ "type": "command", "command": "./.kolega/deny-rm.sh" }]
+      }
+    ]
+  }
+}
+```
+
+**Don't stop until the tests pass (prompt hook):**
+
+```json
+{
+  "schema_version": 1,
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [{
+          "type": "prompt",
+          "prompt": "Based on the conversation, did the agent finish ALL requested work AND leave the tests passing? $EVENT"
+        }]
+      }
+    ]
+  }
+}
+```
+
+**Verify tests actually pass before stopping (agent hook):**
+
+```json
+{
+  "schema_version": 1,
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [{
+          "type": "agent",
+          "prompt": "Run the project's test command and confirm it exits cleanly.",
+          "timeout": 120
+        }]
+      }
+    ]
+  }
+}
+```
+
+## Trusting project hooks
+
+A project's `.kolega/hooks.json` can run arbitrary commands, so it is **ignored until you
+explicitly trust the project**. Global/user hooks are always trusted.
+
+When an untrusted project defines hooks, Kolega Code tells you and runs only the global
+hooks. To enable the project's hooks, launch with:
+
+```bash
+kolega-code --trust-hooks          # TUI
+kolega-code ask "…" --trust-hooks  # non-interactive
+```
+
+Trust is recorded once (per resolved project path) in your user settings, so future runs
+in that project enable its hooks automatically.
+
+## Safety and behavior notes
+
+- **Failure is isolated.** A hook that crashes, times out, or prints garbage is logged and
+  the action proceeds — a broken hook never wedges the agent. Only a clean `exit 2`,
+  `permissionDecision: "deny"`, or `ok: false` blocks.
+- **Each handler has a `timeout`** (seconds). On timeout the process is killed and treated
+  as a non-blocking error.
+- **Tool hooks apply to sub-agents too**, so a `PreToolUse` guard also covers tools used by
+  dispatched sub-agents.
+- A `Stop` hook can force the agent to keep working only a bounded number of times per
+  turn, so a misbehaving "don't stop" hook cannot loop forever.

kolega_code-0.3.2/docs/src/content/docs/getting-started/introduction.md → kolega_code-0.5.0/docs/src/content/docs/index.mdx

@@ -24,8 +24,11 @@ and your sessions, settings, and API keys are stored on your own machine.
 - **Dispatches sub-agents.** For larger tasks, the main agent can hand off to
   specialized agents (investigation, browser, coding, general) and track their
   activity live.
+- **Orchestrates workflows.** With [gigacode](gigacode/), the agent can fan out
+  many sub-agents in parallel — for broad audits, large migrations, or
+  implementing a plan's independent parts at once.
 - **Works non-interactively too.** Run a single prompt with
-  [`kolega-code ask`](../../cli/ask/), get JSON output, and save or resume
+  [`kolega-code ask`](cli/ask/), get JSON output, and save or resume
   sessions.
 
 ## Two ways to use it
@@ -36,8 +39,8 @@ and your sessions, settings, and API keys are stored on your own machine.
 | **One-shot** | `kolega-code ask "…"` | Scripting, automation, quick questions, CI |
 
 There are also helper commands for managing
-[sessions](../../cli/sessions/) and checking your
-[configuration](../../cli/doctor/).
+[sessions](cli/sessions/) and checking your
+[configuration](cli/doctor/).
 
 ## Bring your own model
 
@@ -45,7 +48,7 @@ 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](../../configuration/providers-and-models/).
+[Providers & Models](configuration/providers-and-models/).
 
 ## What you need
 
@@ -53,5 +56,31 @@ small utility calls, and one for extended "thinking"). See
 - An **API key** for at least one supported provider
 - A terminal that supports a modern TUI (most do)
 
-Head to [Installation](../installation/) to set it up, then the
-[Quick Start](../quick-start/) to run your first session.
+## Install
+
+Install with the script:
+
+```bash
+curl -fsSL https://kolega.dev/install-kolega-code.sh | sh
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install kolega-code
+```
+
+Verify the install and start a session in your project:
+
+```bash
+kolega-code --version
+kolega-code .
+```
+
+See [Installation](getting-started/installation/) for requirements, other install
+methods, and upgrade/uninstall commands.
+
+## Next steps
+
+Once you're installed and have a provider key set, head to the
+[Quick Start](getting-started/quick-start/) to run your first session.

{kolega_code-0.3.2 → kolega_code-0.5.0}/docs/src/content/docs/tui/interface.md

@@ -37,14 +37,41 @@ At the bottom sits the **composer** — the text box where you type prompts. See
   can return to the live edge.
 - **Tool results** — shown as collapsible blocks with a state indicator
   (running / done / failed). Expand to see the full result.
-- **Sub-agents** — when the main agent dispatches a sub-agent, its activity is
-  tracked live with status updates.
+- **Sub-agents** — when the main agent dispatches a sub-agent, a live card tracks
+  it inline: the agent name, elapsed time, tool count, token usage, what it's doing
+  right now, and a tail of its latest output. Press `Ctrl+G` (or click the card) to
+  open the full [sub-agent inspector](#sub-agent-inspector).
 - **Option lists** — when the agent asks you to choose between options (including
   plan decisions and tool approvals), they render as a **vertical,
   arrow-key-selectable list**.
   Use the arrow keys to highlight, number keys (`1`–`9`) to jump, and `Enter` to
   confirm.
 
+## Sub-agent inspector
+
+The inline cards summarize sub-agent activity; the **inspector** shows the whole
+story. Press `Ctrl+G` (or click any sub-agent card) to open a full-screen
+"mission control" view:
+
+- **Roster** (left) — every sub-agent dispatched this turn, running or finished,
+  each with a live spinner, status, elapsed time, tool count, and token usage.
+  Nested sub-agents are indented by depth.
+- **Trajectory** (right) — the selected agent's full run: its thinking, each tool
+  call, the tool results (expandable, just like the main transcript), and its
+  responses, streaming live as it works.
+
+| Keys | Action |
+| --- | --- |
+| `Ctrl+G` | Open the inspector (on the most recently active sub-agent) |
+| `↑` / `↓` | Switch between sub-agents |
+| `Tab` then `Enter` | Focus a tool call and expand it (or click it) |
+| `o` | Toggle follow — auto-scroll to the newest activity |
+| `y` | Copy the selected agent's trajectory to the clipboard |
+| `Esc` / `q` | Close the inspector |
+
+The inspector is read-only: opening or closing it never interrupts the agent, so
+the turn keeps running while you look around.
+
 ## Key bindings at a glance
 
 | Keys | Action |
@@ -52,6 +79,7 @@ At the bottom sits the **composer** — the text box where you type prompts. See
 | `Shift+Tab` | Toggle Build ⇄ Plan mode |
 | `Ctrl+P` | Toggle shell/edit permissions between Ask ⇄ Auto |
 | `Ctrl+O` | Show or hide the side panel |
+| `Ctrl+G` | Open the sub-agent inspector |
 | `Enter` | Send the prompt |
 | `Shift+Enter` / `Ctrl+J` | Insert a newline |
 | `Ctrl+C` / `Escape` | Cancel the current generation |

{kolega_code-0.3.2 → kolega_code-0.5.0}/docs/src/content/docs/tui/modes.md

@@ -22,6 +22,10 @@ default to `ask`, so shell commands and file edits prompt before they run. Press
 When you choose an “always allow” approval, Kolega Code stores the local rule in
 `.kolega/permissions.json` for that project.
 
+If [gigacode](../../gigacode/) is enabled, the sub-agents inside a workflow run in
+`auto` permission mode regardless of this setting — see
+[Behavior and safety](../../gigacode/#behavior-and-safety).
+
 ## Plan mode
 
 A **read-only** planning pass. Plan mode uses a standalone planning agent that does
@@ -39,7 +43,9 @@ happens next — typically to **implement the plan** or to **keep discussing** i
 The decision is presented as a vertical, arrow-key-selectable option list.
 
 Use Plan mode when a change is non-trivial and you want to agree on the approach
-before any files are touched.
+before any files are touched. With [gigacode](../../gigacode/) on, a planning agent
+can fan out parallel research across the codebase; those workflow sub-agents stay
+read-only too.
 
 ## A typical loop
 

{kolega_code-0.3.2 → kolega_code-0.5.0}/docs/src/content/docs/tui/slash-commands.md

@@ -40,6 +40,7 @@ These control the app and your session.
 | `/permissions` | Show or switch the shell/edit permission mode |
 | `/model` | Choose the active model |
 | `/effort` | Choose the active model's thinking effort |
+| `/gigacode` | Toggle [gigacode](../../gigacode/) workflow orchestration on or off |
 | `/copy` | Copy the last response to the clipboard |
 | `/version` | Show the Kolega Code version |
 | `/update` | Update Kolega Code to the latest version |

{kolega_code-0.3.2 → kolega_code-0.5.0}/kolega_code/__init__.py

@@ -148,4 +148,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.3.2"
+__version__ = "0.5.0"

{kolega_code-0.3.2 → kolega_code-0.5.0}/kolega_code/agent/__init__.py

@@ -39,4 +39,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.3.2"
+__version__ = "0.5.0"