# Analytics Worker
Source: https://docs.kodus.io/how_to_deploy/en/deploy_kodus/analytics_worker

Optional analytics ingestion worker for self-hosted Enterprise. Powers the Cockpit dashboards (DORA, lifecycle, classifier).

The analytics worker is an **Enterprise-only** add-on. It runs the
ingestion cron that powers the Cockpit dashboards (DORA-style metrics,
PR lifecycle, LLM-based PR classifier).

<Warning>
  The default installer **does not** ship this worker. Community self-hosted
  deployments don't need it and these vars are filtered out of the default
  `.env.example`. Stop here unless you have a self-hosted Enterprise
  license and want the Cockpit reports.
</Warning>

## What it does

A separate Node process running the **same image as `worker`** (`kodus-ai-worker`),
selected at boot via `WORKER_ROLE=analytics`. Two crons fire from this
process and only this process:

* **Ingestion** (`ANALYTICS_INGESTION_CRON`, default `*/30 * * * *`) — reads
  pull requests and review sessions from Mongo + the OLTP Postgres, projects
  them into the `analytics` schema.
* **Classifier** (`ANALYTICS_CLASSIFIER_CRON`, default `*/15 * * * *`) — calls
  an LLM to tag each PR with a type (feature/bugfix/refactor/etc).

Isolating it from the main `worker` keeps the code-review event loop
unaffected by long-running ingestion queries.

## Topology

The analytics warehouse is a Postgres **schema**, not a separate database.
Two supported layouts:

* **Shared Postgres (recommended for self-hosted)** — leave
  `ANALYTICS_PG_DB_HOST` empty. The config loader falls back to the main
  `API_PG_DB_*` vars and creates an `analytics` schema in the same instance.
  One DB to back up and operate.
* **Dedicated Postgres** — set the full `ANALYTICS_PG_DB_*` block to point
  at a separate instance. Use this when you want analytical queries fully
  isolated from the OLTP write path.

```mermaid theme={null}
flowchart LR
    api[api] --> pg[(Postgres OLTP)]
    worker[worker] --> rabbitmq[(RabbitMQ)]
    aw[worker-analytics] --> rabbitmq
    aw --> pg
    aw --> mg[(MongoDB)]
    aw -.->|writes| analytics[(Postgres • analytics schema)]
    cockpit[Cockpit UI] --> analytics
```

## Enabling on self-hosted Enterprise

### 1. Add the service to `docker-compose.yml`

```yaml theme={null}
worker-analytics:
    image: ghcr.io/kodustech/kodus-ai-worker:latest
    platform: linux/amd64
    container_name: kodus-worker-analytics
    environment:
        - ENV=production
        - NODE_ENV=production
        - WORKER_ROLE=analytics
    networks:
        - shared-network
        - kodus-backend-services
    restart: unless-stopped
    env_file:
        - .env
    depends_on:
        - db_kodus_postgres
        - db_kodus_mongodb
        - rabbitmq
```

The image is identical to the `worker` service — only `WORKER_ROLE=analytics`
flips it into ingestion mode.

### 2. Add the analytics block to `.env`

**Shared Postgres (recommended):**

```bash theme={null}
# Empty ANALYTICS_PG_DB_HOST → loader reuses API_PG_DB_* and creates the
# `analytics` schema in the main instance.
ANALYTICS_PG_DB_HOST=
ANALYTICS_PG_DB_SCHEMA=analytics

# Cron schedules (UTC).
ANALYTICS_INGESTION_CRON=*/30 * * * *
ANALYTICS_CLASSIFIER_CRON=*/15 * * * *
```

**Dedicated Postgres:**

```bash theme={null}
ANALYTICS_PG_DB_HOST=your-analytics-host
ANALYTICS_PG_DB_PORT=5432
ANALYTICS_PG_DB_USERNAME=analytics
ANALYTICS_PG_DB_PASSWORD=...
ANALYTICS_PG_DB_DATABASE=kodus_analytics
ANALYTICS_PG_DB_SCHEMA=analytics

ANALYTICS_INGESTION_CRON=*/30 * * * *
ANALYTICS_CLASSIFIER_CRON=*/15 * * * *
```

### 3. Boot — migrations run automatically

The `worker-analytics` container shares the same `prod-entrypoint.sh` as
`api`/`worker`/`webhooks`. With `RUN_MIGRATIONS=true` (installer default),
the analytics warehouse migrations (`yarn analytics:migration:run:prod`)
run on first boot, creating the `analytics` schema and its tables.

## Reference

| Variable                    | Description                                                      | Default        |
| --------------------------- | ---------------------------------------------------------------- | -------------- |
| `WORKER_ROLE`               | Must be set to `analytics` on this container.                    | *required*     |
| `ANALYTICS_PG_DB_HOST`      | Analytics Postgres host. Empty → reuse main Postgres.            | *empty*        |
| `ANALYTICS_PG_DB_PORT`      | Analytics Postgres port.                                         | `5432`         |
| `ANALYTICS_PG_DB_USERNAME`  | Analytics Postgres user. Empty → reuse `API_PG_DB_USERNAME`.     | *empty*        |
| `ANALYTICS_PG_DB_PASSWORD`  | Analytics Postgres password. Empty → reuse `API_PG_DB_PASSWORD`. | *empty*        |
| `ANALYTICS_PG_DB_DATABASE`  | Analytics Postgres database. Empty → reuse `API_PG_DB_DATABASE`. | *empty*        |
| `ANALYTICS_PG_DB_SCHEMA`    | Schema name for the warehouse tables.                            | `analytics`    |
| `ANALYTICS_PG_POOL_MAX`     | Upper bound on the analytics Postgres pool.                      | `5`            |
| `ANALYTICS_INGESTION_CRON`  | Cron schedule for the ingestion run (UTC).                       | `*/30 * * * *` |
| `ANALYTICS_CLASSIFIER_CRON` | Cron schedule for the LLM PR-type classifier (UTC).              | `*/15 * * * *` |

### Pausing ingestion (advanced)

To stop ingestion at runtime without removing the container, set
`ANALYTICS_INGESTION_DISABLED=true` and/or `ANALYTICS_CLASSIFIER_DISABLED=true`
and restart `worker-analytics`. The cron stays scheduled but each tick
short-circuits. Use this for incident triage, not as a long-term config —
they are managed primarily for cloud and may not appear in the installer
template.

## Verifying it's working

After boot, tail the analytics worker logs:

```bash theme={null}
docker compose logs -f worker-analytics
```

You should see lines like `analytics ingestion done in NNNms — {...}` every
30 minutes and `analytics classifier done ...` every 15 minutes. If you
don't, check that `WORKER_ROLE=analytics` is set on this container only
(not on the main `worker` — that one must stay `code-review`).


# Installation
Source: https://docs.kodus.io/how_to_deploy/en/deploy_kodus/generic_vm

Deploy Kodus on a Generic Virtual Machine.

<Snippet />

## Environment Variables Configuration

Use this section to fill your `.env`. Start with the public URLs, then set up
databases and RabbitMQ, and finally add provider-specific settings.

### Namespace Configuration

These settings define the public URLs and host binding used by the web app and API.
If you are not using MCP Manager, you can skip the MCP entries here and the
full block below.

```env theme={null}
WEB_HOSTNAME_API="kodus-api.yourdomain.com"    # Public API hostname (e.g., kodus-api.yourdomain.com)
NEXTAUTH_URL="https://kodus-web.yourdomain.com" # Full public base URL for the Web App (e.g., https://kodus-web.yourdomain.com)
API_HOST=0.0.0.0                              # API host (0.0.0.0 for local development)

# Only needed if you want to use MCP features.
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101 # MCP Manager URL
API_KODUS_MCP_SERVER_URL=http://kodus-api.yourdomain.com/mcp # Kodus MCP Server URL
```

### LLM Provider Configuration

```env theme={null}
API_LLM_PROVIDER_MODEL="gpt-5"     # Model you want to use
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # Your API provider URL
API_OPEN_AI_API_KEY="your-api-key"          # Your API provider key
```

Check our [model-specific guides](https://docs.kodus.io/cookbook/en) for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

### Database configuration

Use local containers for Postgres and MongoDB by default. Update credentials
to match your security requirements.

```env theme={null}
# Use local containers for Postgres and MongoDB
USE_LOCAL_DB=true

# PostgreSQL Settings
API_DATABASE_ENV="development"                # development, production, test
API_PG_DB_HOST=db_kodus_postgres              # PostgreSQL host
API_PG_DB_PORT=5432                          # PostgreSQL port
API_PG_DB_USERNAME=kodusdev                  # Database username
API_PG_DB_PASSWORD=                          # Database password
API_PG_DB_DATABASE=kodus_db                  # Database name

# MongoDB Settings
API_MG_DB_HOST=db_kodus_mongodb              # MongoDB host
API_MG_DB_PORT=27017                         # MongoDB port
API_MG_DB_USERNAME=kodusdev                  # Database username
API_MG_DB_PASSWORD=                          # Database password
API_MG_DB_DATABASE=kodus                     # Database name
API_MG_DB_PRODUCTION_CONFIG=''               # Additional production settings

# SSL — the local Postgres container ships without SSL. This global switch
# covers ALL data sources (default + analytics). Leaving it false makes the
# api crash in a connect-retry loop.
API_DATABASE_DISABLE_SSL=true                # disable SSL for local DBs
```

<Tip>
  `API_PG_DB_PASSWORD` and `API_MG_DB_PASSWORD` are auto-generated by `./scripts/install.sh` (via `generate-secrets.sh`) if left blank. You only need to set them yourself if you point the installer at external databases.
</Tip>

### RabbitMQ configuration

RabbitMQ is required in 2.0. Keep the URI in sync with the values below.

```env theme={null}
# RabbitMQ Configuration
USE_LOCAL_RABBITMQ=true
RABBITMQ_HOSTNAME=rabbitmq                   # RabbitMQ hostname in Docker network
RABBITMQ_DEFAULT_USER=kodus                  # RabbitMQ user (change in production)
RABBITMQ_DEFAULT_PASS=kodus                  # RabbitMQ password (change in production)

# Keep the URI in sync with the user, password, and vhost above
API_RABBITMQ_URI=amqp://kodus:kodus@rabbitmq:5672/kodus-ai # RabbitMQ connection URI
API_RABBITMQ_ENABLED=true                    # RabbitMQ is required
```

### Worker configuration

The worker container needs a role to know which workload to handle.
Self-hosted only runs the code review role; the analytics role is
cloud-only.

<Warning>
  Leaving `WORKER_ROLE` unset crashes the worker on boot. Because the worker is what creates the `workflow.jobs.*` queues on first connect, the api and webhooks then fail every webhook event with a `QueueBind 404` error.
</Warning>

```env theme={null}
# Worker role — required. Self-hosted = code-review.
WORKER_ROLE=code-review
```

### Git Provider Configuration

Choose and configure your preferred Git provider. You can set one or more
providers; for basic token-based authentication, you only need the webhook URL.

<Info>
  Webhooks are handled by a separate service (port 3332). Your webhook URLs must reach that service. You can use a dedicated webhooks domain, or keep the API domain and route `/.../webhook` paths to the webhooks service in your reverse proxy.
  Using GitHub or GitLab OAuth? See <a href="/how_to_deploy/en/platforms/github/github_oauth">GitHub OAuth App</a> or <a href="/how_to_deploy/en/platforms/gitlab/gitlab_oauth">GitLab OAuth App</a>. For GitHub App setup, see <a href="/how_to_deploy/en/platforms/github/github_app">GitHub App</a>.
</Info>

<Tabs>
  <Tab title="Github">
    ```env theme={null}
    # Required for token-based authentication
    API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"          # Webhook URL (use webhooks domain, or API domain if proxied to webhooks service)
    ```
  </Tab>

  <Tab title="GitLab">
    ```env theme={null}
    # Required for token-based authentication
    API_GITLAB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/gitlab/webhook"          # Webhook URL (use webhooks domain, or API domain if proxied to webhooks service)
    ```
  </Tab>

  <Tab title="Bitbucket">
    ```env theme={null}
    # Required for token-based authentication
    GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/bitbucket/webhook"    # Webhook URL (use webhooks domain, or API domain if proxied to webhooks service)
    ```
  </Tab>

  <Tab title="Azure DevOps">
    ```env theme={null}
    # Required for token-based authentication
    GLOBAL_AZURE_REPOS_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/azure-repos/webhook"    # Webhook URL (use webhooks domain, or API domain if proxied to webhooks service)
    ```
  </Tab>
</Tabs>

### MCP Manager Configuration

<Info>
  Only needed if you want to use MCP Manager.
</Info>

MCP Manager is the service that connects Kody to external tools and exposes
them in the Plugins screen. Check our [MCP Manager documentation](/how_to_deploy/en/deploy_kodus/mcp_manager)
for more information.

```env theme={null}
API_MCP_SERVER_ENABLED=false # Change to true if you want to use MCP Manager
---
API_KODUS_SERVICE_MCP_MANAGER=http://kodus-mcp-manager:3101
API_KODUS_MCP_SERVER_URL=http://localhost:3001/mcp

# MCP Manager Configuration
API_MCP_MANAGER_LOG_LEVEL=info
API_MCP_MANAGER_PORT=3101
API_MCP_MANAGER_NODE_ENV=development
API_MCP_MANAGER_DATABASE_ENV=development
API_MCP_MANAGER_CORS_ORIGINS=*
API_MCP_MANAGER_JWT_SECRET=
API_MCP_MANAGER_COMPOSIO_BASE_URL=https://backend.composio.dev/api/v3
API_MCP_MANAGER_COMPOSIO_API_KEY=
API_MCP_MANAGER_MCP_PROVIDERS=kodusmcp,composio,custom
API_MCP_MANAGER_REDIRECT_URI=http://localhost:3000/setup/mcp/oauth
API_MCP_MANAGER_PG_DB_SCHEMA=mcp-manager
API_MCP_MANAGER_ENCRYPTION_SECRET=
```

### External Services Configuration (Optional)

These services are optional but significantly improve Kodus's code review quality. Each requires you to create an account and generate an API key.

<AccordionGroup>
  <Accordion title="E2B — Code Execution Sandbox">
    E2B provides a secure sandbox that Kodus uses to run and validate code during reviews.

    1. Create an account at [e2b.dev](https://e2b.dev)
    2. Generate an API key in your dashboard
    3. Add it to your `.env`:

    ```env theme={null}
    API_E2B_KEY=your-e2b-api-key
    ```
  </Accordion>

  <Accordion title="MorphLLM — Code Editing Model">
    MorphLLM is a specialized model for fast, accurate code editing. Kodus uses it to apply review suggestions more precisely.

    1. Create an account at [morphllm.com](https://morphllm.com)
    2. Generate an API key in your dashboard
    3. Add it to your `.env`:

    ```env theme={null}
    API_MORPHLLM_API_KEY=your-morphllm-api-key
    ```
  </Accordion>
</AccordionGroup>

<Columns>
  <Card title="Need help?" icon="headset" href="https://cal.com/gabrielmalinosqui/30min">
    Schedule a call with our founder to get help with your deployment.
  </Card>

  <Card title="Get help with our community" icon="discord" href="https://discord.gg/TFZBRk9fT6">
    Join our community to get help with your deployment.
  </Card>
</Columns>


# MCP Manager
Source: https://docs.kodus.io/how_to_deploy/en/deploy_kodus/mcp_manager

Deploy MCP Manager for Kodus.

## What are MCPs?

Model Context Protocol (MCP) is an open standard that lets LLM apps connect to
external tools and data sources through a consistent server interface. MCP
servers publish tool schemas and endpoints so clients like Kodus/Kody can fetch
context or run actions during a workflow.

## MCP Manager Architecture

MCP Manager is the backend service that brokers those MCP connections for
Kodus. It keeps track of providers, integrations, and allowed tools per
workspace, then exposes that catalog to the Kodus API.

* Central registry for MCP providers (Kodus, Composio, and custom)
* Stores integration metadata (connection status, MCP URL, allowed tools)
* Handles provider-specific authentication flows and tool discovery
* Exposes APIs used by Kodus to list and invoke MCP tools

```mermaid theme={null}
graph TD
    A[Kodus] --> B[MCP Manager]
    B --> C[Providers]
    C --> D[Kodus MCPs]
    C --> E[Composio]
    C --> F[Custom]
```

## Plugins in Kodus

Everything registered in MCP Manager appears in the Kodus **Plugins** screen,
so your team can install, manage, and enable the MCPs available for each
workspace.

<img alt="Kodus plugins screen showing MCPs from MCP Manager" />

## Providers

### Kodus provider

The Kodus provider bundles first-party MCPs managed by Kodus, including the
Kodus MCP, Context7 MCP, and Kodus Docs MCP.

### Composio provider

Composio is a managed integration platform with a large catalog of SaaS tools.
MCP Manager uses Composio for authentication and to provision MCP endpoints
that Kodus can call. See the official docs for setup details:
[Composio MCP docs](https://docs.composio.dev/docs/mcp-providers)

### Custom providers

You can add custom providers to integrate internal systems or third-party
platforms. In self-hosted deployments, list the provider in
`API_MCP_MANAGER_MCP_PROVIDERS`, then implement the provider in the MCP Manager
codebase. The reference implementation lives here:
[kodus-mcp-manager repo](https://github.com/kodustech/kodus-mcp-manager#-adding-a-new-provider)

## Configuring Composio

1. Create a Composio account and an integration for the tool you want to
   expose.
2. Enable or create an MCP server for that integration (see Composio docs).
3. Set these variables in your Kodus `.env`:
   * `API_MCP_MANAGER_COMPOSIO_API_KEY`
   * `API_MCP_MANAGER_COMPOSIO_BASE_URL` (default:
     `https://backend.composio.dev/api/v3`)
4. Ensure `composio` is listed in `API_MCP_MANAGER_MCP_PROVIDERS`.


# Reverse Proxy
Source: https://docs.kodus.io/how_to_deploy/en/deploy_kodus/reverse_proxy

Configure a reverse proxy for Kodus.

<Info>
  Optional Step: Only needed if you will not use any loadbalancer or proxy server.
</Info>

To make your Kodus instance accessible from external systems (required for Code Review webhooks and public access), you'll need to configure a reverse proxy with Nginx.

Here's a sample Nginx configuration for two subdomains:

```nginx theme={null}
# Server block for the Kodus Web Application
server {
    listen 80;
    server_name kodus-web.yourdomain.com; # Replace with your actual web app domain

    location / {
        proxy_pass http://localhost:3000; # Points to the Kodus Web App container
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_buffer_size 16k;
        proxy_buffers 8 16k;
        proxy_busy_buffers_size 32k;
    }
}

# Server block for the Kodus API
server {
    listen 80;
    server_name kodus-api.yourdomain.com; # Replace with your actual API domain

    location ~ ^/(github|gitlab|bitbucket|azure-repos)/webhook {
        proxy_pass http://localhost:3332; # Points to the Kodus Webhooks service
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    location / {
        proxy_pass http://localhost:3001; # Points to the Kodus API service
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}
```

<Note>
  Webhooks are handled by a separate service (port 3332). The `location ~ ^/(github|gitlab|bitbucket|azure-repos)/webhook` block is required if your webhook URLs use the API domain.
</Note>

### Optional: Dedicated Webhooks Subdomain

If you prefer a separate domain for webhooks (e.g., `kodus-webhooks.yourdomain.com`), add a server block that points to the webhooks service:

```nginx theme={null}
server {
    listen 80;
    server_name kodus-webhooks.yourdomain.com;

    location / {
        proxy_pass http://localhost:3332; # Webhooks service
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}
```

Save this configuration to `/etc/nginx/sites-available/kodus` (or a name of your choice, e.g., `kodus-web` and `kodus-api` as separate files if preferred) and create a symbolic link to enable it:

```bash theme={null}
sudo ln -s /etc/nginx/sites-available/kodus /etc/nginx/sites-enabled/
sudo nginx -t  # Test the configuration
sudo systemctl reload nginx  # Apply the changes
```

<Info>
  **Important Configuration Update for Reverse Proxy:**

  After setting up the reverse proxy with `kodus-web.yourdomain.com` and `kodus-api.yourdomain.com` (or your chosen subdomains), you **must** ensure your `.env` file correctly reflects these public URLs. Specifically, verify:

  * `WEB_HOSTNAME_API`: Should be set to **only the hostname** of your public API (e.g., `kodus-api.yourdomain.com`), without any protocol (`http://` or `https://`).
  * `WEB_PORT_API`: Should correspond to the public port your API is accessible on (typically `443` for HTTPS or `80` for HTTP). The scheme (http/https) used by the frontend to call the API will often be inferred from this port or hardcoded in the frontend logic to use HTTPS.
  * Webhook URLs (e.g., `API_GITHUB_CODE_MANAGEMENT_WEBHOOK`): Ensure these resolve to the **webhooks service**. You can use the API domain only if `/.../webhook` routes to port `3332`, or use a dedicated webhooks domain (e.g., `https://kodus-webhooks.yourdomain.com/github/webhook`).

  Failure to update these correctly may result in authentication issues, inability for the web application to connect to the API, or malfunctioning webhooks.
</Info>

### Enabling SSL (Recommended)

For production deployments, we strongly recommend setting up SSL with Let's Encrypt:

```bash theme={null}
# Install Certbot for Let's Encrypt
sudo apt-get update
sudo apt-get install certbot python3-certbot-nginx

# Obtain and install certificates for both domains
sudo certbot --nginx -d kodus-web.yourdomain.com -d kodus-api.yourdomain.com # Replace with your actual domains
```

This will automatically configure your Nginx setup to use HTTPS and redirect HTTP traffic for both subdomains.


# Sandbox & AST Graph
Source: https://docs.kodus.io/how_to_deploy/en/deploy_kodus/sandbox

How Kodus parses your repo (kodus-graph), where it runs (sandbox modes), and when to pick each mode.

To review a PR with the right context, Kodus parses the entire repository
into an **AST graph** (nodes + edges) and uses it to fetch cross-file
context, validate suggestions, and feed the agent. The parser runs inside
a **sandbox** so it can `git clone`, install dependencies, and execute the
CLI in isolation from the API process.

This page explains the sandbox modes you can pick from, what the AST
graph is, and how the cache keeps PR-level reviews fast.

## How the AST graph works

Kodus uses [`@kodus/kodus-graph`](https://www.npmjs.com/package/@kodus/kodus-graph),
a CLI that walks a repository and emits a JSON graph (functions, classes,
files, imports, calls). The CLI is **pre-installed in the worker image**
(`kodus-ai-worker`), so there is no extra setup step on `local` mode.

The lifecycle:

1. **When you select a repository** (during setup, or when adding a repo
   later in the UI) — Kodus enqueues an `AstGraphBuild` job that runs
   `kodus-graph parse --all` against the default branch, persists the
   result to Postgres (`ast_graph_*` tables), and marks the repo as
   indexed. This happens in the background — you don't have to wait for
   it to finish before opening PRs.
2. **When a PR is merged into the default branch** — webhook handlers
   enqueue an incremental rebuild that re-parses only the changed files
   and merges the deltas into the cached graph. The cache stays fresh
   without ever needing a full rebuild.
3. **On every PR review** — Kodus loads the cached graph, parses only
   the files touched by the PR, and feeds the agent a focused subgraph.
   This is the hot path; it never re-parses the whole repo.

The cache is what makes large-repo reviews tractable: the first build
runs once at repo-onboarding, every PR after that reads from Postgres.

## Sandbox modes

The sandbox is selected by `SANDBOX_PROVIDER` in `.env`:

| Mode                              | What it does                                                                              | Trade-off                                                                 |
| --------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **`local`** *(installer default)* | Runs `kodus-graph` inside the `worker` container itself. Bun + the CLI are pre-installed. | No external dependency. Worker container needs more RAM on big repos.     |
| **`e2b`**                         | Spins up a remote [E2B](https://e2b.dev) sandbox per job. Requires `API_E2B_KEY`.         | Strong isolation, scales for huge repos. **Paid third-party service.**    |
| **`auto`**                        | Uses `e2b` when `API_E2B_KEY` is set, otherwise falls back to no sandbox.                 | Convenient for staged rollouts, e.g. when migrating from `none` to `e2b`. |
| **`none`**                        | No sandbox. Disables AST graph and cross-file context.                                    | Reviews are less rich (no call-graph context, no cross-file analysis).    |

### Picking a mode

* **You're getting started, want it to "just work"** → `local`. This is
  the installer default and needs zero external accounts.
* **Repos are huge (millions of LOC) or you want strict isolation** →
  `e2b`. Sign up at [e2b.dev](https://e2b.dev), set `API_E2B_KEY`, switch
  `SANDBOX_PROVIDER=e2b`.
* **You explicitly don't want any sandbox to run** → `none`. The review
  agent runs without cross-file context; suggestions still work but are
  less informed.

## Migrating an existing self-hosted install

If you upgraded from a release that predates the AST graph, your
**already-selected repositories** won't have a graph yet — the build only
fires automatically on **new** repo selections. To index them, run the
backfill script bundled with the installer:

```bash theme={null}
# From the kodus-installer directory, with the stack running:
./scripts/backfill-ast-graph.sh
```

This walks every team in the instance and enqueues an `AstGraphBuild`
job for each selected repo whose `astGraphStatus` is `NULL`, `PENDING`,
or `FAILED`. Builds run in the background — you can keep using Kodus
while they finish.

The script is **idempotent**: re-running skips repos that are already
`READY`, never re-enqueues `BUILDING` jobs, and you can stop and resume
freely.

Common flags:

```bash theme={null}
./scripts/backfill-ast-graph.sh --org <id>          # restrict to one org
./scripts/backfill-ast-graph.sh --org <id> --team <id>  # one team only
./scripts/backfill-ast-graph.sh --force             # also rebuild READY graphs
./scripts/backfill-ast-graph.sh --limit 50          # cap jobs per team (default: 10)
./scripts/backfill-ast-graph.sh --dry-run           # list teams, enqueue nothing
```

You can watch progress in the worker logs:

```bash theme={null}
docker compose logs -f worker | grep -i ast-graph
```

## Configuration

```bash theme={null}
# Default for self-hosted — runs in the worker container.
SANDBOX_PROVIDER=local

# Or use E2B (paid) for stronger isolation.
SANDBOX_PROVIDER=e2b
API_E2B_KEY=your-e2b-api-key
```

Sign up for E2B at [e2b.dev](https://e2b.dev), generate an API key in the
dashboard, then drop it in `.env` and restart the stack.

## What runs where

```mermaid theme={null}
flowchart LR
    pr[PR webhook] --> worker[worker]
    worker -->|local mode| sandbox_local[kodus-graph CLI<br/>inside worker container]
    worker -.->|e2b mode| sandbox_e2b[E2B remote sandbox<br/>kodus-graph runs there]
    sandbox_local --> graph[(Postgres • ast_graph_*)]
    sandbox_e2b --> graph
    graph --> agent[code-review agent]
```

## Resource sizing

The `local` sandbox runs `git clone` and `kodus-graph parse` inside the
`worker` container, so worker RAM headroom matters:

* **Small to medium repos (\< 100k LOC)** — the default 8GB host is fine.
* **Large repos (100k–1M LOC)** — give the worker container 4–8GB of RAM
  on top of normal usage; consider 16GB total host RAM.
* **Huge monorepos (> 1M LOC)** — switch to `e2b` so the parsing happens
  off-box.

The Postgres footprint scales with repo count and history depth — plan
\~10–50MB per indexed repo as a rough order of magnitude.

## Troubleshooting

**Reviews don't include cross-file context (`local` mode):**

Check the worker logs for `kodus-graph` install or parse errors:

```bash theme={null}
docker compose logs -f worker | grep -i kodus-graph
```

If the install step fails, confirm that the worker container has
internet access (it needs to fetch bun + the CLI on first boot if the
image was built without them).

**`e2b` jobs hang or fail to start:**

Verify `API_E2B_KEY` is set and valid:

```bash theme={null}
docker compose exec worker printenv API_E2B_KEY
```

The E2B dashboard shows live sessions and quota usage.

**You want to disable AST entirely (testing, debugging):**

Set `SANDBOX_PROVIDER=none` and restart the worker. Reviews will skip
the graph stage and run with the LLM's vanilla view of the diff.


# Anonymous Telemetry
Source: https://docs.kodus.io/how_to_deploy/en/deploy_kodus/telemetry

What the self-hosted heartbeat sends, why we collect it, and how to disable it.

Each self-hosted Kodus instance sends **one anonymous heartbeat per day** to
`https://telemetry.kodus.io`. The payload contains aggregated counters and
runtime metadata only — never code, identities, or anything that could trace
back to you or your users.

This page documents exactly what is sent, why, where it goes, and how to
turn it off.

## What we send

A single `POST /v1/heartbeat` once per UTC day, \~700 bytes. Example payload
(redacted UUID for clarity):

```json theme={null}
{
  "schema_version": 1,
  "instance_id": "0188f5c5-5b8f-4f45-92d4-b20c25df0b5a",
  "sent_at": "2026-05-04T03:17:00.000Z",
  "kodus": {
    "version": "0.4.15",
    "deployment": "docker",
    "uptime_hours": 124
  },
  "runtime": {
    "node_version": "v20.11.1",
    "os": "linux",
    "arch": "x64",
    "cpu_count": 8,
    "db_type": "postgres",
    "db_version": "PostgreSQL 15.4"
  },
  "usage_7d": {
    "active_users": 12,
    "organizations": 1,
    "teams": 2,
    "repos_connected": 9,
    "prs_reviewed": 184,
    "suggestions_generated": 0,
    "suggestions_applied": 0
  },
  "config": {
    "kody_rules_enabled": true,
    "agent_review_repos_pct": 0,
    "integrations": ["github", "slack"]
  }
}
```

The full schema lives in the [kodus-beacon repository](https://github.com/kodustech/kodus-beacon/blob/main/docs/api.md) — it is enforced server-side
with a strict validator that rejects any unknown field with a `400`.

## What we never send

By design, the schema cannot carry:

* User emails, names, OAuth tokens, API keys
* Repository names, branch names, PR titles, commit messages, code content
* Customer-identifying strings (org slugs, workspace names, custom domains)
* IP addresses (the receiver hashes the source IP with a daily-rotating
  salt for abuse detection only and never persists the raw IP)
* Any free-form text field

The receiver enforces a 5 KB body limit and rejects any field outside the
documented schema, so a misconfigured client cannot accidentally leak data.

## Why we collect this

Anonymous heartbeats let us answer questions we otherwise cannot answer for
self-hosted users:

* Which versions of Kodus are still in use, and how fast new releases get
  adopted
* How operators deploy (Docker / Kubernetes / bare metal), so we prioritise
  the platforms people actually run
* Whether features like Kody Rules are reaching self-hosted users at all
* Volume signals (PRs reviewed per fleet, repos connected) so we can size
  capacity decisions

It does **not** let us identify any specific instance, customer, or user. We
do not contact you based on telemetry. We do not share or sell the data.

## Inspect what your instance would send

Before any heartbeat leaves your instance, you can dump the exact payload
that the daily cron would build:

```bash theme={null}
yarn telemetry:preview
```

This boots a minimal Kodus context, runs the same collector the cron uses,
and prints the JSON to stdout — without sending it. Pipe it through `jq` to
explore:

```bash theme={null}
yarn telemetry:preview | jq '.usage_7d'
```

## Disable telemetry

Set `KODUS_TELEMETRY_DISABLED=true` in your environment. The cron skips
silently — no heartbeat is sent, ever, until you flip it back.

```bash theme={null}
# .env
KODUS_TELEMETRY_DISABLED=true
```

Accepted truthy values (case-insensitive): `1`, `true`, `yes`, `on`. Any
other value (including empty) keeps telemetry enabled.

## Where the data lives

* **Receiver:** a small Node.js service (Fastify) deployed at
  `telemetry.kodus.io`. Source code is public:
  [kodustech/kodus-beacon](https://github.com/kodustech/kodus-beacon).
* **Storage:** Neon Postgres, US region, encrypted at rest, TLS-only.
  Two tables — `telemetry_instances` (one row per instance, last seen
  * version) and `telemetry_heartbeats` (one row per instance per UTC
    day, payload stored as JSONB).
* **Retention:** individual heartbeat rows are kept for **12 months**.
  After that we aggregate the counters into historical statistics
  (e.g. "X active instances in January 2026") and drop the per-day
  rows. The instance row stays — it carries no time-series, only the
  most recent version + last-seen timestamp.
* **Access:** product engineering team only, via individual Neon
  credentials with audit logging. The data is never shared with third
  parties and never used to train any AI model.

## Source code you can audit

Both ends are open and small enough to read end-to-end:

* **Client** (what runs on your instance): the cron, collector, and HTTP
  transport live under [`libs/telemetry/`](https://github.com/kodustech/kodus-ai/tree/main/libs/telemetry)
  and [`apps/worker/src/cron/self-hosted-beacon.cron.ts`](https://github.com/kodustech/kodus-ai/blob/main/apps/worker/src/cron/self-hosted-beacon.cron.ts).
* **Server** (what runs at `telemetry.kodus.io`): the entire receiver is
  \~80 lines of Fastify route + a Postgres upsert. See
  [kodustech/kodus-beacon](https://github.com/kodustech/kodus-beacon).

## Questions

If something here is unclear or you want a field added, removed, or
documented further, open an issue at
[kodustech/kodus-beacon](https://github.com/kodustech/kodus-beacon/issues)
or reach out on [Discord](https://discord.gg/TFZBRk9fT6).


# Troubleshooting Guide
Source: https://docs.kodus.io/how_to_deploy/en/deploy_kodus/troubleshooting

Solve common issues with Kodus.

## Quick Fixes

### "Run diagnostics"

The installer ships with a doctor script that checks the stack and common misconfigurations.

```bash theme={null}
cd kodus-installer
./scripts/doctor.sh
```

### "I can't access the web interface"

1. Check if the containers are running:

```bash theme={null}
docker-compose ps kodus-web
```

2. Verify the ports are correctly mapped:

```bash theme={null}
docker-compose port kodus-web 3000
```

3. Check the web container logs:

```bash theme={null}
docker-compose logs kodus-web
```

### "Edge Runtime errors in `kodus-web` logs"

If you see errors like `A Node.js API is used ... not supported in the Edge Runtime` (often with an `axios` import trace), part of the web app is running in the Edge Runtime, which does not support Node.js APIs.

1. Update to the latest `kodus-web` image (re-run the installer or run `docker-compose pull kodus-web` and `docker-compose up -d`).
2. If you are building from source, make sure auth/server routes run on the Node.js runtime (set `export const runtime = "nodejs"` and avoid `runtime = "edge"` on those routes).
3. Rebuild and restart the container.

### "Git webhooks aren't working"

1. Verify your domain setup:

```bash theme={null}
curl -I https://your-domain.com
```

2. Check the webhooks logs for webhook attempts:

```bash theme={null}
docker-compose logs webhooks | grep webhook
```

3. Verify your reverse proxy configuration:

```bash theme={null}
sudo nginx -t
```

### "Database connection issues"

1. Check database container status:

```bash theme={null}
docker-compose ps db_kodus_postgres
docker-compose ps db_kodus_mongodb
```

2. Verify database logs:

```bash theme={null}
docker-compose logs db_kodus_postgres
docker-compose logs db_kodus_mongodb
```

3. Test database connections:

```bash theme={null}
docker-compose exec db_kodus_postgres psql -U $API_PG_DB_USERNAME -d $API_PG_DB_DATABASE
docker-compose exec db_kodus_mongodb mongosh -u $API_MG_DB_USERNAME -p $API_MG_DB_PASSWORD
```

### "Migration failed due to missing vector type"

If you encounter the error "type vector does not exist" during migrations, this is because the pgvector extension is not enabled in your PostgreSQL database. Here's how to fix it:

1. Connect to your PostgreSQL database:

```bash theme={null}
docker-compose exec db_kodus_postgres psql -U $API_PG_DB_USERNAME -d $API_PG_DB_DATABASE
```

2. Enable the pgvector extension:

```sql theme={null}
CREATE EXTENSION IF NOT EXISTS vector;
```

3. After enabling the extension, try running your migrations again:

```bash theme={null}
docker-compose exec api npm run migration:run
```

If you're still experiencing issues, you can verify the extension is properly installed:

```sql theme={null}
SELECT * FROM pg_extension WHERE extname = 'vector';
```

## Common Problems

### RabbitMQ Issues

If you're seeing message queue errors:

1. Check RabbitMQ status:

```bash theme={null}
docker-compose logs rabbitmq
```

2. Access the management console at `http://localhost:15672` to verify queues and connections

3. Restart the service if needed:

```bash theme={null}
docker-compose restart rabbitmq
```

### Resource Problems

If services are slow or crashing:

1. Check resource usage:

```bash theme={null}
docker stats
```

2. Verify container limits:

```bash theme={null}
docker inspect $(docker-compose ps -q api) | grep -A 5 "Resources"
```

3. Adjust resource limits in docker-compose.yml if needed

## Getting Help

### What to Include in Support Requests

* The exact error message
* Relevant logs from affected services
* Your deployment method (CLI, VM, etc.)
* Steps to reproduce the issue

### Where to Get Help

* [Discord Community](https://discord.gg/TFZBRk9fT6)
* [GitHub Issues](https://github.com/kodustech/kodus-installer/issues)


# Updating
Source: https://docs.kodus.io/how_to_deploy/en/deploy_kodus/updating

Update your Kodus installation.

<Note>
  Versions shipping anonymous self-hosted telemetry are enabled by default
  and send one daily heartbeat to `telemetry.kodus.io` with aggregated
  counters only — no code, names, or identifiers. Inspect what would be
  sent with `yarn telemetry:preview`, or set `KODUS_TELEMETRY_DISABLED=true`
  to opt out. Full schema and policy in
  [Anonymous Telemetry](/how_to_deploy/en/deploy_kodus/telemetry).
</Note>

To update your Kodus installation to the latest version:

```bash theme={null}
# Navigate to your Kodus installation directory
cd kodus-installer

# Pull the latest changes from the repository
git pull

# If you are upgrading from 1.x, update your .env with the new 2.0 variables
# (RabbitMQ, MCP Manager, and webhooks).

# Re-run the installer to pull images, start services, and run migrations
./scripts/install.sh

# Optional: run diagnostics
./scripts/doctor.sh
```


# Kodus Architecture
Source: https://docs.kodus.io/how_to_deploy/en/kodus_architecture

A deep dive into Kodus's technical infrastructure.

## Overview

This document outlines the architecture powering Kodus's infrastructure. Our system is built on a distributed architecture that leverages containerization and network segmentation to ensure maximum scalability, security, and maintainability.

## Networks and Key Components

The infrastructure is divided into Docker networks that separate public access
from internal service traffic:

* shared-network: Public-facing services and edge routing
* kodus-backend-services: Internal service-to-service communication
* monitoring-network: Metrics and observability traffic (optional)

## Components

```mermaid theme={null}
graph LR
    Web[Kodus Web App] --> API[API Service]
    API --> RabbitMQ[(RabbitMQ)]
    Webhooks[Webhooks Service] --> API
    API --> Worker[Worker Service]
    Worker --> RabbitMQ
    API --> Postgres[(Postgres)]
    API --> Mongo[(MongoDB)]
    Worker --> Postgres
    Worker --> Mongo
```

### 1. Kodus Web Application

Our frontend platform is built with Next.js, delivering a seamless user experience through direct communication with our API layer.

### 2. Core Backend Services

The 2.0 stack splits backend responsibilities into dedicated services:

* API: Central service layer handling business logic and request processing
* Worker: Asynchronous processing for queues and background jobs
* Webhooks: Dedicated service for Git provider webhooks

### 3. MCP Manager

MCP Manager catalogs providers and integrations, then exposes them to Kodus so
teams can install MCPs from the Plugins screen.

### 4. Data Stores

Kodus uses two databases:

* Postgres: Relational data and embeddings metadata
* MongoDB: Flexible document storage

### 5. Messaging and Observability

RabbitMQ is required for 2.0, providing reliable asynchronous communication
between API, worker, and webhooks.

Prometheus and Grafana are optional and used for monitoring and visualization.

### 6. Auxiliary Services (Kodus Cloud)

Kodus Cloud includes closed-source auxiliary services (billing, analytics, and
chat integrations) that are not required for self-hosted deployments.

## Next Steps

<CardGroup>
  <Card title="Run Kodus Locally" icon="laptop" href="/how_to_deploy/en/local_quickstart/orchestrator">
    Ideal for local development and getting familiar with the full Kodus stack.
  </Card>

  <Card title="Deploy Kodus to Production" icon="rocket" href="/how_to_deploy/en/deploy_kodus/generic_vm">
    Perfect for production deployment and experiencing the full capabilities of Kodus.
  </Card>
</CardGroup>


# Local Quickstart
Source: https://docs.kodus.io/how_to_deploy/en/local_quickstart/orchestrator

Get Kodus running on your local machine — API, Worker, Webhooks, Web UI, and all dependencies in one command.

<Note>
  This guide is for local development purposes. For production deployment,
  please refer to the [Deploy Kodus](/how_to_deploy/en/deploy_kodus/generic_vm)
  guide.
</Note>

<Note>
  Local dev runs with `API_CLOUD_MODE=false`, which is the same mode as a
  self-hosted instance — and which means the daily anonymous heartbeat to
  `telemetry.kodus.io` is enabled by default. If you don't want your local
  experiments showing up in the fleet, set `KODUS_TELEMETRY_DISABLED=true`
  in your `.env`. See [Anonymous Telemetry](/how_to_deploy/en/deploy_kodus/telemetry)
  for what is sent and how to inspect it.
</Note>

## Prerequisites

* Node.js (LTS version)
* Docker
* Yarn or NPM
* LLM API Keys

## Running the project

<Tabs>
  <Tab title="Automated Setup (Recommended)">
    For a quick and automated setup, use our setup script:

    ```bash theme={null}
    git clone https://github.com/kodustech/kodus-ai.git
    cd kodus-ai
    yarn setup
    ```

    This script will automatically:

    * ✅ Check all required dependencies (Node.js, Yarn, Docker, OpenSSL)
    * ✅ Install project dependencies
    * ✅ Create and configure the `.env` file
    * ✅ Generate all required security keys automatically
    * ✅ Set up Docker networks
    * ✅ Provide clear next steps

    ### Choose your LLM mode (required)

    Select one mode and fill your .env before starting the services.

    <Snippet />

    ### Next steps

    **Basic setup:**

    ```bash theme={null}
    yarn docker:start
    yarn migrate:dev
    yarn seed
    ```

    **With external integrations (webhooks, etc.):**

    ```bash theme={null}
    yarn docker:start
    yarn migrate:dev
    yarn seed
    yarn tunnel  # Creates public endpoint for external services
    ```

    Once everything is running, open **[http://localhost:3000](http://localhost:3000)** in your browser.
  </Tab>

  <Tab title="Manual Setup">
    If you prefer to configure everything manually:

    ### 1. Clone the repository

    ```bash theme={null}
    git clone https://github.com/kodustech/kodus-ai.git
    ```

    ### 2. Install dependencies

    ```bash theme={null}
    yarn install
    ```

    ### 3. Configure environment variables

    ```bash theme={null}
    cp .env.example .env
    ```

    ### 4. Choose your LLM mode (required)

    Select one mode and fill your .env before starting the services.

    <Snippet />

    ### 5. Generate Security Keys

    Before configuring your environment variables, you'll need to generate secure keys for JWT tokens and other security-related configurations:

    ```bash theme={null}
    # For most security keys (JWT secrets, etc.)
    openssl rand -base64 32

    # For crypto keys and code management secrets
    openssl rand -hex 32

    # For webhook tokens (URL-safe)
    openssl rand -base64 32 | tr -d '=' | tr '/+' '_-'
    ```

    You'll need to generate values for these security keys:

    * `JWT_SECRET` (use `openssl rand -base64 32`)
    * `JWT_REFRESH_SECRET` (use `openssl rand -base64 32`)
    * `CODE_MANAGEMENT_SECRET` (use `openssl rand -hex 32`)
    * `CODE_MANAGEMENT_WEBHOOK_TOKEN` (use `openssl rand -base64 32 | tr -d '=' | tr '/+' '_-'`)

    ### 6. Set up Docker networks

    Create the required Docker networks:

    ```bash theme={null}
    docker network create kodus-backend-services || true
    docker network create shared-network || true
    ```

    ### 7. Starting the development environment

    Launch the services using Docker:

    ```bash theme={null}
    yarn docker:start
    ```

    This command starts:

    * Kodus API
    * Worker (async jobs)
    * Webhooks service
    * Kodus Web Application
    * PostgreSQL database
    * MongoDB database
    * RabbitMQ
    * Required network configurations

    To also create a public endpoint for external services:

    ```bash theme={null}
    yarn tunnel
    ```

    ### 8. First-time setup

    If this is your first time running the project, execute the following commands:

    Run database migrations:

    ```bash theme={null}
    yarn migrate:dev
    ```

    Seed initial data:

    ```bash theme={null}
    yarn seed
    ```

    ### 9. Service endpoints

    Access the services at:

    * Web UI: `http://localhost:3000`
    * API: `http://localhost:3001`
    * RabbitMQ Management: `http://localhost:15672`
    * Debug Port: `9229`
  </Tab>
</Tabs>

## Development workflow

### Basic Local Development

1. **Start services**: `yarn docker:start`
2. **Run migrations**: `yarn migrate:dev`
3. **Load seed data**: `yarn seed`
4. **Open the app**: Visit `http://localhost:3000`
5. **Health check**: `yarn dev:health-check`

### Development with External Integrations

If you need to test integrations with external services (like Git webhooks):

1. **Start services**: `yarn docker:start && yarn migrate:dev && yarn seed`
2. **Create tunnel**: `yarn tunnel` (creates public endpoint)
3. **Update webhook URLs**: The tunnel command updates your `.env` automatically
4. **Configure Git provider**: Use the tunnel URL in your Git provider webhook settings
5. **Test integration**: Trigger webhooks and monitor logs

<Info>
  **Tunnel Benefits:**

  * Test real webhook integrations locally
  * Debug external service communications
  * Share your development environment with team members
  * Test mobile apps or other external clients
</Info>

## Troubleshooting

### Quick Health Check

```bash theme={null}
yarn dev:health-check
```

This comprehensive health check validates:

* ✅ **Services**: Kodus API, Worker, Webhooks, Web, PostgreSQL, MongoDB, RabbitMQ
* 🔌 **Port availability**: Web (3000), API (3001), PostgreSQL (5432), MongoDB (27017), RabbitMQ (5672/15672)
* 🗄️ **Database setup**: Migrations and seed data
* 🌐 **API endpoints**: Health endpoints and basic connectivity

### Manual Verification

1. **Check Web UI**: Visit `http://localhost:3000` in your browser
2. **Check API health**: Visit `http://localhost:3001/health`
3. **Check RabbitMQ**: Visit `http://localhost:15672` (default credentials: `guest`/`guest`)
4. **Verify database connections**: Check the logs for successful database connections
5. **Test webhook endpoints**: Your Git provider webhooks should point to `http://localhost:3332/[provider]/webhook` (or to your API domain if a reverse proxy routes `/.../webhook` to the webhooks service)

### Setup Script Issues

If the automated setup script (`yarn setup`) fails:

**Missing dependencies:**

```bash theme={null}
# Check if all required tools are installed
node --version
yarn --version
docker --version
openssl version
```

**Permission issues with Docker:**

```bash theme={null}
# Add your user to the docker group (Linux/macOS)
sudo usermod -aG docker $USER
# Then log out and log back in
```

**Network creation errors:**

```bash theme={null}
# Check if networks already exist
docker network ls | grep kodus
# Remove conflicting networks if needed
docker network rm kodus-backend-services shared-network
```

### Common Issues

**Port conflicts:**

* Ensure ports 3000 (Web), 3001 (API), 5432 (PostgreSQL), 27017 (MongoDB), and 5672/15672 (RabbitMQ) are available
* Stop other services using these ports before starting Kodus

**Environment variables not loading:**

* Verify your `.env` file exists in the project root
* Check that there are no trailing spaces in variable assignments
* Ensure all required security keys were generated properly

**Health check failures:**

* Run `yarn dev:health-check` to get detailed diagnostics
* Check if containers are fully started (wait 1-2 minutes after `yarn docker:start`)
* Verify database migrations and seed data are loaded
* Check API logs with `yarn docker:logs` for startup errors

**API not responding:**

* The API takes time to fully initialize after container startup
* Check if migrations and seed data are loaded
* Verify the `.env` file has all required variables
* Run health check to see which specific components are failing

**Webhook issues with external services:**

* Use `yarn tunnel` to create a public endpoint for external webhooks
* Update your Git provider webhook URLs to use the tunnel URL
* Ensure the tunnel is running when testing webhook integrations
* Check tunnel logs for connection issues


# Creating a Webhook
Source: https://docs.kodus.io/how_to_deploy/en/platforms/azure_devops/azdevops_webhook



Kody usually creates the webhook automatically when you connect an Azure DevOps project. This page covers the **manual setup** path you take when automatic registration didn't happen — typically on self-hosted installs or in Azure projects where Kody can't create service hooks on your behalf.

<Note>
  Webhook URLs must reach the Webhooks service (port 3332). Using the API domain only works if your reverse proxy routes `/.../webhook` paths to the Webhooks service.
</Note>

## Azure Repos webhook URL requires a signed token

Unlike GitHub, GitLab, Bitbucket and Forgejo, Azure Repos webhook requests **must include an encrypted `token` query parameter**. Kodus validates this token on every incoming request and rejects calls without it with `403 Unauthorized`. The token is derived from two environment variables you already configured during self-hosted setup:

* `CODE_MANAGEMENT_SECRET` — the 32-byte encryption key (hex-encoded).
* `CODE_MANAGEMENT_WEBHOOK_TOKEN` — the plaintext the key encrypts.

So the Azure webhook URL looks like:

```
https://kodus-api.yourdomain.com/azure-repos/webhook?token=<generated>
```

The `<generated>` value is produced by encrypting `CODE_MANAGEMENT_WEBHOOK_TOKEN` with `CODE_MANAGEMENT_SECRET` using AES-256-CBC, formatted as `<ivHex>:<cipherHex>`.

<Note>
  Kody generates this token automatically when it creates the webhook for you via the UI-driven integration flow. You only need to generate it by hand when you're registering the webhook manually in Azure DevOps.
</Note>

## Generating the webhook token

Pick the option that matches your environment. Both use the env vars that your Kodus stack already has configured — you do **not** need to clone the repository.

### Option A — inside the running Kodus container (recommended)

Run this against an already-running `api` container. The env vars are already in scope:

```bash theme={null}
docker compose exec api node -e "
const crypto = require('crypto');
const key = Buffer.from(process.env.CODE_MANAGEMENT_SECRET, 'hex');
const iv = crypto.randomBytes(16);
const c = crypto.createCipheriv('aes-256-cbc', key, iv);
let e = c.update(process.env.CODE_MANAGEMENT_WEBHOOK_TOKEN, 'utf8', 'hex');
e += c.final('hex');
console.log(iv.toString('hex') + ':' + e);
"
```

The output is the value you paste as `?token=...` on the webhook URL. Example:

```
8f3c1a4b9e2d6f8a1c3e5f7091a4b7c2:d1e9a23c78...
```

### Option B — locally with Node (no Docker)

If your Kodus stack is not running or you want to generate the token on a different machine, export the two env vars and run:

```bash theme={null}
export CODE_MANAGEMENT_SECRET="<same value as in your .env>"
export CODE_MANAGEMENT_WEBHOOK_TOKEN="<same value as in your .env>"

node -e "
const crypto = require('crypto');
const key = Buffer.from(process.env.CODE_MANAGEMENT_SECRET, 'hex');
const iv = crypto.randomBytes(16);
const c = crypto.createCipheriv('aes-256-cbc', key, iv);
let e = c.update(process.env.CODE_MANAGEMENT_WEBHOOK_TOKEN, 'utf8', 'hex');
e += c.final('hex');
console.log(iv.toString('hex') + ':' + e);
"
```

<Warning>
  Both env var values must match **exactly** the ones your Kodus API container is using. A key mismatch produces a valid-looking token that Kodus will reject with `403 Unauthorized`.
</Warning>

<Tip>
  The token does not expire — you can reuse the same generated value for every Azure Repos webhook in your organization. Rotate it only if you rotate `CODE_MANAGEMENT_SECRET` or `CODE_MANAGEMENT_WEBHOOK_TOKEN`.
</Tip>

## Creating the webhook subscription in Azure DevOps

1. Navigate to your Azure DevOps project.

2. Click **Project settings** in the bottom-left corner.

3. Under **General**, select **Service hooks**.

4. Click **+ Create subscription**.

5. Configure the webhook:

   * **Service:** **Web Hooks**

   * **Trigger on this type of event:** select one of the supported events (see below)

   * **URL:** your Kodus Azure Repos webhook URL with the token appended:

     ```
     https://kodus-api.yourdomain.com/azure-repos/webhook?token=<generated>
     ```

   * **Filters** (optional): filter by repository or branch if needed.

   * **Action:** send a POST request to the given URL.

6. Click **Finish**.

Create one subscription per event type. Kodus currently reacts to:

* `git.pullrequest.created` — Pull request created
* `git.pullrequest.updated` — Pull request updated
* `git.pullrequest.merge.attempted` — Pull request merge attempted
* `ms.vss-code.git-pullrequest-comment-event` — Pull request commented

<Note>
  Make sure the URL is reachable from Azure DevOps and accepts incoming POST requests on port 3332 (directly or through your reverse proxy).
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Azure sends the webhook but Kodus returns 403">
    The `?token=` value is missing, truncated, or was generated with a different `CODE_MANAGEMENT_SECRET` / `CODE_MANAGEMENT_WEBHOOK_TOKEN` than the one the running API uses. Regenerate the token with **Option A** (which guarantees it's produced with the same env vars the container is actually using) and update the subscription URL in Azure.
  </Accordion>

  <Accordion title="Webhook never arrives">
    Azure DevOps only retries failed deliveries a limited number of times. Check the **Service hooks** page — successful deliveries show a green check. If deliveries are failing with connection errors, verify the URL is reachable from the public internet and that your reverse proxy forwards `/.../webhook` paths to port 3332.
  </Accordion>

  <Accordion title="Works for one event but not others">
    Each event type needs its own subscription in Azure DevOps. If you only created "Pull request created", updates and comments won't trigger reviews.
  </Accordion>
</AccordionGroup>


# Creating a Webhook
Source: https://docs.kodus.io/how_to_deploy/en/platforms/bitbucket/bitbucket_webhook



Kodus usually creates the webhook automatically. If that didn't happen, follow these steps to set it up manually:

<Note>
  Webhook URLs must reach the Webhooks service (port 3332). Using the API domain only works if your reverse proxy routes `/.../webhook` paths to the webhooks service.
</Note>

1. Navigate to your Bitbucket repository

2. Click on "Repository settings" in the left sidebar

3. Select "Webhooks"

4. Click "Add webhook"

5. Time to configure your webhook:

   * **Title**: Kodus Code Review
   * **URL**: Drop in the URL where you want to receive notifications, the URL you put under `GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK` in the `.env` file
   * **Status**: Active
   * **SSL/TLS**: Check Enable SSL verification
   * **Triggers**: Select these events:
     * Repository:
       * Push
       * Updated
       * Commit comment created
       * Build status created
       * Build status updated
     * Issue
       * Created
       * Updated
       * Comment created
     * Pull Request
       * Created
       * Updated
       * Merged
       * Declined
       * Comment created
       * Comment deleted
       * Comment updated
       * Comment resolved
       * Comment reopened

6. Click "Save"

And that's it! You've successfully set up a webhook to do code reviews in your Bitbucket repository.


# Creating a Webhook
Source: https://docs.kodus.io/how_to_deploy/en/platforms/forgejo/forgejo_webhook



<Note>
  Forgejo support is maintained by the community.
</Note>

Kodus usually creates the webhook automatically. If that didn't happen, follow these steps to set it up manually:

<Note>
  Webhook URLs must reach the Webhooks service (port 3332). Using the API domain only works if your reverse proxy routes `/.../webhook` paths to the webhooks service.
</Note>

1. Navigate to your Forgejo repository

2. Click **Settings** in the right sidebar

3. Select **Webhooks**

4. Click **Add Webhook** → **Forgejo**

5. Configure your webhook:

   * **Target URL**: Enter the URL where you want to receive notifications, the URL you set for `GLOBAL_FORGEJO_CODE_MANAGEMENT_WEBHOOK` in your `.env` file
   * **HTTP Method**: POST
   * **POST Content Type**: `application/json`
   * **Trigger On**: Select these events:
     * Push events
     * Pull Request events
     * Issues events
     * Issue Comment events
   * **Active**: Check

6. Click **Add Webhook**

And that's it! You've successfully set up a webhook to do code reviews in your Forgejo repository.


# Creating a GitHub App
Source: https://docs.kodus.io/how_to_deploy/en/platforms/github/github_app



If you want to run Kody with a GitHub App, you need to create one. This app enables Kody to interact with your repositories, manage pull requests, and receive webhooks.

<Note>If you want to enable "Sign in with GitHub" for platform users, that's a separate OAuth App process and doesn't interfere with the GitHub App permissions. This guide focuses on the functional integration. See <a href="/how_to_deploy/en/platforms/github/github_oauth">GitHub OAuth App</a>.</Note>

## Prerequisites

Have your application domains ready:

* **WEB\_DOMAIN**: Your Frontend URL (e.g., `https://app.yourdomain.com` or `http://localhost:3000`)
* **API\_DOMAIN**: Your Backend/API URL (e.g., `https://api.yourdomain.com` or `http://localhost:3000` for monorepo/proxy setups)
* **WEBHOOK\_DOMAIN** (optional): Public domain for webhooks (e.g., `https://kodus-webhooks.yourdomain.com`). If you route `/.../webhook` on the API domain, you can use `API_DOMAIN`.

## Step 1: Create the GitHub App

1. On GitHub, go to **Settings** > **Developer Settings** > **GitHub Apps**
2. Click **New GitHub App**
3. Fill in the basic information (Name, Homepage URL) according to your preference

<img alt="GitHub Apps settings page highlighting the New GitHub App button" />

## Step 2: Configure Callback and Setup URLs

<img alt="GitHub App Webhook" />

This step is critical to ensure installation and redirection work properly. Fill in the fields below, replacing `WEB_DOMAIN` with your actual URL:

* **Callback URL**:
  ```
  WEB_DOMAIN/api/auth/callback/github
  ```
  This URL is used to complete the authorization flow.

* **Setup URL**:
  ```
  WEB_DOMAIN/setup/github
  ```

* Check the option: **Redirect on update**
  This ensures that after installing the app, users are redirected back to Kodus to complete the setup.

## Step 3: Configure the Webhook

The webhook notifies Kodus about events in your pull requests.

<Note>
  Webhooks are handled by a separate service (port 3332). If you use the API domain here, ensure your reverse proxy routes `/github/webhook` to the webhooks service. Otherwise use a dedicated webhooks domain.
</Note>

* **Webhook URL**:
  ```
  WEBHOOK_DOMAIN/github/webhook
  ```

* Make sure the **Active** option is checked

## Step 4: Collect Credentials and Add to .env

<img alt="GitHub App Webhook" />

Now you need to get the credentials generated by GitHub and add them to your Kodus environment variables.

### App ID

At the top of your app's "About" page, copy the **App ID**.

Add to your `.env`:

```
API_GITHUB_APP_ID=your_app_id_here
```

### Client Secret

Go to the **Client secrets** section and click **Generate a new client secret**.

Copy the generated value.

Add to your `.env`:

```
API_GITHUB_CLIENT_SECRET=your_client_secret_here
```

### Private Key

Scroll to the bottom of the page and click **Generate a private key**.

This will download a `.pem` file. Open this file with a text editor and copy the entire content.

Add to your `.env`:

```
API_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- ..."
```

### Installation URL

Open your GitHub App and click **Install App**. Copy the URL from the browser address bar (it looks like `https://github.com/apps/<app-slug>/installations/new`).

Add to your `.env`:

```
WEB_GITHUB_INSTALL_URL="https://github.com/apps/your-app/installations/new"
```

## Summary of Environment Variables

At the end, your configuration file should contain:

```bash theme={null}
API_GITHUB_APP_ID=123456
API_GITHUB_CLIENT_SECRET=example_secret_123
API_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- ..."
WEB_GITHUB_INSTALL_URL="https://github.com/apps/your-app/installations/new"
```

Click **Save Changes** on GitHub and restart your Kodus application to apply the changes.


# GitHub OAuth App (Sign in with GitHub)
Source: https://docs.kodus.io/how_to_deploy/en/platforms/github/github_oauth



Use this if you want users to sign in to Kodus with GitHub. This is separate from the GitHub App integration used for code review automation and webhooks.

## Prerequisites

* **WEB\_DOMAIN**: Your Frontend URL (e.g., `https://app.yourdomain.com` or `http://localhost:3000`)

## Step 1: Create the OAuth App

1. On GitHub, go to **Settings** > **Developer Settings** > **OAuth Apps**
2. Click **New OAuth App**
3. Fill in the basic information (Application name, Homepage URL)

<img alt="GitHub OAuth Apps page showing the new application form" />

## Step 2: Configure the Callback URL

Set the **Authorization callback URL** to:

```
WEB_DOMAIN/api/auth/callback/github
```

Make sure the URL matches your actual web domain and scheme (http/https).

## Step 3: Add Credentials to .env

After creating the app, copy the credentials from GitHub and add them to your Kodus environment:

```
WEB_OAUTH_GITHUB_CLIENT_ID="your_client_id_here"
WEB_OAUTH_GITHUB_CLIENT_SECRET="your_client_secret_here"
```

## Summary of Environment Variables

```bash theme={null}
WEB_OAUTH_GITHUB_CLIENT_ID="your_client_id_here"
WEB_OAUTH_GITHUB_CLIENT_SECRET="your_client_secret_here"
```

Restart the web application to apply the changes.


# Creating a Webhook
Source: https://docs.kodus.io/how_to_deploy/en/platforms/github/github_webhook



Kodus usually creates the webhook automatically. If that didn't happen, follow these steps to set it up manually:

<Note>
  Webhook URLs must reach the Webhooks service (port 3332). Using the API domain only works if your reverse proxy routes `/.../webhook` paths to the webhooks service.
</Note>

1. Head over to your GitHub repository

2. Click on "Settings"

3. Find "Webhooks" in the left sidebar

4. Click "Add webhook"

5. Configure your webhook:

   * **Payload URL**: Enter the URL from your `.env` file: `API_GITHUB_CODE_MANAGEMENT_WEBHOOK`
   * **Content type**: `application/json`
   * **Secret**: Leave blank
   * **SSL verification**: Enable SSL verification
   * **Which events would you like to trigger this webhook?**: Let me select individual events
   * Check these boxes:
     * Issue comment
     * Pull request review comments
     * Pull request review threads
     * Pull request reviews
     * Pull requests
     * Pushes

6. Click "Add webhook"

You've successfully set up a webhook for code reviews in your GitHub repository.


# GitLab OAuth App (Sign in with GitLab)
Source: https://docs.kodus.io/how_to_deploy/en/platforms/gitlab/gitlab_oauth



Use this if you want users to sign in to Kodus with GitLab. This is separate from the GitLab webhook integration used for code review automation.

## Prerequisites

* **WEB\_DOMAIN**: Your Frontend URL (e.g., `https://app.yourdomain.com` or `http://localhost:3000`)

## Step 1: Create the OAuth App

1. In GitLab, go to **User Settings** > **Applications**
2. Click **New application**
3. Fill in the application name and the redirect URI

## Step 2: Configure the Callback URL

Set the **Redirect URI** to:

```
WEB_DOMAIN/api/auth/callback/gitlab
```

Make sure the URL matches your actual web domain and scheme (http/https).

## Step 3: Configure Scopes

Set the scopes in GitLab to match the scopes below:

```
WEB_GITLAB_SCOPES="read_api read_user read_repository"
```

## Step 4: Add Credentials to .env

After creating the app, copy the credentials from GitLab and add them to your Kodus environment:

```
WEB_OAUTH_GITLAB_CLIENT_ID="your_client_id_here"
WEB_OAUTH_GITLAB_CLIENT_SECRET="your_client_secret_here"
WEB_GITLAB_SCOPES="read_api read_user read_repository"
WEB_GITLAB_OAUTH_URL="https://gitlab.com/oauth/authorize"
```

For self-managed GitLab, replace the OAuth URL with your instance domain (e.g., `https://gitlab.yourdomain.com/oauth/authorize`).

## Summary of Environment Variables

```bash theme={null}
WEB_OAUTH_GITLAB_CLIENT_ID="your_client_id_here"
WEB_OAUTH_GITLAB_CLIENT_SECRET="your_client_secret_here"
WEB_GITLAB_SCOPES="read_api read_user read_repository"
WEB_GITLAB_OAUTH_URL="https://gitlab.com/oauth/authorize"
```

Restart the web application to apply the changes.


# Creating a Webhook
Source: https://docs.kodus.io/how_to_deploy/en/platforms/gitlab/gitlab_webhook



Kodus usually creates the webhook automatically. If that didn't happen, follow these steps to set it up manually:

<Note>
  Webhook URLs must reach the Webhooks service (port 3332). Using the API domain only works if your reverse proxy routes `/.../webhook` paths to the webhooks service.
</Note>

1. Navigate to your GitLab project

2. Go to "Settings" > "Webhooks"

3. Configure your webhook:

   * **URL**: Enter the URL from your `.env` file: `API_GITLAB_CODE_MANAGEMENT_WEBHOOK`
   * **Check Show full URL**
   * **Name**: (optional) Kodus Code Review
   * **Description**: (optional) Kodus Code Review Webhook
   * **Secret token**: Leave blank
   * **SSL verification**: Enable SSL verification
   * **Trigger**: Select the following events:
     * Comments
     * Issue events
     * Merge request events

4. Click "Add webhook"

You've successfully set up a webhook for code reviews in your GitLab repository.


# Auto License Assignment
Source: https://docs.kodus.io/how_to_use/en/auto_license_assignment



The Auto License Assignment feature simplifies the management of developer licenses within your organization. Instead of manually assigning licenses to each developer, Kodus can automatically assign a license to active contributors.

## How it Works

When enabled, Kodus monitors pull request activity in your repositories.

* **Automatic Assignment:** If a user creates more than one pull request, Kodus checks if there are available license slots in your organization.
  * If a slot is available, the user is automatically assigned a license and their PRs will be reviewed.
  * If no slots are available, Kodus will react to the pull request with a thumbs down emoji (👎) for Github or a padlock emoji (🔒) for Gitlab to indicate that the review could not be performed due to a lack of licenses.

## Ignored Users

You can configure a list of **Ignored Users**. These users will be excluded from the auto-assignment process.

* **No Reviews:** Pull requests created by ignored users will not be reviewed by Kodus.
* **No Reactions:** Kodus will not react to their PRs, even if they exceed the PR limit. It will be as if Kodus ignored the PR entirely.

This is useful for bots, service accounts, or specific team members who do not require code reviews.

## Configuration

To enable and configure Auto License Assignment:

1. Go to your **Code Review Settings**.
2. Navigate to the **Subscription** tab.
3. Locate the **Auto-assign licenses** section.
   * Use the toggle to enable or disable the feature.
   * If enabled, you can select users to add to the **Ignored Users** list.


# BYOK - Bring Your Own Key
Source: https://docs.kodus.io/how_to_use/en/byok

Configure your own API keys for maximum flexibility and cost control. Available on every Kodus plan.

BYOK (Bring Your Own Key) is the **default way Kodus uses LLMs across every plan** — Community, Teams, and Enterprise. You connect your own provider account, pick a model, pay only for what you use, and monitor costs directly on your provider's dashboard. Kodus never marks up tokens and never sees your key in plain text.

<Card title="How this maps to plans" icon="scale-balanced" href="/how_to_use/en/pricing#byok-is-the-default-across-all-plans">
  BYOK is free on Community, included on Teams (\$10/active dev/month on top of your token spend), and one of two options on Enterprise (the other being a Kodus-managed API key).
</Card>

## Getting Started

The BYOK screen has two paths: pick a **recommended model** from the curated catalog (fastest path, 90% of cases) or **configure any provider manually** (escape hatch for custom endpoints or uncurated models).

<Info>
  **Who can edit this.** The BYOK page is **Owner-only** — configuring, testing, and deleting keys requires the **Owner** role. Other roles (Billing Manager, Repo Admin, Contributor) can't access `/organization/byok`. See [Workspace Roles](/how_to_use/en/workspace_roles).
</Info>

<Steps>
  <Step title="Open BYOK Settings">
    Go to [app.kodus.io/organization/byok](https://app.kodus.io/organization/byok).
  </Step>

  <Step title="Pick a recommended model">
    The **Main model** section shows a grid of curated models we've benchmarked for code review. Click any card to start connecting it.
  </Step>

  <Step title="Paste your API key and test">
    Each card expands inline with a single input — just the API key. Click **Test** to probe the provider, or **Test & save** to run the test and persist the config on success.
  </Step>

  <Step title="Add a Fallback (recommended)">
    Once the Main model is configured, a **Fallback model** section appears. If your main provider hits rate limits or goes down, Kodus falls back automatically.
  </Step>
</Steps>

<Info>
  **Test before saving.** The **Test** button probes your provider with a cheap metadata call (no LLM inference is performed). It catches invalid keys, wrong base URLs, and network issues before they break your first code review.
</Info>

## Recommended Models

These six models are curated for code review. They all appear in the catalog on `/organization/byok` and come pre-tuned with sensible defaults (temperature, max output tokens, and reasoning effort set to `medium`).

<CardGroup>
  <Card title="Claude Sonnet 4.6" icon="crown">
    **Best balance of quality and cost**

    Anthropic's latest Sonnet. Adaptive extended thinking, strong cross-file analysis, 200K context window.

    * **Provider:** Anthropic
    * **Model ID:** `claude-sonnet-4-6`
    * **Key:** [console.anthropic.com](https://console.anthropic.com/settings/keys)
  </Card>

  <Card title="Claude Opus 4.7" icon="star">
    **Flagship quality**

    Top-tier Anthropic model for the hardest reviews. 1M context, premium price.

    * **Provider:** Anthropic
    * **Model ID:** `claude-opus-4-7`
    * **Key:** [console.anthropic.com](https://console.anthropic.com/settings/keys)
  </Card>

  <Card title="Gemini 3.1 Pro (custom tools)" icon="brain">
    **Largest context**

    Google's flagship with custom-tools support. 1M context window — strongest on large PRs and monorepos.

    * **Provider:** Google Gemini
    * **Model ID:** `gemini-3.1-pro-preview-customtools`
    * **Key:** [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
  </Card>

  <Card title="GPT-5.4" icon="sparkles">
    **Fast and consistent**

    OpenAI's latest flagship. Reliable low latency, broad knowledge, 400K context.

    * **Provider:** OpenAI
    * **Model ID:** `gpt-5.4`
    * **Key:** [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
  </Card>

  <Card title="Kimi K2.6 Coding" icon="moon">
    **Coding-specialized, cheap**

    Moonshot AI's coding-tuned model. Two plans: Developer API (pay-per-token) or Kimi Code Plan (subscription with dedicated endpoint).

    * **Provider:** OpenAI-compatible (Moonshot AI)
    * **Model ID:** `kimi-k2.6`
    * **Keys:** [platform.moonshot.ai](https://platform.moonshot.ai/console/api-keys) or [kimi.com/code](https://www.kimi.com/code)
  </Card>

  <Card title="GLM 5.1" icon="bolt">
    **Best subscription value**

    Z.ai's latest. Two plans: Developer API (pay-per-token) or GLM Coding Plan (flat-rate subscription).

    * **Provider:** OpenAI-compatible (Z.ai)
    * **Model ID:** `glm-5.1`
    * **Keys:** [z.ai console](https://z.ai/manage-apikey/apikey-list) or [z.ai/subscribe](https://z.ai/subscribe)
  </Card>
</CardGroup>

<Info>
  **Our default recommendation:** Start with **Claude Sonnet 4.6** for the best overall code-review experience. If cost is the priority, **GLM 5.1 on the Coding Plan** or **Kimi K2.6 on the Kimi Code Plan** give flat-rate subscriptions that cap your monthly spend.
</Info>

## Plan selector (GLM 5.1 and Kimi K2.6)

Z.ai and Moonshot both offer a subscription plan with a **different endpoint** than their pay-per-token Developer API. The curated card for each of these models shows a **Plan** selector so you can pick the right endpoint before pasting your key.

<Tabs>
  <Tab title="GLM 5.1 (Z.ai)">
    | Plan              | Endpoint                              | Keys from                                                    | Best for                                  |
    | ----------------- | ------------------------------------- | ------------------------------------------------------------ | ----------------------------------------- |
    | **Developer API** | `https://api.z.ai/api/paas/v4/`       | [z.ai/manage-apikey](https://z.ai/manage-apikey/apikey-list) | Bursty workloads, pay-per-token           |
    | **Coding Plan**   | `https://api.z.ai/api/coding/paas/v4` | [z.ai/subscribe](https://z.ai/subscribe)                     | Predictable team volume, flat monthly fee |

    <Warning>
      GLM Coding Plan keys **only** work on `/api/coding/paas/v4`. The Lite and Pro tiers are often capped at **1 concurrent request** — Kodus pre-fills `maxConcurrentRequests=1` when you pick this plan. Bump it in Advanced settings if you're on the Max tier (up to 30).
    </Warning>
  </Tab>

  <Tab title="Kimi K2.6 (Moonshot AI)">
    | Plan               | Endpoint                         | Keys from                                                             | Best for                                             |
    | ------------------ | -------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------- |
    | **Developer API**  | `https://api.moonshot.ai/v1`     | [platform.moonshot.ai](https://platform.moonshot.ai/console/api-keys) | Pay-per-token, concurrency scales with recharge tier |
    | **Kimi Code Plan** | `https://api.kimi.com/coding/v1` | [kimi.com/code](https://www.kimi.com/code)                            | Subscription with dedicated coding endpoint          |

    <Info>
      Kimi Code Plan is documented at a cap of 30 concurrent requests. Kodus pre-fills `maxConcurrentRequests=30` when you pick that plan.
    </Info>
  </Tab>
</Tabs>

## Configure manually

When the model you want isn't in the curated list (custom endpoint, self-hosted LLM, or a provider we haven't benchmarked), click **Configure manually** at the bottom of the catalog. This opens `/organization/byok/manual?slot=main` — a step-by-step wizard:

<Steps>
  <Step title="Pick a provider">
    Choose from OpenAI, Anthropic, Google Gemini, OpenRouter, Novita, or **OpenAI Compatible** (for any OpenAI-format endpoint).
  </Step>

  <Step title="Enter the base URL (if required)">
    OpenAI-compatible providers need an explicit base URL. The field only appears when you pick that provider.
  </Step>

  <Step title="Pick or type the model ID">
    If Kodus can list models from the provider, you get a dropdown. Otherwise (e.g. self-hosted or when platform keys aren't configured), type the exact model ID manually.
  </Step>

  <Step title="Paste the API key">
    The key field appears once provider and model are set.
  </Step>

  <Step title="Tune advanced settings (optional)">
    Temperature, max tokens, reasoning effort, and max concurrent requests — all optional. Defaults are sensible for most providers.
  </Step>

  <Step title="Test and save">
    Click **Test & save** to run the connection probe and persist on success.
  </Step>
</Steps>

<Tip>
  The same manual route works for Fallback — navigate with `?slot=fallback`, or use the **Add fallback** link after Main is saved.
</Tip>

## Supported Providers

<Tabs>
  <Tab title="OpenAI">
    **Best for:** Latest GPT models and reliable performance.

    **Get an API key:**

    1. Visit [OpenAI API Keys](https://platform.openai.com/api-keys)
    2. Create a new key for Kodus
    3. Add billing information
  </Tab>

  <Tab title="Google Gemini">
    **Best for:** Large-context reviews (1M tokens) and competitive pricing.

    **Get an API key:**

    1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey)
    2. Create a new key
    3. Enable billing in Google Cloud Console
  </Tab>

  <Tab title="Anthropic Claude">
    **Best for:** Nuanced analysis and adaptive extended thinking.

    **Get an API key:**

    1. Visit [Anthropic Console](https://console.anthropic.com/)
    2. Create an account and generate a key
    3. Add credits
  </Tab>

  <Tab title="Novita AI">
    **Best for:** Open-source models at competitive prices.

    **Get an API key:**

    1. Sign up at [Novita AI](https://novita.ai/)
    2. Navigate to API settings
    3. Generate a key

    <Card title="Novita Setup Guide" icon="rocket" href="/cookbook/en/novita">
      Detailed setup with screenshots.
    </Card>
  </Tab>

  <Tab title="OpenRouter">
    **Best for:** One billing relationship across many models.

    **Get an API key:**

    1. Create an account at [OpenRouter](https://openrouter.ai/)
    2. Add credits
    3. Generate a key in settings

    <Warning>
      OpenRouter routes each request to a different upstream provider by default, which can cause quality and latency drift between calls. **Pin specific upstreams** under Advanced settings → OpenRouter routing to keep behavior stable. See [Pinning OpenRouter providers](#pinning-openrouter-providers).
    </Warning>
  </Tab>

  <Tab title="OpenAI Compatible">
    **Best for:** Specialized providers (Moonshot, Z.ai, Fireworks, Together, Groq, DeepSeek) or self-hosted endpoints.

    **How to configure:**

    1. In the manual wizard, pick **OpenAI Compatible** as the provider.
    2. Enter the base URL (e.g. `https://api.moonshot.ai/v1`, `https://api.z.ai/api/paas/v4/`, `https://api.fireworks.ai/inference/v1`).
    3. Provide the key and model ID.

    <CardGroup>
      <Card title="Z.ai (GLM) guide" href="/knowledge_base/en/how-to-use-z-ai-with-kodus" icon="bolt">
        Full Z.ai setup with Coding Plan details.
      </Card>

      <Card title="Moonshot (Kimi) guide" href="/knowledge_base/en/how-to-use-moonshot-with-kodus" icon="moon">
        Kimi K2.6 + Kimi Code Plan setup.
      </Card>

      <Card title="Fireworks AI" href="/knowledge_base/en/how-to-use-fireworks-with-kodus" icon="fire">
        Fireworks-specific setup.
      </Card>

      <Card title="Together AI" href="/knowledge_base/en/how-to-use-together-ai-with-kodus" icon="handshake">
        Together AI setup.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

## Reasoning / Extended Thinking

All six recommended models support reasoning. The BYOK form exposes a **Thinking** toggle (Off / Low / Medium / High / Custom) under **Advanced settings**, pre-filled to **Medium** for every recommended model.

### Preset levels

When you pick Low / Medium / High, Kodus translates the level to each provider's native format automatically:

| Provider                                     | How "medium" maps                                                       |
| -------------------------------------------- | ----------------------------------------------------------------------- |
| **Anthropic** (Claude Sonnet 4.6 / Opus 4.7) | `thinking: { type: "adaptive" }` + `outputConfig: { effort: "medium" }` |
| **Google** (Gemini 3.1 Pro)                  | `thinkingConfig: { thinkingLevel: "medium" }`                           |
| **OpenAI** (GPT-5.4)                         | `reasoningEffort: "medium"`                                             |
| **OpenRouter**                               | `reasoning: { effort: "medium" }`                                       |
| **OpenAI-compatible** (Kimi K2.6 / GLM 5.1)  | `thinking: { type: "enabled" }` — binary on/off, level ignored          |

<Note>
  Kimi and GLM currently expose reasoning as a single on/off flag. Picking Low, Medium, or High all emit the same payload (thinking enabled). When their APIs add level granularity, Kodus will start forwarding it.
</Note>

### Custom JSON override

Picking **Custom** in the Thinking toggle reveals a JSON textarea. Paste the provider options directly — **Kodus auto-wraps them under the active provider's namespace**. You don't need to know the Vercel AI SDK routing rules.

Use this when:

* You need a specific `budgetTokens` value for Claude (instead of the preset effort mapping)
* You want to enable/disable thinking on a per-model basis for OpenAI-compatible providers
* You want fields beyond reasoning — **caching, service tier, safety settings, `user` tagging, etc.** The override is merged into `providerOptions`, so any adapter field passes through
* The provider ships a new field Kodus hasn't wrapped yet

#### Examples (paste directly — no namespace needed)

<Tabs>
  <Tab title="Anthropic">
    Override Claude's thinking budget to exactly 20,000 tokens:

    ```json theme={null}
    {
      "thinking": { "type": "enabled", "budgetTokens": 20000 }
    }
    ```

    Enable prompt caching (non-reasoning example):

    ```json theme={null}
    {
      "cacheControl": { "type": "ephemeral" }
    }
    ```
  </Tab>

  <Tab title="Google Gemini">
    Explicit thinking budget (Gemini 2.5) or level (Gemini 3+):

    ```json theme={null}
    {
      "thinkingConfig": { "thinkingBudget": 16000 }
    }
    ```

    Adjust safety settings:

    ```json theme={null}
    {
      "safetySettings": [
        { "category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_NONE" }
      ]
    }
    ```
  </Tab>

  <Tab title="OpenAI">
    Reasoning with OpenAI-specific fields:

    ```json theme={null}
    {
      "reasoningEffort": "high",
      "serviceTier": "flex",
      "store": false,
      "user": "kodus-review"
    }
    ```
  </Tab>

  <Tab title="OpenRouter">
    Force reasoning + ignore a specific upstream:

    ```json theme={null}
    {
      "reasoning": { "effort": "high" },
      "ignore": ["deepinfra"]
    }
    ```
  </Tab>

  <Tab title="OpenAI-compatible (Kimi, GLM, etc.)">
    Enable thinking with a budget hint:

    ```json theme={null}
    {
      "thinking": { "type": "enabled", "budget_tokens": 25000 }
    }
    ```

    Explicitly disable thinking:

    ```json theme={null}
    {
      "thinking": { "type": "disabled" }
    }
    ```

    <Warning>
      Fields the upstream provider doesn't recognize (e.g. `budget_tokens` on a server that ignores it) are silently dropped. Check the provider's docs to confirm what they accept.
    </Warning>
  </Tab>
</Tabs>

#### Going manual with namespaces (power users)

If your JSON already contains a known namespace key at the top level (`anthropic`, `google`, `openai`, `openrouter`, `openaiCompatible`), Kodus leaves it untouched. Useful if you want to mix multiple provider namespaces or be explicit:

```json theme={null}
{
  "openrouter": {
    "reasoning": { "effort": "high" },
    "provider": { "order": ["moonshot"], "allow_fallbacks": false }
  }
}
```

Under the hood, these are the namespace mappings Kodus uses:

| BYOK provider                     | Namespace key      |
| --------------------------------- | ------------------ |
| `anthropic`                       | `anthropic`        |
| `google_gemini` / `google_vertex` | `google`           |
| `openai`                          | `openai`           |
| `open_router`                     | `openrouter`       |
| `openai_compatible` / `novita`    | `openaiCompatible` |

#### Gotchas

* **Valid JSON only.** Missing commas or trailing commas break the parse and Kodus ignores the override.
* **Precedence:** the JSON override **fully replaces** the effort-preset's namespace block — if you override `anthropic.thinking` but forget `anthropic.outputConfig`, that field won't be sent. OpenRouter routing (Pin providers / Allow fallbacks) is the one exception: it deep-merges with your override under `openrouter`.
* **Unknown provider = no wrap.** If your BYOK provider isn't in the namespace table above, Kodus passes the JSON through as-is. Rare — only applies if you configure a provider Kodus doesn't recognize.

## Pinning OpenRouter providers

OpenRouter is a router — when you request a model (e.g. `moonshotai/kimi-k2.5`), it forwards the call to one of several upstream providers (Moonshot direct, Together, Groq, Fireworks, Novita…). Each call can land on a different backend. That's convenient, but it introduces silent variance:

* **Quality drift** — upstreams run different precisions (FP8, INT4, full) and give subtly different outputs for identical prompts
* **Tool-calling inconsistency** — some backends don't support function calling the same way, leading to malformed tool use
* **Reasoning format variance** — one upstream honors `reasoning_effort`, another only `thinking.enabled`, another ignores both
* **Latency swings** — p50 can jump from 800ms to 4s between calls as routing changes
* **Rate-limit surprises** — you hit quota on a backend you didn't explicitly choose

### How to pin

When your BYOK provider is **OpenRouter**, the Advanced settings panel shows an **OpenRouter routing** section with two fields:

* **Pin providers (in order)** — comma-separated list of upstream names (e.g. `moonshot, together`). OpenRouter tries them in order and uses the first available.
* **Allow fallbacks** — when off, requests hard-fail if none of the pinned providers are available. When on (default), OpenRouter can fall back to any other upstream that serves the model.

<Tip>
  For a **stable** setup, pin a single provider and turn off fallbacks (`Pin: moonshot`, `Allow fallbacks: off`). Requests will always hit the same upstream or fail loudly — no silent quality changes. The tradeoff is zero resilience if that one upstream goes down; pair it with a different BYOK Fallback (e.g. Anthropic) to absorb outages.
</Tip>

<Warning>
  Upstream names must match OpenRouter's catalog. Check the provider tags on [openrouter.ai/docs/features/provider-routing](https://openrouter.ai/docs/features/provider-routing) — common values include `moonshot`, `together`, `groq`, `fireworks`, `novita`.
</Warning>

Under the hood, Kodus emits this into the Vercel AI SDK call:

```json theme={null}
{
  "openrouter": {
    "provider": {
      "order": ["moonshot", "together"],
      "allow_fallbacks": false
    }
  }
}
```

### Advanced: raw JSON override

If you need fields beyond `order` and `allow_fallbacks` (e.g. `ignore`, `data_collection`, `require_parameters`), switch **Thinking** to **Custom** in Advanced settings and paste the full routing payload — it's merged into `providerOptions` alongside any reasoning config:

```json theme={null}
{
  "openrouter": {
    "provider": {
      "order": ["moonshot"],
      "allow_fallbacks": false,
      "ignore": ["deepinfra"],
      "data_collection": "deny"
    },
    "reasoning": { "effort": "medium" }
  }
}
```

## Concurrency and rate limits

The `maxConcurrentRequests` field (under **Advanced settings**) caps how many inflight requests Kodus sends to your provider in parallel. Most of the time, the default is fine — but subscription plans with strict concurrency caps need it set explicitly.

### Defaults Kodus pre-fills

| Provider / plan                              | Pre-filled value    | Why                                                                                |
| -------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------- |
| **GLM Coding Plan (Lite/Pro)**               | `1`                 | Subscription allows only one in-flight request. Going higher triggers 429s.        |
| **GLM Coding Plan (Max)**                    | `1` (bump manually) | Max allows up to 30, but we default to the safe value. Raise in Advanced settings. |
| **Kimi Code Plan**                           | `30`                | Moonshot's documented cap on the coding endpoint.                                  |
| **GLM Developer API**                        | *(empty)*           | Limits scale per key; no sensible global default.                                  |
| **Kimi Developer API**                       | *(empty)*           | Scales with your recharge tier (Tier 1 ≈ 50, Tier 5 ≈ 1000).                       |
| **Anthropic / OpenAI / Google / OpenRouter** | *(empty)*           | Providers enforce their own TPM/RPM; Kodus doesn't cap.                            |

### When to tune it

<CardGroup>
  <Card title="Raise it" icon="arrow-up">
    * You have a high-tier recharge on Moonshot/OpenRouter and want higher throughput on big PRs
    * You bumped your GLM Coding Plan to **Max** and want to use the full 30-concurrent budget
    * Reviews feel serialized on multi-file PRs and you're not seeing 429s
  </Card>

  <Card title="Lower it" icon="arrow-down">
    * You see `429` or `Too much concurrency` errors in review logs
    * Your provider warns about rate limits on the dashboard
    * You want to conserve Coding Plan window (5h/weekly) across more PRs
  </Card>
</CardGroup>

<Tip>
  **Concurrency vs. RPM vs. TPM.** `maxConcurrentRequests` only caps parallel inflight requests. Many providers also enforce separate **RPM** (requests per minute) and **TPM** (tokens per minute) limits. If you're hitting RPM/TPM while concurrency looks fine, the fix is usually to upgrade your tier or spread load across time — not to change `maxConcurrentRequests`.
</Tip>

<Note>
  **Fallback interaction.** When Main hits a 429 and Kodus fails over to the Fallback model, the Fallback's own `maxConcurrentRequests` applies. Setting a generous Fallback on a different provider is a good way to absorb bursts when your Main is on a tight subscription.
</Note>

## Best Practices

### Security

<CardGroup>
  <Card title="Dedicated Keys" icon="shield-check">
    Create separate API keys for Kodus. Makes usage auditing and key rotation easier.
  </Card>

  <Card title="Regular Rotation" icon="arrows-rotate">
    Rotate keys periodically and update them in BYOK settings.
  </Card>

  <Card title="Monitor Usage" icon="chart-bar">
    Check your provider dashboards for unusual patterns.
  </Card>

  <Card title="Secure Storage" icon="lock">
    Never commit keys to repositories. Kodus stores them encrypted at rest and in transit.
  </Card>
</CardGroup>

### Fallback Strategy

* Use a **different provider** for Main and Fallback (e.g. Anthropic main, Google fallback). Protects against provider-specific outages.
* Subscriptions with tight concurrency limits (GLM Coding Plan Lite/Pro, Kimi Code Plan) make poor solo configurations — pair them with a pay-per-token Fallback so bursty PRs don't starve.

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Invalid API key' when clicking Test">
    * Copy the key without extra spaces, quotes, or trailing newlines.
    * Confirm billing is enabled and the account has credits.
    * For GLM Coding Plan / Kimi Code Plan keys, make sure you picked the matching **Plan** in the card — subscription keys don't work on the Developer API endpoint and vice versa.
  </Accordion>

  <Accordion title="'Endpoint not found' when clicking Test">
    * Verify the base URL matches the provider exactly (trailing slash matters for some).
    * For OpenAI-compatible providers, the models endpoint is usually `{baseURL}/models`.
  </Accordion>

  <Accordion title="Model not found at review time (key test passed)">
    * The **Test** button validates the key/endpoint but doesn't verify the specific model ID. If you typed a model that doesn't exist (typo), the first real review fails.
    * Cross-check the model ID against the provider's catalog before saving.
  </Accordion>

  <Accordion title="'Rate limited' or 'Too much concurrency'">
    * Lower **Max concurrent requests** in Advanced settings.
    * On GLM Coding Plan Lite/Pro, stay at **1 concurrent**. Upgrade to Max (30 concurrent) if you need more throughput.
    * On Kimi Code Plan, the documented cap is **30 concurrent**.
  </Accordion>

  <Accordion title="Self-hosted env vars not showing">
    * If Kodus is configured via `.env` (self-hosted Fixed Mode), the BYOK screen shows a blue info banner with the active provider/model — the key is never displayed for security.
    * Saving a BYOK config on top of `.env` prompts a confirm dialog before overriding.
  </Accordion>

  <Accordion title="High or unexpected costs">
    * Reasoning adds tokens. If cost is spiking, lower **Thinking** from Medium to Low, or switch to a cheaper model for Main.
    * Check your provider dashboard for the per-model breakdown.
    * Set a monthly cap at the provider level.
  </Accordion>
</AccordionGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I switch providers anytime?">
    Yes. The change takes effect for the next review — no redeploy required.
  </Accordion>

  <Accordion title="What happens if my API key runs out of credits?">
    Reviews automatically switch to the Fallback model if one is configured. Without a Fallback, the review fails and returns an error. Always configure a Fallback.
  </Accordion>

  <Accordion title="How does the primary/fallback system work?">
    Main handles every review by default. If it fails (rate limit, 5xx, timeout), Kodus retries once on Fallback. You pay only for the provider that actually processed the review.
  </Accordion>

  <Accordion title="Should I use the same provider for Main and Fallback?">
    No. Different providers protect against provider-specific outages. A common pairing: Anthropic Main + Google Fallback, or GLM Coding Plan Main + Anthropic Fallback for spike coverage.
  </Accordion>

  <Accordion title="Do you store our API keys securely?">
    Yes. Keys are encrypted at rest and in transit and never logged in plain text. The BYOK status endpoint never returns the raw key.
  </Accordion>

  <Accordion title="Can I use a self-hosted LLM (e.g. Ollama, vLLM)?">
    Yes — via the **OpenAI Compatible** provider in the manual wizard. Enter your endpoint's base URL, the model ID it exposes, and a placeholder API key (most self-hosted runtimes ignore the key header but still require one).
  </Accordion>
</AccordionGroup>


# AI Agents
Source: https://docs.kodus.io/how_to_use/en/cli/ai_agents

Integrate the Kodus CLI with AI coding agents for autonomous review-fix loops.

The CLI ships with a minimal, structured output mode (`--prompt-only`) designed for AI coding agents to parse and act on. Combined with a team key, it enables autonomous review-fix loops — the agent reviews, applies fixes, re-reviews, and commits, all without human input in the critical path.

## Supported agents

* **Claude Code** — native skill via the skill installer.
* **Cursor** — native skill.
* **Codex** — native skill, with Decision Memory via `notify` hooks.
* **Windsurf** — via `--prompt-only` output.

For any other agent that can run shell commands and parse structured text, `kodus review --prompt-only` works out of the box.

## Quickest setup

Install the CLI plus all agent skills in one shot:

```bash theme={null}
curl -fsSL https://review-skill.com/install | bash -s -- --team-key kodus_xxxxx
```

This:

1. Installs the `@kodus/cli` binary globally.
2. Configures the team key in `~/.kodus/config.json`.
3. Deploys Kodus skills to every detected agent (Claude Code, Cursor, Codex, Windsurf).

No individual logins. No interactive prompts. Ready for agent loops immediately.

## The Review-Fix Loop

<Steps>
  <Step title="Agent runs review">
    ```bash theme={null}
    kodus review --prompt-only
    ```

    The CLI returns structured issues with file paths, line numbers, severities, and suggested fixes — in a compact text format designed for an LLM to consume.
  </Step>

  <Step title="Agent applies fixes">
    The agent reads the output, decides which fixes to apply (or accepts all via `--fix`), and edits files accordingly.
  </Step>

  <Step title="Agent re-runs review">
    ```bash theme={null}
    kodus review --prompt-only --fail-on error
    ```

    With `--fail-on error`, the loop exits non-zero while there are still error-or-worse issues. The agent keeps looping; when the review comes back clean, the process exits 0 and the agent moves on.
  </Step>

  <Step title="Agent commits and pushes">
    Once the review is clean, the agent commits and pushes. Optionally, install the pre-push hook (`kodus hook install`) for an additional safety net on manual pushes.
  </Step>
</Steps>

## Team key authentication for agents

Team keys are strongly recommended for agents — no individual signup, no interactive login, easy rotation, per-device tracking.

```bash theme={null}
export KODUS_TEAM_KEY=kodus_xxxxx
kodus review --prompt-only
```

Generate a key at <a href="https://app.kodus.io/organization/cli-keys">app.kodus.io/organization/cli-keys</a> and distribute the install command shown there to your team.

<Warning>Save the key when it's shown — it won't be displayed again.</Warning>

## Output flags that matter

| Flag             | Use                                                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--prompt-only`  | Compact structured output for parsing. Use in the review loop.                                                          |
| `--agent`        | Enforces deterministic machine-readable output on any command.                                                          |
| `--format json`  | Full JSON payload. Pair with `--agent` for strict parsers.                                                              |
| `--fail-on`      | Exit code gate. The loop keeps going while this is non-zero.                                                            |
| `--fields <csv>` | Narrow the JSON/agent payload (e.g. `summary,issues.file,issues.severity`). Useful to keep agent context windows small. |

## Combining with Decision Memory

Pair agent loops with [Decision Memory](decision_memory) to capture the reasoning behind every agent turn as structured files in your repo. The loop handles *what* changed; memory captures *why*.

```bash theme={null}
kodus decisions enable
# Now every agent turn writes a decision file under .kody/
```

## Example: Claude Code loop with business validation

```bash theme={null}
# In a Claude Code session, the agent can run:
kodus review --prompt-only --fail-on error    # general review
kodus pr business-validation --task-id KC-1441 --dry-run   # check against task
kodus review --prompt-only --fix               # auto-apply fixable issues
git commit -am "fix: KC-1441 address review findings"
```

With the skill installer, Claude Code's Kodus skill knows when to invoke each of these — no prompt engineering required on your side.

## Related

<CardGroup>
  <Card title="Decision Memory" icon="brain" href="decision_memory">
    Persist agent decisions as structured files in your repo.
  </Card>

  <Card title="Concepts" icon="book-open" href="concepts">
    Review modes, diff modes, and agent output flags.
  </Card>

  <Card title="Command Reference" icon="book" href="commands">
    Full flag listing.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="troubleshooting">
    Agent loop issues, hook problems, timeouts.
  </Card>
</CardGroup>


# Command Reference
Source: https://docs.kodus.io/how_to_use/en/cli/commands

Complete reference for all Kodus CLI commands, flags, and options.

## Global Flags

These flags are available on all commands:

| Flag              | Short | Default    | Description                                       |
| ----------------- | ----- | ---------- | ------------------------------------------------- |
| `--format <fmt>`  | `-f`  | `terminal` | Output format: `terminal`, `json`, `markdown`     |
| `--output <file>` | `-o`  | —          | Save output to a file                             |
| `--verbose`       | `-v`  | `false`    | Verbose output                                    |
| `--quiet`         | `-q`  | `false`    | Quiet mode (errors only)                          |
| `--agent`         | —     | `false`    | Agent mode: deterministic machine-readable output |

***

## `kodus review`

Analyzes modified files for code quality issues, bugs, security vulnerabilities, and style violations.

### Usage

```bash theme={null}
kodus review                          # Review working tree changes (interactive)
kodus review [files...]               # Review specific files
kodus review --staged                 # Review staged files only
kodus review --branch main            # Compare against a branch
kodus review --commit abc123          # Analyze a specific commit
kodus review --fix                    # Auto-apply all fixable issues
kodus review --prompt-only            # Output optimized for AI agents
```

### Flags

| Flag                   | Short | Description                                                          |
| ---------------------- | ----- | -------------------------------------------------------------------- |
| `--staged`             | `-s`  | Analyze only staged files                                            |
| `--commit <sha>`       | `-c`  | Analyze diff from a specific commit                                  |
| `--branch <name>`      | `-b`  | Compare current branch against specified branch                      |
| `--rules-only`         | —     | Review using only configured rules (no general suggestions)          |
| `--fast`               | —     | Fast mode: quicker analysis with lighter checks                      |
| `--interactive`        | `-i`  | Interactive mode: navigate and apply fixes                           |
| `--fix`                | —     | Automatically apply all fixable issues                               |
| `--prompt-only`        | —     | Output optimized for AI agents                                       |
| `--fail-on <severity>` | —     | Exit with code 1 if issues meet or exceed severity                   |
| `--context <file>`     | —     | Custom context file to include in review                             |
| `--fields <csv>`       | —     | Select response fields (JSON/agent mode), e.g. `summary,issues.file` |

### Review Modes

<Tabs>
  <Tab title="Interactive (Default)">
    Navigate files with issue counts, preview suggested fixes, and apply them one by one.

    ```bash theme={null}
    kodus review
    ```
  </Tab>

  <Tab title="Auto-fix">
    Applies all fixable issues at once with a confirmation prompt.

    ```bash theme={null}
    kodus review --fix
    ```
  </Tab>

  <Tab title="AI Agent">
    Minimal, structured output designed for Claude Code, Cursor, or Windsurf. Enables autonomous review-fix loops.

    ```bash theme={null}
    kodus review --prompt-only
    ```
  </Tab>
</Tabs>

***

## `kodus pr suggestions`

Fetch AI-powered suggestions for open pull requests.

### Usage

```bash theme={null}
kodus pr suggestions --pr-url https://github.com/org/repo/pull/42
kodus pr suggestions --pr-number 42 --repo-id <id>
kodus pr suggestions --pr-number 42 --repo-id <id> --severity error,warning
kodus pr suggestions --pr-number 42 --repo-id <id> --format json
```

### Flags

| Flag                   | Description                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| `--pr-url <url>`       | Pull request URL                                                     |
| `--pr-number <number>` | Pull request number (requires `--repo-id`)                           |
| `--repo-id <id>`       | Repository ID for the pull request                                   |
| `--severity <list>`    | Comma-separated severities to include                                |
| `--category <list>`    | Comma-separated categories to include                                |
| `--fields <csv>`       | Select response fields (JSON/agent mode), e.g. `summary,issues.file` |

***

## `kodus pr business-validation`

Validate a local diff against the business rules/acceptance criteria of a task. Useful before merging to confirm the implementation matches the task intent.

### Usage

```bash theme={null}
kodus pr business-validation --task-url https://linear.app/team/issue/KC-1441
kodus pr business-validation --task-id KC-1441 --staged
kodus pr business-validation --task-id KC-1441 --branch main
kodus pr business-validation --task-id KC-1441 --commit abc123
kodus pr business-validation --task-id KC-1441 --dry-run
```

### Flags

| Flag               | Short | Description                                     |
| ------------------ | ----- | ----------------------------------------------- |
| `--task-url <url>` | —     | Task URL to append to the validation command    |
| `--task-id <id>`   | —     | Task ID or issue key (e.g. `KC-1441`) to append |
| `--staged`         | `-s`  | Use only staged changes                         |
| `--commit <sha>`   | `-c`  | Use diff from a specific commit                 |
| `--branch <name>`  | `-b`  | Compare current branch against a base branch    |
| `--dry-run`        | —     | Print payload without executing the API call    |

***

## `kodus auth`

Manage authentication with the Kodus API.

### `auth login`

```bash theme={null}
kodus auth login                              # Interactive login
kodus auth login -e user@mail.com -p password # Non-interactive
```

| Flag                    | Short | Description      |
| ----------------------- | ----- | ---------------- |
| `--email <email>`       | `-e`  | Account email    |
| `--password <password>` | `-p`  | Account password |

### `auth logout`

```bash theme={null}
kodus auth logout
```

Removes local authentication (login and team key).

### `auth status`

```bash theme={null}
kodus auth status
```

Shows authentication mode, email, token validity, organizations, trial status, and usage limits.

### `auth team-key`

```bash theme={null}
kodus auth team-key --key kodus_xxxxx
```

Authenticate using a shared team API key. Can also be set via the `KODUS_TEAM_KEY` environment variable.

### `auth team-status`

```bash theme={null}
kodus auth team-status
```

Shows team authentication details (organization and team name).

### `auth token`

```bash theme={null}
kodus auth token
```

Generates a CI/CD token for use in automated pipelines. Use with the `KODUS_TOKEN` environment variable.

***

## `kodus hook`

Manage pre-push Git hooks for automatic code review before pushing.

### `hook install`

```bash theme={null}
kodus hook install                    # Default: fail-on critical, fast mode enabled
kodus hook install --fail-on error    # Block pushes on error severity
kodus hook install --no-fast          # Disable fast mode
kodus hook install --force            # Overwrite existing hook
```

| Flag                   | Default    | Description                               |
| ---------------------- | ---------- | ----------------------------------------- |
| `--fail-on <severity>` | `critical` | Minimum severity to block push            |
| `--fast` / `--no-fast` | `true`     | Enable/disable fast mode                  |
| `--force`              | —          | Overwrite existing hook without prompting |

### `hook uninstall`

```bash theme={null}
kodus hook uninstall
```

Removes the pre-push hook installed by Kodus.

### `hook status`

```bash theme={null}
kodus hook status
```

Shows hook status, fail-on severity, fast mode setting, and path.

### Skipping the Hook

```bash theme={null}
KODUS_SKIP_HOOK=1 git push
```

***

## `kodus decisions`

Capture and persist AI agent decisions into your repository for future reference. Decisions are stored as structured markdown in `.kody/`.

### `decisions enable`

```bash theme={null}
kodus decisions enable                                    # All agents
kodus decisions enable --agents claude,cursor            # Specific agents
kodus decisions enable --agents codex --codex-config ~/.codex/config.toml
kodus decisions enable --force                           # Overwrite existing config
```

| Flag                    | Default                | Description                      |
| ----------------------- | ---------------------- | -------------------------------- |
| `--agents <agents>`     | `claude,cursor,codex`  | Comma-separated agent list       |
| `--codex-config <path>` | `~/.codex/config.toml` | Path to Codex config             |
| `--force`               | —                      | Overwrite existing `modules.yml` |

### `decisions disable`

```bash theme={null}
kodus decisions disable
```

Removes all decision hooks. Preserved data in `.kody/` is not deleted.

### `decisions status`

```bash theme={null}
kodus decisions status
```

Shows PR memory, sessions, last SHA, agent, and module config.

### `decisions show`

```bash theme={null}
kodus decisions show                  # Current branch PR memory
kodus decisions show auth             # Module decisions for 'auth'
kodus decisions show feat/new-api     # PR decisions for a specific branch
```

### `decisions promote`

```bash theme={null}
kodus decisions promote                                   # Current branch, all modules
kodus decisions promote --branch feat/auth                # Specific branch
kodus decisions promote --branch feat/auth --modules auth,users
```

| Flag              | Description                                       |
| ----------------- | ------------------------------------------------- |
| `--branch <name>` | Branch name (default: current branch)             |
| `--modules <ids>` | Comma-separated module IDs (default: all matched) |

Promotes PR-level decisions to long-term module memory.

***

## `kodus config centralized`

Manage centralized configuration from the CLI.

### Usage

```bash theme={null}
kodus config centralized status
kodus config centralized init [owner/repo] --sync-option <pr|manual>
kodus config centralized sync
kodus config centralized disable
kodus config centralized download --out ./centralized-config.zip
```

### Subcommands

| Subcommand              | Description                                                                   |
| ----------------------- | ----------------------------------------------------------------------------- |
| `status`                | Show whether centralized config is enabled and the selected source repository |
| `init [repository]`     | Enable centralized config for a selected repository                           |
| `sync`                  | Run centralized config sync on demand                                         |
| `disable`               | Disable centralized config and clear selected repository                      |
| `download --out <path>` | Download centralized config ZIP bundle                                        |

### Flags

| Flag                           | Applies To                  | Description                       |
| ------------------------------ | --------------------------- | --------------------------------- |
| `--sync-option <pr \| manual>` | `init`                      | Sync strategy. Default is `pr`    |
| `--out <path>`                 | `download`                  | Required output path for ZIP file |
| `--json`                       | all centralized subcommands | Output structured JSON            |

For a complete walkthrough, see: [/how\_to\_use/en/code\_review/configs/centralized\_config#cli-dedicated-section](/how_to_use/en/code_review/configs/centralized_config#cli-dedicated-section)

***

## `kodus config repo`

Inspect and update repository settings stored in Kodus. Team-key auth is required. Use `.` to target the current repository.

<Note>`kodus config repo` and `kodus config remote` are aliases for the same command group.</Note>

### Usage

```bash theme={null}
kodus config repo add                                   # Add current repo to Kodus
kodus config repo add owner/repo                        # Add a specific repo
kodus config repo list                                  # List configured repos
kodus config repo show                                  # Show current repo settings
kodus config repo setup                                 # Guided setup wizard
kodus config repo set . reviewEnabled true              # Set a setting directly
kodus config repo open                                  # Open the Kodus dashboard
kodus config repo add-ignore-file . "**/*.generated.ts"
kodus config repo add-base-branch . "release/*"
kodus config repo add-ignore-title . "^WIP:"
```

### Subcommands

| Subcommand                                      | Description                                                                      |
| ----------------------------------------------- | -------------------------------------------------------------------------------- |
| `add [repository]`                              | Add a repository to Kodus (shortcut: `kodus config -r [repository]`)             |
| `list`                                          | List repositories configured in Kodus                                            |
| `show [repository]`                             | Show repository settings                                                         |
| `setup [repository]`                            | Run a guided repository setup wizard                                             |
| `set [repository] <key> <value>`                | Set a repository setting directly                                                |
| `open [repository]`                             | Open the Kodus dashboard for advanced settings                                   |
| `add-pattern [repository] <field> <pattern>`    | Add a pattern to a list field (`ignore-files`, `base-branches`, `ignore-titles`) |
| `remove-pattern [repository] <field> <pattern>` | Remove a pattern from a list field                                               |
| `add-ignore-file [repository] <pattern>`        | Shortcut: add a pattern to ignored file patterns                                 |
| `remove-ignore-file [repository] <pattern>`     | Shortcut: remove an ignored file pattern                                         |
| `add-base-branch [repository] <pattern>`        | Shortcut: add a base branch pattern                                              |
| `remove-base-branch [repository] <pattern>`     | Shortcut: remove a base branch pattern                                           |
| `add-ignore-title [repository] <pattern>`       | Shortcut: add an ignored title pattern                                           |
| `remove-ignore-title [repository] <pattern>`    | Shortcut: remove an ignored title pattern                                        |

### Flags

| Flag          | Applies To | Description                    |
| ------------- | ---------- | ------------------------------ |
| `--no-prompt` | `add`      | Skip the post-add setup prompt |

***

## `kodus rules`

Create, update, and view Kody Rules — structured rules that Kodus applies during review.

### Usage

```bash theme={null}
kodus rules view                                         # View all rules for your team
kodus rules view --repo-id <id>                          # Filter by repository
kodus rules view --uuid <rule-uuid>                      # Fetch a single rule
kodus rules create --title "No console.log" --rule "Avoid leaving console.log in committed code" --severity high
kodus rules update --uuid <rule-uuid> --severity critical
```

### Subcommands

| Subcommand | Description             |
| ---------- | ----------------------- |
| `create`   | Create a new Kody Rule  |
| `update`   | Update an existing rule |
| `view`     | View Kody Rules         |

### `rules create` Flags

| Flag                    | Default  | Description                                       |
| ----------------------- | -------- | ------------------------------------------------- |
| `--title <title>`       | —        | Rule title                                        |
| `--rule <rule>`         | —        | Rule content/description                          |
| `--repo-id <id>`        | `global` | Repository ID (or `global` to apply to all repos) |
| `--severity <severity>` | `medium` | `low`, `medium`, `high`, `critical`               |
| `--scope <scope>`       | `file`   | `pull request` or `file`                          |
| `--path <glob>`         | `**/*`   | Glob pattern for file targeting                   |
| `--json`                | `false`  | Output created rule as JSON                       |

### `rules update` Flags

| Flag                    | Description                    |
| ----------------------- | ------------------------------ |
| `--uuid <uuid>`         | Rule UUID to update (required) |
| `--repo-id <id>`        | Updated repository ID          |
| `--title <title>`       | Updated title                  |
| `--rule <rule>`         | Updated content/description    |
| `--severity <severity>` | Updated severity               |
| `--scope <scope>`       | Updated scope                  |
| `--path <glob>`         | Updated glob pattern           |
| `--json`                | Output updated rule as JSON    |

### `rules view` Flags

| Flag             | Description                   |
| ---------------- | ----------------------------- |
| `--uuid <uuid>`  | Fetch a single rule by UUID   |
| `--repo-id <id>` | Filter rules by repository ID |
| `--json`         | Output rules as JSON          |

***

## `kodus skills`

Inspect and install the agent skills bundled with the CLI (Claude Code, Cursor, Codex).

### Usage

```bash theme={null}
kodus skills list                                        # List bundled skills
kodus skills install                                     # Install into detected agent roots
kodus skills install --dry-run                           # Preview changes
kodus skills resync                                      # Re-sync bundled skills
kodus skills uninstall                                   # Remove bundled skills
```

### Subcommands

| Subcommand  | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| `list`      | List bundled skills available in this CLI package                         |
| `sync`      | Sync bundled skills to detected local agent directories                   |
| `resync`    | Re-sync bundled skills to detected local agent directories                |
| `install`   | Install bundled skills into detected agent roots (creates dirs as needed) |
| `uninstall` | Uninstall bundled managed skills from detected agent directories          |

### Flags

| Flag        | Applies To                               | Description                                |
| ----------- | ---------------------------------------- | ------------------------------------------ |
| `--dry-run` | `install`, `sync`, `resync`, `uninstall` | Show planned changes without writing files |

<Tip>For full multi-agent bootstrap, prefer the platform installer (`curl -fsSL https://review-skill.com/install | bash`). `kodus skills` covers local re-sync and cleanup.</Tip>

***

## `kodus status`

Show a consolidated Kodus status: auth mode, organization, repository, hook, decisions, bundled skills, and CLI version.

```bash theme={null}
kodus status
```

Useful as a first diagnostic when something misbehaves or when onboarding a new machine.

***

## `kodus update`

Update the Kodus CLI to the latest version from npm.

```bash theme={null}
kodus update
```

Resolves the correct global install command for your package manager (`npm`, `yarn`, `pnpm`, `bun`) and runs it. If an installer script was used, the CLI points you to the re-run command instead.

***

## `kodus subscribe`

Opens the Kodus pricing/upgrade page in your browser.

```bash theme={null}
kodus subscribe
```

***

## Severity Levels

Issues are categorized by severity, from most to least critical:

| Level      | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| `critical` | Major security or stability issues requiring immediate attention |
| `error`    | Significant bugs or problems                                     |
| `warning`  | Potential issues worth addressing                                |
| `info`     | Suggestions and best practices                                   |

## Issue Categories

| Category                 | Description                            |
| ------------------------ | -------------------------------------- |
| `security_vulnerability` | Security-related issues                |
| `bug`                    | Potential bugs                         |
| `performance`            | Performance optimization opportunities |
| `code_quality`           | Code quality improvements              |
| `best_practices`         | Best practice violations               |
| `complexity`             | Code complexity issues                 |
| `maintainability`        | Maintainability concerns               |
| `style`                  | Code style issues                      |


# Concepts
Source: https://docs.kodus.io/how_to_use/en/cli/concepts

Mental models to get the most out of the Kodus CLI.

A short tour of the ideas that show up everywhere in the CLI. Read this once and the rest of the docs will make more sense.

## Diff Modes

Every review needs to answer one question: *what changed?* The CLI supports four diff modes, each with a different source of truth.

| Mode                           | Source of diff                                | Inlines files? | When to use                                   |
| ------------------------------ | --------------------------------------------- | -------------- | --------------------------------------------- |
| **Working tree** (default)     | Uncommitted changes in your working directory | Yes            | Mid-development, before staging anything.     |
| **Staged** (`--staged`)        | `git diff --cached`                           | Yes            | About to commit — same scope as `git commit`. |
| **Branch** (`--branch <base>`) | `base..HEAD` committed diff                   | No             | Pre-merge review of the whole branch.         |
| **Commit** (`--commit <sha>`)  | The diff introduced by a single commit        | No             | Audit one commit, cherry-pick review.         |

<Tip>
  **Why does inlining matter?** Working-tree and staged reviews send file contents alongside the diff because the backend can't see your uncommitted work. Branch and commit modes skip inlining — the backend clones the same commit directly. That's why branch/commit reviews work on huge diffs where working-tree reviews would exceed request size limits.
</Tip>

## Review Modes

Three output styles, same underlying review.

* **Interactive** (default) — a TUI that lists files, expands issues, and applies fixes one at a time with a preview. The natural way to work in a terminal.
* **Auto-fix** (`--fix`) — applies every fixable issue at once, with a single confirmation. Use when you trust the rules and want to batch-apply.
* **Prompt-only** (`--prompt-only`) — minimal, structured text designed for AI agents to parse and act on. Pair with `--fail-on` in an agent loop so the loop exits cleanly when the review is clean.

You can also use `--format json` or `--format markdown` with any command for non-interactive consumers (CI, scripts, webhooks).

## Authentication Modes

Pick one per machine. The CLI auto-detects what's available.

* **Trial** — no auth. 5 reviews per day. Good for "try it once".
* **Personal login** (`kodus auth login`) — an individual account. Tokens refresh automatically.
* **Team key** (`kodus auth team-key --key kodus_xxxxx`) — one shared key for a team, generated in the dashboard. Recommended for AI agents and anywhere you don't want interactive logins.
* **CI/CD token** (`kodus auth token`) — a long-lived token for pipelines. Generated from a logged-in machine, used via `KODUS_TOKEN`.

See [Getting Started](getting_started) for the full decision tree.

## Kody Rules

A **Kody Rule** is a structured rule the Kodus reviewer applies during every review, scoped to a repository or global to your team.

```
Rule
├── title          "No console.log in production code"
├── rule           "Avoid leaving console.log in committed code"
├── severity       low | medium | high | critical
├── scope          file | pull request
├── path           **/*.ts       (glob for file targeting)
└── repo-id        <uuid> | global
```

Rules layer on top of the general Kodus review — the AI uses them as additional criteria, not replacements.

Manage rules from the dashboard or from the CLI with `kodus rules create|update|view`. The CLI is useful when you want rules in version control (generate them from a script, check into a repo, re-apply on provisioning).

## Repository Settings

Every repository in Kodus has settings that govern how reviews behave: ignored files, base branch patterns, title filters, feature toggles. These live in the Kodus backend and are mirrored anywhere the repo is reviewed (web PRs, CLI reviews, agent loops).

From the CLI:

```bash theme={null}
kodus config repo list                 # See your configured repos
kodus config repo show                 # See settings for the current repo
kodus config repo setup                # Guided wizard
kodus config repo set . reviewEnabled true
kodus config repo add-ignore-file . "**/*.generated.ts"
kodus config repo open                 # Jump to the web dashboard
```

`kodus config repo` and `kodus config remote` are aliases for the same command group.

## Centralized Config

Normally, each repository's settings live in Kodus. **Centralized Config** lets a team store those settings in a single source-of-truth git repository — every change becomes a pull request against that repo, giving you review and version history on your review configuration itself.

Enable, sync, or inspect state:

```bash theme={null}
kodus config centralized status
kodus config centralized init owner/config-repo --sync-option pr
kodus config centralized sync
kodus config centralized disable
```

Use Centralized Config when your team wants auditable, versioned control over review settings. Keep the default (per-repo settings in Kodus) when that ceremony is overkill.

## Decision Memory

Decision Memory is Kodus's way of persisting the *reasoning* behind AI agent work — not just the diff, but the "why".

When enabled, Kodus installs hooks in Claude Code, Cursor, or Codex that fire on every turn-complete event and capture structured decisions to:

```
.kody/
├── pr/by-sha/<head-sha>.md    # PR-level decisions (versioned with code)
├── memory/<module-id>.md      # Module-level decisions (long-term)
└── modules.yml                # Module configuration
```

PR-level memory lives on the branch. When a PR merges, promote its decisions to module-level memory (`kodus decisions promote`) so future work on that module starts with the accumulated context.

Full walk-through: [Decision Memory](decision_memory).

## Business Validation

Where `kodus review` asks "is this code good?", `kodus pr business-validation` asks "does this diff actually do what the task said to do?". You point it at a Linear/Jira/URL-based task and a diff source (working tree, staged, branch, commit) and it checks the implementation against the task's acceptance criteria.

```bash theme={null}
kodus pr business-validation --task-id KC-1441 --branch main
kodus pr business-validation --task-url https://linear.app/… --staged
```

Pair with a pre-merge check to catch "code works, but it's not what was asked for" before human review.

## AI Agent Output (`--prompt-only` and `--agent`)

Two related flags, different jobs.

* **`--prompt-only`** — output is optimized for an AI agent to parse and act on. Only works on commands that produce review-style output (`review`, `pr suggestions`).
* **`--agent`** — global flag that enforces **deterministic, machine-readable** output on any command. Use when a script or agent parses CLI output; combine with `--format json` for strictness.

Most agent integrations just need `--prompt-only`. Reach for `--agent` when you're orchestrating the CLI from a harness or a tool-calling loop that has strict format expectations.

## Next steps

<CardGroup>
  <Card title="Command Reference" icon="book" href="commands">
    Full command + flag listing.
  </Card>

  <Card title="AI Agents" icon="robot" href="ai_agents">
    Build review-fix loops with coding agents.
  </Card>

  <Card title="Decision Memory" icon="brain" href="decision_memory">
    Capture and promote agent decisions across branches.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="troubleshooting">
    Common errors and exit codes.
  </Card>
</CardGroup>


# Decision Memory
Source: https://docs.kodus.io/how_to_use/en/cli/decision_memory

Capture and persist AI agent decisions as structured files in your repository.

Decision Memory is Kodus's way of remembering **why** an AI agent made the changes it did — not just the diff, but the reasoning, the constraints, the alternatives considered. Decisions are captured automatically on every agent turn and stored as structured markdown files versioned alongside your code.

## Why it exists

Code review catches what's wrong with a diff. It doesn't tell you why the author went with approach A over approach B, or what constraint forced the ugly workaround on line 42. For AI agents, that context vanishes between sessions — each run starts from scratch.

Decision Memory fixes this by:

* **Capturing reasoning automatically** at every turn-complete event.
* **Storing it in the repo** so the context travels with the code, not with a session.
* **Scoping it by PR and by module** so you get both branch-level context and long-term module knowledge.

## How it works

When enabled, Kodus installs hooks into your AI agent's turn-complete events. Each turn, the agent's decisions are captured into:

```
.kody/
├── pr/by-sha/<head-sha>.md    # PR-level decisions (versioned with code)
├── memory/<module-id>.md      # Module-level decisions (long-term)
└── modules.yml                # Module configuration
```

* **PR memory** lives on the branch. It's scoped to the current head SHA — as the branch evolves, new files are created for each meaningful state.
* **Module memory** is long-term. It accumulates decisions per module over time.
* **`modules.yml`** tells Kodus how to map paths to modules (e.g., `src/auth/**` → `auth` module).

## Supported agents

* **Claude Code** — via settings hook on stop/agent-turn-complete.
* **Cursor** — via workspace rules.
* **Codex** — via `notify` entry in `~/.codex/config.toml`.

## Setup

Enable for all detected agents:

```bash theme={null}
kodus decisions enable
```

Or target specific agents:

```bash theme={null}
kodus decisions enable --agents claude,cursor
kodus decisions enable --agents codex --codex-config ~/.codex/config.toml
```

If a previous config is in place, force a reinstall:

```bash theme={null}
kodus decisions enable --force
```

Check what's wired up:

```bash theme={null}
kodus decisions status
```

## Workflow

<Steps>
  <Step title="Enable hooks">
    ```bash theme={null}
    kodus decisions enable
    ```

    This installs agent-specific integration files and adds `.kody/` to git (creating a `modules.yml` if it doesn't exist).
  </Step>

  <Step title="Work normally">
    As you (or your agent) work, each turn-complete event captures a decision to `.kody/pr/by-sha/<sha>.md`. Commit these files along with your code changes — the reasoning is now in version control.
  </Step>

  <Step title="Review captured decisions">
    ```bash theme={null}
    kodus decisions show                    # current branch PR memory
    kodus decisions show feat/auth          # decisions for a specific branch
    kodus decisions show auth               # module decisions for 'auth'
    ```
  </Step>

  <Step title="Promote to long-term memory">
    When a PR merges, promote its PR-level decisions to module-level memory so they persist beyond the branch:

    ```bash theme={null}
    kodus decisions promote                               # current branch, all matched modules
    kodus decisions promote --branch feat/auth            # a specific branch
    kodus decisions promote --branch feat/auth --modules auth,users
    ```
  </Step>
</Steps>

## What gets captured

Each decision file is structured markdown:

* **Summary** — what the agent intended to do.
* **Context** — constraints, prior decisions, referenced files.
* **Alternatives considered** — approaches the agent rejected and why.
* **Outcome** — what was actually changed.

The exact shape depends on the agent's turn event; the CLI normalizes it into a consistent frontmatter + body format.

## Disabling

Remove all hooks and integration files:

```bash theme={null}
kodus decisions disable
```

This does not delete data in `.kody/` — your history stays intact. Delete the directory manually if you want a clean slate.

## Context files the CLI reads

In addition to `.kody/`, the CLI picks up project context from these files when running reviews:

| File             | Description                                 |
| ---------------- | ------------------------------------------- |
| `.kodus.md`      | Kodus-specific configuration and guidelines |
| `claude.md`      | Claude-specific guidelines                  |
| `.cursor/rules/` | Cursor IDE rules directory                  |

These are orthogonal to Decision Memory — they describe *standing* context, while Decision Memory captures *turn-by-turn* reasoning.

## Related

<CardGroup>
  <Card title="AI Agents" icon="robot" href="ai_agents">
    Review-fix loops with Claude Code, Cursor, Codex, and Windsurf.
  </Card>

  <Card title="Concepts" icon="book-open" href="concepts">
    Kody Rules, centralized config, and diff modes.
  </Card>

  <Card title="Command Reference" icon="book" href="commands#kodus-decisions">
    Full `kodus decisions` flag listing.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="troubleshooting">
    Decision hooks not capturing? See the dedicated accordion.
  </Card>
</CardGroup>


# Getting Started
Source: https://docs.kodus.io/how_to_use/en/cli/getting_started

Install the Kodus CLI, authenticate, and run your first review.

This guide gets you from zero to a reviewed diff in under five minutes.

<Steps>
  <Step title="Install">
    <Tabs>
      <Tab title="Skill Installer (Recommended)">
        Installs the CLI and deploys Kodus skills to all detected AI agents (Claude Code, Cursor, Codex, Windsurf):

        ```bash theme={null}
        curl -fsSL https://review-skill.com/install | bash
        ```
      </Tab>

      <Tab title="npm">
        ```bash theme={null}
        npm install -g @kodus/cli
        ```
      </Tab>

      <Tab title="npx (No Install)">
        ```bash theme={null}
        npx @kodus/cli review
        ```
      </Tab>

      <Tab title="curl">
        ```bash theme={null}
        curl -fsSL https://raw.githubusercontent.com/kodustech/cli/main/install.sh | bash
        ```
      </Tab>
    </Tabs>

    <Note>Requires Node.js >= 20.0.0.</Note>

    Verify the install:

    ```bash theme={null}
    kodus --version
    kodus status
    ```
  </Step>

  <Step title="Authenticate">
    Pick the path that matches your situation. You can also skip auth and run `kodus review` directly — it works in trial mode with daily limits.

    <Tabs>
      <Tab title="Solo developer">
        Sign in with a personal account:

        ```bash theme={null}
        kodus auth login
        ```

        Tokens are stored in `~/.kodus/credentials.json` and auto-refreshed.
      </Tab>

      <Tab title="Team (shared key)">
        Generate a team key at <a href="https://app.kodus.io/organization/cli-keys">app.kodus.io/organization/cli-keys</a> and apply it:

        ```bash theme={null}
        kodus auth team-key --key kodus_xxxxx
        ```

        Or distribute the bootstrap command to your team — it installs the CLI and configures the key in one shot:

        ```bash theme={null}
        curl -fsSL https://review-skill.com/install | bash -s -- --team-key kodus_xxxxx
        ```

        <Warning>Save the key when it's shown — it won't be displayed again.</Warning>
      </Tab>

      <Tab title="AI agent">
        For AI coding agents (Claude Code, Cursor, Codex), team keys are the recommended path — no individual login, no interactive prompts. Set the key once:

        ```bash theme={null}
        export KODUS_TEAM_KEY=kodus_xxxxx
        ```

        Add it to your shell profile so the agent picks it up on every run.
      </Tab>

      <Tab title="CI/CD">
        From a logged-in machine, generate a long-lived token:

        ```bash theme={null}
        kodus auth token
        ```

        In your pipeline, set:

        ```bash theme={null}
        export KODUS_TOKEN=<generated-token>
        ```

        See [Self-Hosted Setup](self_hosted) for full CI examples.
      </Tab>
    </Tabs>

    <Info>
      **Self-hosting Kodus?** Point the CLI to your API before authenticating:

      ```bash theme={null}
      export KODUS_API_URL=https://kodus-api.yourcompany.com
      ```

      HTTPS is required except for `localhost`.
    </Info>

    Confirm the auth state:

    ```bash theme={null}
    kodus auth status
    ```
  </Step>

  <Step title="Run your first review">
    Inside any git repository with uncommitted changes:

    ```bash theme={null}
    kodus review
    ```

    The CLI analyzes your working tree diff, prints a summary, and (in interactive mode) lets you browse file-by-file, preview suggested fixes, and apply them.

    Common variations:

    ```bash theme={null}
    kodus review --staged             # Only staged files
    kodus review --branch main        # Compare current branch against main
    kodus review --commit abc123      # Analyze a single commit
    kodus review --fix                # Auto-apply every fixable issue
    kodus review --prompt-only        # Compact output for AI agents
    kodus review --fail-on error      # Exit non-zero on error-or-worse (CI-friendly)
    ```

    <Tip>
      Working-tree reviews (default) and `--staged` inline file contents so the backend sees your uncommitted changes. `--branch` and `--commit` modes skip inlining since the backend can fetch those commits itself — this is why those modes work well on huge branches.
    </Tip>
  </Step>

  <Step title="Choose what's next">
    Depending on your goal:

    <CardGroup>
      <Card title="Automate on every push" icon="shield-check" href="commands#kodus-hook">
        Install the pre-push hook with `kodus hook install`.
      </Card>

      <Card title="Run reviews in CI" icon="infinity" href="self_hosted#ci-cd-integration">
        GitHub Actions, GitLab CI, and generic pipeline examples.
      </Card>

      <Card title="Plug into an AI agent" icon="robot" href="ai_agents">
        Feed `--prompt-only` into Claude Code, Cursor, or Codex for autonomous fix loops.
      </Card>

      <Card title="Configure the repo" icon="sliders" href="commands#kodus-config-repo">
        Manage ignored files, base branches, and review settings from the CLI.
      </Card>
    </CardGroup>
  </Step>
</Steps>

## Environment Variables

These env vars configure the CLI across all commands.

| Variable                    | Description                                                  |
| --------------------------- | ------------------------------------------------------------ |
| `KODUS_API_URL`             | API endpoint (default: `https://api.kodus.io`)               |
| `KODUS_TEAM_KEY`            | Team key for shared access and AI agents                     |
| `KODUS_TOKEN`               | CI/CD token generated via `kodus auth token`                 |
| `KODUS_VERBOSE`             | Set to `true` for verbose output                             |
| `KODUS_SKIP_HOOK`           | Set to `1` to skip the pre-push hook for a single `git push` |
| `KODUS_REQUEST_TIMEOUT_MIN` | Per-request timeout in minutes (default: `60`)               |
| `CF_ACCESS_CLIENT_ID`       | Cloudflare Access client ID (APIs behind Zero Trust)         |
| `CF_ACCESS_CLIENT_SECRET`   | Cloudflare Access client secret                              |

For self-hosted setups, tokens, and Cloudflare Access, see [Self-Hosted Setup](self_hosted).

## Troubleshooting

Ran into an error? Check the [Troubleshooting guide](troubleshooting) for common symptoms and fixes.


# Kodus CLI
Source: https://docs.kodus.io/how_to_use/en/cli/introduction

AI-powered code review, business validation, and agent workflows — from your terminal.

Kodus CLI reviews your code changes directly from the terminal — catching bugs, security issues, and style violations before they reach a pull request. It's the same Kodus engine that runs on your PRs, but pointed at your working tree, staged diff, branch, or commit.

## Who it's for

* **Solo developers** running a pre-commit check before pushing.
* **Teams** wanting a shared review ruleset across every clone, IDE, and CI job — without each developer signing in.
* **AI coding agents** (Claude Code, Cursor, Codex, Windsurf) running review-fix loops with structured output.
* **CI/CD pipelines** failing builds on issues above a severity threshold.

## What it looks like

Running `kodus review` against a working tree change produces a structured report: files affected, issues grouped by severity, suggested fixes you can preview and apply, and an exit code safe for scripting.

<img alt="AI code review in your CLI" />

In `--prompt-only` mode the same review becomes compact, structured text optimized for an AI agent to parse and act on.

## What you can do

<CardGroup>
  <Card title="Interactive Review" icon="terminal">
    Browse files, preview fixes, and apply them one by one from your terminal.
  </Card>

  <Card title="Auto-fix" icon="wand-magic-sparkles">
    Apply every fixable issue at once with `--fix`.
  </Card>

  <Card title="AI Agent Integration" icon="robot">
    Feed `--prompt-only` output into Claude Code, Cursor, or Windsurf for autonomous review-fix loops.
  </Card>

  <Card title="Pre-push Hook" icon="shield-check">
    Block pushes on issues above a severity threshold with `kodus hook install`.
  </Card>

  <Card title="PR Suggestions" icon="code-pull-request">
    Fetch Kody's suggestions on an open pull request without leaving your terminal.
  </Card>

  <Card title="Business Validation" icon="clipboard-check">
    Validate that a local diff satisfies a task's acceptance criteria before merging.
  </Card>

  <Card title="Kody Rules" icon="scale-balanced">
    Create, update, and review team rules that the AI applies during every review.
  </Card>

  <Card title="Decision Memory" icon="brain">
    Persist AI agent decisions as structured files versioned alongside your code.
  </Card>
</CardGroup>

## Limits

|                        | Trial (No Account) | Authenticated      |
| ---------------------- | ------------------ | ------------------ |
| Reviews per day        | 5                  | Based on your plan |
| Files per review       | 10                 | 100                |
| Lines per file         | 500                | —                  |
| Max diff size per file | 500 KB             | 500 KB             |
| Max content per file   | 2 MB               | 2 MB               |

Trial limits reset daily. Run `kodus auth status` to check your current usage.

## CLI vs Kodus Web

The CLI and the Kodus web dashboard share the same review engine, rules, and repository settings. Use the CLI when you want reviews **before the PR exists** — on a local branch, a staged diff, or inside an agent loop. Use the web dashboard for PR reviews, metrics, and team-level configuration.

Changes you make via `kodus config repo` and `kodus rules` apply to both surfaces.

## Next steps

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="getting_started">
    Install, authenticate, and run your first review.
  </Card>

  <Card title="Command Reference" icon="book" href="commands">
    All commands, flags, and options.
  </Card>

  <Card title="AI Agents" icon="robot" href="ai_agents">
    Set up autonomous review-fix loops with coding agents.
  </Card>

  <Card title="Self-Hosted" icon="server" href="self_hosted">
    Connect the CLI to your own Kodus instance.
  </Card>

  <Card title="Troubleshooting" icon="life-ring" href="troubleshooting">
    Common errors, exit codes, and how to debug.
  </Card>
</CardGroup>


# Self-Hosted Setup
Source: https://docs.kodus.io/how_to_use/en/cli/self_hosted

Connect the Kodus CLI to your self-hosted Kodus instance.

If you're running Kodus on your own infrastructure, the CLI works the same way — you just need to point it to your API.

## Connect to Your Instance

<Steps>
  <Step title="Set the API URL">
    Tell the CLI where your Kodus API lives. Pick one method:

    <Tabs>
      <Tab title="Environment Variable (Recommended)">
        ```bash theme={null}
        export KODUS_API_URL=https://kodus-api.yourcompany.com
        ```

        Add this to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to make it permanent:

        ```bash theme={null}
        echo 'export KODUS_API_URL=https://kodus-api.yourcompany.com' >> ~/.zshrc
        source ~/.zshrc
        ```
      </Tab>

      <Tab title="Config File">
        Create or edit `~/.kodus/config.json`:

        ```json theme={null}
        {
          "apiUrl": "https://kodus-api.yourcompany.com",
          "teamKey": "kodus_xxxxx",
          "teamName": "Your Team",
          "organizationName": "Your Org"
        }
        ```

        The CLI creates this file automatically when you run `kodus auth team-key`, but you can also create it manually.
      </Tab>

      <Tab title="Inline (One-off)">
        ```bash theme={null}
        KODUS_API_URL=https://kodus-api.yourcompany.com kodus review
        ```
      </Tab>
    </Tabs>

    <Warning>
      **HTTPS is required.** The CLI rejects non-HTTPS URLs for security. The only exception is `localhost` and `127.0.0.1` for local development.
    </Warning>

    **Priority order:** `KODUS_API_URL` env var > `~/.kodus/config.json` apiUrl > default (`https://api.kodus.io`).
  </Step>

  <Step title="Authenticate">
    <Tabs>
      <Tab title="Team Key (Recommended)">
        Generate a team key from your self-hosted Kodus dashboard and configure it:

        ```bash theme={null}
        kodus auth team-key --key kodus_xxxxx
        ```

        Or use the installer with both API URL and team key:

        ```bash theme={null}
        curl -fsSL https://review-skill.com/install | bash -s -- --team-key kodus_xxxxx
        ```

        <Tip>Team keys are ideal for shared environments and AI agent setups — no individual login required.</Tip>
      </Tab>

      <Tab title="Personal Login">
        ```bash theme={null}
        kodus auth login
        ```

        Enter the email and password registered on your self-hosted instance. Tokens are stored locally in `~/.kodus/credentials.json` with restricted permissions (600).
      </Tab>

      <Tab title="CI/CD Token">
        Generate a token from a personal account, then use it in pipelines:

        ```bash theme={null}
        # Generate (once, from a logged-in machine)
        kodus auth token

        # Use in your pipeline
        export KODUS_API_URL=https://kodus-api.yourcompany.com
        export KODUS_TOKEN=<generated-token>
        kodus review --format json --fail-on error
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify the Connection">
    ```bash theme={null}
    kodus auth status
    ```

    You should see your authentication mode, organization name, and that the token is valid. If using verbose mode, the API URL being used is logged:

    ```bash theme={null}
    kodus auth status --verbose
    ```
  </Step>
</Steps>

## Cloudflare Access (Zero Trust)

If your self-hosted API is behind [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/applications/), the CLI supports service token authentication.

<Tabs>
  <Tab title="Environment Variables">
    ```bash theme={null}
    export KODUS_API_URL=https://kodus-api.yourcompany.com
    export CF_ACCESS_CLIENT_ID=your-client-id.access
    export CF_ACCESS_CLIENT_SECRET=your-client-secret
    ```
  </Tab>

  <Tab title="Config File">
    ```json theme={null}
    {
      "apiUrl": "https://kodus-api.yourcompany.com",
      "teamKey": "kodus_xxxxx",
      "cfAccessClientId": "your-client-id.access",
      "cfAccessClientSecret": "your-client-secret"
    }
    ```
  </Tab>
</Tabs>

The CLI sends `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers on every API request when configured. Priority: env vars > config file.

## Config File Reference

The CLI stores configuration in `~/.kodus/config.json`:

```json theme={null}
{
  "apiUrl": "https://kodus-api.yourcompany.com",
  "teamKey": "kodus_xxxxx",
  "teamName": "Engineering",
  "organizationName": "Acme Corp",
  "cfAccessClientId": "your-client-id.access",
  "cfAccessClientSecret": "your-client-secret"
}
```

| Field                  | Required | Description                                                                       |
| ---------------------- | -------- | --------------------------------------------------------------------------------- |
| `apiUrl`               | No       | Your self-hosted API URL. Overridden by `KODUS_API_URL` env var.                  |
| `teamKey`              | No       | Team API key (starts with `kodus_`). Overridden by `KODUS_TEAM_KEY` env var.      |
| `teamName`             | No       | Display name for the team.                                                        |
| `organizationName`     | No       | Display name for the organization.                                                |
| `cfAccessClientId`     | No       | Cloudflare Access client ID. Overridden by `CF_ACCESS_CLIENT_ID` env var.         |
| `cfAccessClientSecret` | No       | Cloudflare Access client secret. Overridden by `CF_ACCESS_CLIENT_SECRET` env var. |

<Info>
  The config file is created with `0600` permissions (owner read/write only). The directory `~/.kodus/` is created with `0700` permissions.
</Info>

## Environment Variables Summary

| Variable                  | Description                                                   |
| ------------------------- | ------------------------------------------------------------- |
| `KODUS_API_URL`           | Self-hosted API endpoint (HTTPS required, except localhost)   |
| `KODUS_TEAM_KEY`          | Team key for shared access                                    |
| `KODUS_TOKEN`             | CI/CD token for pipelines                                     |
| `CF_ACCESS_CLIENT_ID`     | Cloudflare Access client ID                                   |
| `CF_ACCESS_CLIENT_SECRET` | Cloudflare Access client secret                               |
| `KODUS_VERBOSE`           | Set to `true` to see the resolved API URL and request details |

## CI/CD Integration

For self-hosted instances in CI/CD pipelines, set the API URL and authentication as environment variables:

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml theme={null}
    - name: Kodus Review
      env:
        KODUS_API_URL: ${{ secrets.KODUS_API_URL }}
        KODUS_TEAM_KEY: ${{ secrets.KODUS_TEAM_KEY }}
      run: npx @kodus/cli review --format json --fail-on error
    ```
  </Tab>

  <Tab title="GitLab CI">
    ```yaml theme={null}
    kodus-review:
      script:
        - npx @kodus/cli review --format json --fail-on error
      variables:
        KODUS_API_URL: $KODUS_API_URL
        KODUS_TEAM_KEY: $KODUS_TEAM_KEY
    ```
  </Tab>

  <Tab title="Generic">
    ```bash theme={null}
    export KODUS_API_URL=https://kodus-api.yourcompany.com
    export KODUS_TEAM_KEY=kodus_xxxxx
    npx @kodus/cli review --format json --fail-on error
    ```
  </Tab>
</Tabs>

<Tip>
  Use `--fail-on error` or `--fail-on critical` to fail the pipeline when issues above a severity threshold are found.
</Tip>

## Distributing to Your Team

To onboard your team in one command, combine the API URL with the skill installer:

```bash theme={null}
KODUS_API_URL=https://kodus-api.yourcompany.com \
  curl -fsSL https://review-skill.com/install | bash -s -- --team-key kodus_xxxxx
```

This installs the CLI, configures the team key, and deploys review skills to detected AI agents (Claude Code, Cursor, Windsurf) — all pointing to your self-hosted instance.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Security Error: API URL must use HTTPS protocol">
    The CLI requires HTTPS for all non-localhost URLs. Make sure your self-hosted instance has a valid TLS certificate. If you're testing locally, use `http://localhost:<port>` instead.
  </Accordion>

  <Accordion title="Connection refused or timeout">
    * Verify the URL is reachable: `curl -I https://kodus-api.yourcompany.com`
    * Check if a firewall or VPN is blocking the connection
    * If behind Cloudflare Access, ensure `CF_ACCESS_CLIENT_ID` and `CF_ACCESS_CLIENT_SECRET` are set
    * Use `--verbose` to see the exact URL being used
  </Accordion>

  <Accordion title="Authentication failed (401)">
    * Run `kodus auth status` to check your current auth state
    * If using a team key, verify it's valid on your self-hosted dashboard
    * If using personal login, tokens expire after 1 hour — the CLI auto-refreshes, but you may need to re-login if the refresh token is also expired
    * Make sure `KODUS_API_URL` points to the correct instance
  </Accordion>

  <Accordion title="API returned invalid response (expected JSON, got HTML)">
    This usually means the URL is hitting a reverse proxy, load balancer, or Cloudflare Access page instead of the actual API. Check:

    * The URL path is correct (no trailing `/api` or similar)
    * Cloudflare Access credentials are configured if applicable
    * The reverse proxy is forwarding requests correctly
  </Accordion>

  <Accordion title="Device limit reached">
    Your self-hosted instance may enforce device limits per organization. Contact your admin to increase the limit or remove old devices from the dashboard.
  </Accordion>
</AccordionGroup>


# Troubleshooting
Source: https://docs.kodus.io/how_to_use/en/cli/troubleshooting

Common Kodus CLI errors, exit codes, and how to debug them.

Start any investigation with:

```bash theme={null}
kodus status
kodus auth status
kodus review --verbose    # or any command with --verbose
```

`kodus status` shows the consolidated state (auth mode, org, repo, hook, version). `--verbose` prints the resolved API URL and per-request details.

## Common Errors

<AccordionGroup>
  <Accordion title="Command not found: kodus">
    The CLI isn't on your `PATH`. Reinstall with your package manager's global flag, or use `npx @kodus/cli <command>` for one-off runs.

    * `npm install -g @kodus/cli`
    * `yarn global add @kodus/cli`
    * `pnpm add -g @kodus/cli`
    * `bun add -g @kodus/cli`

    If you installed via the skill installer, re-run `curl -fsSL https://review-skill.com/install | bash` to fix PATH entries.
  </Accordion>

  <Accordion title="AUTH_REQUIRED or 401 Unauthorized">
    * Run `kodus auth status` to see the current mode.
    * If using a team key, verify it's still active at <a href="https://app.kodus.io/organization/cli-keys">app.kodus.io/organization/cli-keys</a>.
    * If using personal login, try `kodus auth login` again — the refresh token may have expired.
    * For CI, confirm `KODUS_TOKEN` (or `KODUS_TEAM_KEY`) is set in the environment the pipeline runs in.
    * If self-hosted, confirm `KODUS_API_URL` points to the correct instance.
  </Accordion>

  <Accordion title="NOT_IN_GIT_REPO">
    `kodus review` requires a git working directory. `cd` into a repo or initialize one with `git init`. For `kodus config repo` commands, you can pass `owner/repo` explicitly instead of `.`.
  </Accordion>

  <Accordion title="Review takes very long or seems to hang">
    Large branches (hundreds of files, thousands of lines) can take several minutes. The default request timeout is 60 minutes — you should see progress in verbose mode.

    * Use `--verbose` to confirm the request is in flight.
    * For very large diffs, prefer `--branch <base>` or `--commit <sha>` over working-tree mode: these let the backend clone the same commit instead of receiving inlined file contents.
    * Override the timeout with `KODUS_REQUEST_TIMEOUT_MIN=90 kodus review` if needed.
    * Split work across smaller branches when practical.
  </Accordion>

  <Accordion title="Files are being skipped from the review">
    Review honors the `ignore-files` patterns configured in `kodus config repo`. List current settings with:

    ```bash theme={null}
    kodus config repo show
    ```

    You can add or remove patterns:

    ```bash theme={null}
    kodus config repo add-ignore-file . "**/*.generated.ts"
    kodus config repo remove-ignore-file . "**/*.generated.ts"
    ```

    Binary files, images, and lockfiles are skipped by default.
  </Accordion>

  <Accordion title="Rate limit reached / Trial exhausted">
    Trial mode allows 5 reviews per day. Sign in with `kodus auth login` or configure a team key via `kodus auth team-key --key kodus_xxxxx` to raise limits. `kodus auth status` prints your current usage.
  </Accordion>

  <Accordion title="API returned invalid response (expected JSON, got HTML)">
    Your `KODUS_API_URL` is hitting a reverse proxy or Cloudflare Access page instead of the API. Check:

    * The URL path (no stray `/api`, `/v1`, etc.).
    * Cloudflare Access credentials (`CF_ACCESS_CLIENT_ID`, `CF_ACCESS_CLIENT_SECRET`) if applicable.
    * That the proxy forwards `Authorization` and `CF-Access-*` headers intact.
  </Accordion>

  <Accordion title="HTTPS required for API URL">
    The CLI rejects non-HTTPS API URLs for everything except `localhost` and `127.0.0.1`. Provision a valid TLS certificate for your self-hosted instance, or use `http://localhost:<port>` for local development.
  </Accordion>

  <Accordion title="Pre-push hook is not running">
    * Confirm installation: `kodus hook status`.
    * Make sure `.git/hooks/pre-push` is executable.
    * Other hook managers (Husky, Lefthook, pre-commit) may overwrite `.git/hooks/pre-push`. Either chain them or reinstall with `kodus hook install --force`.
    * Skip the hook for a single push: `KODUS_SKIP_HOOK=1 git push`.
  </Accordion>

  <Accordion title="Decisions (memory) hooks aren't capturing">
    * Run `kodus decisions status` to see which agents are wired up.
    * Re-run `kodus decisions enable --force` to reinstall integration files.
    * For Codex, ensure `~/.codex/config.toml` contains the `notify = ["kodus", "decisions", "capture", ...]` line, or pass `--codex-config <path>`.
    * Check the agent actually emits turn-complete events (some older Claude Code configurations don't).
  </Accordion>

  <Accordion title="Device limit reached">
    Self-hosted instances can enforce device limits per organization. Ask your admin to increase the limit or remove unused devices from the dashboard.
  </Accordion>
</AccordionGroup>

## Exit Codes

Use these in scripts and CI pipelines.

| Code | Meaning                                                               |
| ---- | --------------------------------------------------------------------- |
| `0`  | Success. No issues found, or issues were found but below `--fail-on`. |
| `1`  | Issues found at or above the `--fail-on` severity.                    |
| `2`  | CLI usage error (invalid flag, missing argument).                     |
| `3`  | Authentication or authorization failure.                              |
| `4`  | Network or API error (timeout, 5xx, invalid response).                |
| `5`  | Not in a git repository, or no changes to review.                     |

<Tip>
  For CI, pair `--fail-on error` with `--format json` and `--output review.json` to surface structured results as pipeline artifacts without affecting the exit code logic.
</Tip>

## Debugging Tips

* **`--verbose` on any command** prints the resolved API URL, request IDs, and timings.
* **`kodus schema`** outputs the machine-readable command schema — useful when your agent reports a missing flag.
* **`--agent`** enforces deterministic, machine-readable output; combine with `--format json` when scripting.
* **`KODUS_VERBOSE=true`** persists verbose mode across multiple commands in a session.

## Getting Help

* Report bugs: [github.com/kodustech/cli/issues](https://github.com/kodustech/cli/issues)
* Feature requests, configuration questions: your Kodus account manager, or `support@kodus.io`.
* For self-hosted deployments, include `kodus status --verbose` output when filing an issue.


# Kodus Review
Source: https://docs.kodus.io/how_to_use/en/cockpit/kodus_review

Measure how effective Kodus's reviews are — and act on it

## What is the Kodus Review tab

The **Kodus Review** tab answers one question: *is your team acting on what Kodus says?*

Unlike the Productivity tab (which measures general delivery metrics like deploy frequency and PR cycle time), Kodus Review is about Kodus itself — how many suggestions get implemented, which categories and rules land or get ignored, and where the team pushes back.

Every chart and table respects the global **repository** and **date range** filters at the top of the page. Click a repository row, a category bar, or a rule to drill into the underlying suggestions.

## Summary cards

| Card                                | What it means                                                                                      |
| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Implementation rate**             | % of sent suggestions the team implemented in the period                                           |
| **Suggestions sent**                | How many suggestions Kodus delivered (as PR comments) in the period                                |
| **Negative vote rate**              | Share of reactions that were 👎, with the trend vs. the previous period                            |
| **Criticals ignored in merged PRs** | Critical suggestions left unimplemented on PRs that were already merged — the actionable risk list |

## Implementation rate

The core metric. A suggestion counts as **implemented** when its final status is `implemented` or `partially_implemented` at the time the PR closes.

```
Implementation rate = implemented suggestions ÷ sent suggestions
```

Scope rules — the same across every implementation-rate chart:

* Only **delivered** suggestions count (the ones actually posted as PR comments). Drafts Kodus filtered out before commenting are never counted.
* Suggestions are attributed to the **week the PR closed**, because implementation status is only final once the PR merges.

### Week over week

The weekly chart shows the trend, with a toggle:

* **Overall** — a single implementation-rate line.
* **By severity** — one line per severity (critical / high / medium / low), so you can see whether higher-severity suggestions get implemented more.

### By category and by severity

* **By category** — sent vs. implemented per suggestion category. Click a bar to open the suggestions explorer filtered to that category.
* **By severity** — implementation rate per severity level. The expectation is a descending gradient (critical implemented more than low). If it looks flat or inverted, severity isn't guiding the team.

<Warning>
  **The "All / Kodus only" toggle on the severity chart matters.** A Kody Rule carries the severity *you* set on the rule, not a risk assessment by Kodus. Mixing the two distorts the calibration read — for example, a pile of medium Kody Rules with high adoption can make Kodus look like it under-rates medium. Switch to **Kodus only** to see Kodus's own severity calibration. Bars built on very few suggestions are faded and marked with `*` — a 0% or 100% from a handful of suggestions is not a real signal.
</Warning>

## Negative feedback

Feedback comes from 👍 / 👎 reactions on Kodus's suggestion comments.

* **Negative vote rate** (summary card) — `👎 ÷ (👍 + 👎)`, with the trend vs. the previous period. Lower is better.
* **By category** — where the team disagrees most. A category with many 👎 is a candidate to retune or disable.
* **Trend** — negative votes week over week.

## Repositories — health

A per-repository table: PRs reviewed, suggestions sent, implementation rate, 👍/👎, and the **weakest category** (the category with the lowest implementation rate in that repo, given a minimum sample). It shows where Kodus is landing versus being ignored.

Clicking a row focuses the whole cockpit on that repository (same as picking it in the repository filter).

## Kody Rules — health

How each Kody Rule is performing in the period: triggers, implementation rate, 👍/👎, and a status. Only active rules appear — deleted or inactive ones are excluded since you can't act on them.

The status is computed per rule, in this priority order:

| Status       | Meaning                                                     | Suggested action                                                     |
| ------------ | ----------------------------------------------------------- | -------------------------------------------------------------------- |
| **Stale**    | No triggers in the period                                   | Review whether the rule is still needed                              |
| **Low data** | Triggered, but too few times (fewer than 5) to judge        | Wait for more data                                                   |
| **Noisy**    | The team actively downvotes it (≥ 3 👎 and more 👎 than 👍) | The rule is miscalibrated — rewrite or scope it (e.g. exclude tests) |
| **Ignored**  | Triggers a lot but almost nothing is implemented (≤ 20%)    | Question its relevance — does the team care about it?                |
| **Healthy**  | Everything else                                             | No action                                                            |

**Noisy** and **Ignored** look similar but call for different actions. *Ignored* is passive — the rule fires but nobody implements it, and you can't tell if it's noise or just neglect. *Noisy* is active disagreement — the team explicitly downvotes it, so you know it's noise. That's why a rule that is both shows as **Noisy**: the downvotes are the stronger, more actionable signal. The thresholds are sensible defaults and may be tuned over time.

## Suggestions explorer

Every drill-down — a category bar, a rule row, the "criticals ignored" card — opens the **suggestions explorer**: a filterable, paginated list of the actual suggestions behind the number.

Filters: repository, category, severity, implementation status, Kody Rule, and free-text search. Each row expands to show the existing vs. suggested code and a link to the PR comment.


# Bug Ratio
Source: https://docs.kodus.io/how_to_use/en/cockpit/metrics/change_failure_rate

Measure the percentage of PRs that are bug fixes (also known as Change Failure Rate)

## What is Bug Ratio

Bug Ratio measures the percentage of Pull Requests that are bug fixes or corrections in relation to the total number of PRs. This metric helps you understand how much of your development effort is spent fixing issues versus building new features. It can also be read as "Change Failure Rate" - the rate at which changes result in failures.

## How We Calculate It

We automatically identify which PRs are bug fixes using AI language models (LLM) that analyze the Pull Request names and descriptions. The system then calculates the percentage of bug-related work relative to your total PR activity.

**What We Track:**

* PRs identified as bug fixes by AI analysis
* Total number of PRs in the period
* The percentage of bug-related work

**How It's Calculated:**

```
Bug Ratio = (Bug Fix PRs) ÷ (Total PRs) × 100
```

For example, if 3 out of 15 PRs are identified as bug fixes, your bug ratio is 20%.

**How We Identify Bug Fixes:**
We use advanced language models to analyze PR titles and automatically classify them. The AI looks for patterns like:

* "Fix bug in..." or "Bug fix for..."
* "Resolve issue with..." or "Fix problem in..."
* "Patch for..." or "Hotfix:..."

## Why It Matters

The Bug Ratio is a key indicator of your team's development focus and code quality. Understanding this ratio helps you:

* **Development Focus**: See how much time is spent fixing vs. building
* **Code Quality**: Identify if you're spending too much time on bugs
* **Process Improvement**: Understand if your development process needs optimization
* **Resource Planning**: Plan how much effort to allocate to bug fixes

## How to Improve

* Implement comprehensive testing strategies (unit, integration, E2E)
* Use automated tools (linters, static analyzers) pre-production
* Ensure thorough code reviews for all changes
* Break large features into smaller, testable pieces
* Use feature flags for safer deployments
* Conduct post-incident reviews to prevent recurrence

## Best Practices for PR Naming

To help the AI accurately identify bug fixes, consider these naming conventions:

### Good Bug Fix PR Names

* "Fix: User login fails with invalid credentials"
* "Bug fix: Memory leak in data processing module"
* "Resolve issue: API returns 500 error for large requests"
* "Patch: Fix null pointer exception in user service"

### Avoid Vague Names

* "Fix stuff" or "Bug fix"
* "Update code" or "Improve performance"
* "Fix things" or "Resolve issues"

### Feature vs Bug Fix

* **Bug Fix**: "Fix: Payment validation fails for expired cards"
* **Feature**: "Add: New payment method support"
* **Improvement**: "Enhance: Payment validation error messages"


# Deploy Frequency
Source: https://docs.kodus.io/how_to_use/en/cockpit/metrics/deploy_frequency

Measure how often your team deploys code to production

## What is Deploy Frequency

Deploy Frequency measures how many times your team successfully deploys code to production within a given time period. This metric is a key indicator of your team's ability to deliver value quickly and maintain a smooth delivery pipeline.

## How We Calculate It

We automatically track every time your team merges code into the main branch (or default branch). Since merges to main typically trigger deployments, this gives us a good measure of how frequently your team delivers code to production.

**What We Track:**

* Every merge to your main/default branch
* The time period you select (daily, weekly, monthly)
* Successful code integrations

**How It's Calculated:**

```
Deploy Frequency = (Number of Merges to Main) ÷ (Time Period in Weeks)
```

For example, if you merge 12 times to main in a 4-week period, your deploy frequency is 3 merges per week.

**Note**: We measure merges to main because they typically represent when code is ready for production deployment. If your team has a different workflow (like deploying from feature branches), this metric may need interpretation.

## Why It Matters

Frequent deployments ensure new features and bug fixes reach users quickly, boosting customer satisfaction and competitiveness. They also reduce risks and facilitate issue resolution.

## How to Improve

* Implement CI/CD pipelines for automated deployments
* Break large changes into smaller PRs
* Use feature flags to deploy without exposing features
* Make infrastructure as code for repeatable deployments
* Set up comprehensive monitoring and quick rollback


# Developer Activity
Source: https://docs.kodus.io/how_to_use/en/cockpit/metrics/developer_activity

Track developer productivity and activity patterns over time

## What is Developer Activity

Developer Activity measures how productive your team members are over time, tracking commits, Pull Requests, and reviews on a weekly basis. This helps you understand individual performance, team workload distribution, and identify patterns in development activity.

## How We Calculate It

We automatically track each developer's activity throughout the week, measuring their contributions and engagement with the codebase.

**What We Track:**

* **PRs Created**: Number of PRs created by each developer

**How It's Calculated:**

```
Weekly Activity = COUNT(PRs Created) per developer per week
```

We aggregate data by week starting Monday to give you consistent weekly insights.

## Why It Matters

Understanding developer activity helps you:

* **Identify Top Performers**: Recognize your most productive team members
* **Balance Workload**: Distribute work more evenly across the team
* **Track Trends**: See how productivity changes over time
* **Improve Collaboration**: Understand team dynamics and patterns

### Impact on Team Performance

* **Resource Allocation**: Better distribute work based on capacity
* **Performance Recognition**: Acknowledge and reward high performers
* **Bottleneck Identification**: Find where work gets stuck
* **Team Health**: Monitor for burnout or disengagement

## How to Improve

* Set clear goals and specific targets for each developer
* Provide training and learning opportunities
* Spread work more evenly across the team
* Encourage collaboration and knowledge sharing
* Define clear processes for how work flows
* Reduce manual, repetitive tasks through automation


# Kody Suggestions
Source: https://docs.kodus.io/how_to_use/en/cockpit/metrics/kody_suggestions

Measure the effectiveness of AI-powered code suggestions

## What are Kody Suggestions

Kody Suggestions measures the effectiveness of AI-powered code suggestions generated by Kodus. This metric tracks how many suggestions are sent to developers and how many are actually implemented, providing insights into the value and adoption of AI-assisted development.

## How We Calculate It

We automatically track how many AI-powered suggestions Kody sends to your team and how many of those suggestions are actually implemented in your code.

**What We Track:**

* Suggestions sent to developers
* Suggestions that get implemented
* The percentage of suggestions that are adopted

**How It's Calculated:**

```
Implementation Rate = (Implemented Suggestions) ÷ (Total Suggestions Sent) × 100
```

For example, if Kody sent 20 suggestions and 16 were implemented, your implementation rate is 80%.

## Why It Matters

Kody Suggestions provide several benefits for your development team:

* **Productivity Boost**: AI can catch common issues and suggest improvements
* **Code Quality**: Consistent suggestions help maintain coding standards
* **Learning Opportunity**: Developers learn best practices through AI feedback
* **Time Savings**: Reduce time spent on routine code review tasks

## How to Improve

* Configure custom Kody rules specific to your team's standards
* Provide feedback on suggestions to improve accuracy
* Ensure Kody has access to relevant codebase context
* Educate developers on how to use Kody effectively
* Share examples of how Kody has helped the team
* Gather input on suggestion usefulness


# Lead Time Breakdown
Source: https://docs.kodus.io/how_to_use/en/cockpit/metrics/lead_time_breakdown

Break down your development cycle into coding, pickup, and review phases

## What is Lead Time Breakdown

Lead Time Breakdown gives you a detailed view of your development process by breaking down the total cycle time into three key phases: coding time, pickup time, and review time. This helps you identify exactly where bottlenecks occur in your workflow.

## How We Calculate It

We automatically track the time spent in each phase of your development process, from first commit to PR merge.

**What We Track:**

* **Coding Time**: Active development time (first commit to last commit)
* **Pickup Time**: Time between last commit and creating the PR
* **Review Time**: Time from PR creation to merge

**What We Don't Count:**

* Time before first commit (planning, design)
* Time after merge (deployment, etc.)
* Failed or abandoned PRs

**How It's Calculated:**

```
Coding Time = (Last Commit Time) - (First Commit Time)
Pickup Time = (PR Opened Time) - (Last Commit Time)  
Review Time = (PR Closed Time) - (PR Opened Time)
```

We use the 75th percentile (P75) for each phase to filter out outliers and show you typical performance.

## Why It Matters

Understanding where time is spent helps you optimize the right part of your process:

* **Coding Time**: Shows development efficiency
* **Pickup Time**: Reveals workflow bottlenecks
* **Review Time**: Indicates review process effectiveness

## How to Improve

### Reduce Coding Time

* **Clear Requirements**: Ensure developers understand what to build
* **Smaller Features**: Break large changes into manageable pieces
* **Pair Programming**: Collaborate to solve complex problems faster
* **Code Reuse**: Leverage existing patterns and components

### Reduce Pickup Time

* **Immediate PR Creation**: Create PRs right after finishing code
* **Workflow Automation**: Use tools to streamline PR creation
* **Clear Definition of Done**: Know exactly when code is ready
* **Reduce Context Switching**: Focus on completing one task at a time

### Reduce Review Time

* **Review Guidelines**: Set clear expectations for reviewers
* **Automated Checks**: Use tools to catch issues before review
* **Review Rotation**: Distribute review workload across the team
* **Quick Responses**: Respond promptly to review comments

## Common Bottlenecks

### Coding Time

* **Unclear Requirements**: Developers don't know what to build
* **Complex Features**: Changes that are too large or complex
* **Technical Debt**: Working around existing code issues
* **Dependencies**: Waiting for other components or services

### Pickup Time

* **Workflow Inefficiency**: Manual steps that slow down the process
* **Context Switching**: Moving between multiple tasks
* **Lack of Automation**: Manual PR creation and setup

### Review Time

* **Large PRs**: Changes that are too big to review quickly
* **Reviewer Availability**: Not enough people available to review
* **Unclear Changes**: PRs that are hard to understand
* **Review Backlog**: Too many PRs waiting for review


# PR Cycle Time
Source: https://docs.kodus.io/how_to_use/en/cockpit/metrics/lead_time_for_changes

Measure the time from first commit to production deployment

## What is PR Cycle Time

PR Cycle Time measures the total time from when a developer first commits code until that code is successfully merged into the default branch. This metric represents the end-to-end delivery speed of your development process.

## How We Calculate It

We automatically track the time between your first commit and when that code gets merged into the default branch (main/master). Since merges to main typically represent when code is ready for production, this gives us a good measure of your development cycle time.

**What We Track:**

* Time from first commit to PR merge
* The complete development cycle
* How long code takes to be integrated

**What We Don't Count:**

* Time spent planning or designing (before first commit)
* Time after merge (deployment, user adoption, etc.)
* Failed or abandoned changes

**How It's Calculated:**

```
PR Cycle Time = (PR Merge Time) - (First Commit Time)
```

We use the 75th percentile (P75) to show you the typical cycle time, filtering out unusually long outliers that could skew your understanding of normal performance.

## Why It Matters

PR Cycle Time is a critical metric that measures your team's ability to complete development work efficiently. High cycle times may indicate large batch sizes, lengthy review processes, or bottlenecks in the development workflow.

## How to Improve

* Break large changes into smaller PRs (200-400 lines)
* Set clear review expectations and guidelines
* Use automated checks to catch issues pre-review
* Distribute review workload across the team
* Get early feedback during development
* Use consistent branching strategy


# PR Size
Source: https://docs.kodus.io/how_to_use/en/cockpit/metrics/pr_size

Measure the average size of your Pull Requests

## What is PR Size

PR Size measures the average number of changes (lines added, modified, or deleted) in your Pull Requests. This metric helps you understand how your team breaks down work and can indicate potential bottlenecks in the development process.

## How We Calculate It

We automatically measure the size of every Pull Request by counting the total lines of code that were added, modified, or deleted.

**What We Track:**

* Total lines changed in each PR
* Additions, modifications, and deletions
* The average size across all your PRs

**How It's Calculated:**

```
PR Size = (Total Lines Added + Modified + Deleted) ÷ (Number of PRs)
```

For example, if you have 3 PRs with 50, 100, and 150 lines changed, your average PR size is 100 lines.

## Why It Matters

PR Size is a critical metric that impacts multiple aspects of your development process:

* **Review Quality**: Smaller PRs are easier to review thoroughly
* **Deployment Speed**: Smaller changes can be deployed more frequently
* **Risk Management**: Large changes increase the risk of introducing bugs
* **Team Collaboration**: Smaller PRs enable faster feedback and iteration

## How to Improve

* Use feature flags for incremental rollout
* Break user stories into smaller, focused tasks
* Set clear PR size limits (200-400 lines recommended)
* Build vertical slices instead of technical layers
* Refactor regularly to maintain modularity


# PRs by Developer
Source: https://docs.kodus.io/how_to_use/en/cockpit/metrics/prs_by_developer

Track completed Pull Requests per developer grouped by week

## What is PRs by Developer

PRs by Developer measures the number of **closed** Pull Requests completed by each team member, grouped by week. This metric focuses on actual results and completed work, giving you insights into individual developer productivity and team workload distribution.

## How We Calculate It

We automatically track every closed Pull Request and group them by developer and week, starting from Monday. This gives you a clear view of who is completing work and when.

**What We Track:**

* **Closed PRs**: Every PR that has been completed (merged or closed)
* **Developer Attribution**: Who authored each completed PR
* **Weekly Aggregation**: Grouped by week starting Monday
* **Completion Count**: Number of PRs finished per developer per week

**What We Don't Count:**

* Open or draft PRs
* PRs without a valid close date
* Incomplete or abandoned work

**How It's Calculated:**

```
Weekly PRs per Developer = COUNT(closed PRs) per developer per week
```

We group data by week starting Monday to give you consistent weekly insights and identify trends over time.

## Why It Matters

Understanding PR completion by developer helps you:

* **Measure Individual Output**: See who is completing the most work
* **Identify Productivity Patterns**: Understand weekly rhythms and trends
* **Balance Workload**: Distribute work more evenly across the team
* **Track Team Performance**: Monitor overall team velocity and output

### Impact on Team Management

* **Resource Allocation**: Better distribute work based on individual capacity
* **Performance Recognition**: Acknowledge high performers and their contributions
* **Bottleneck Identification**: Find where work gets stuck or delayed
* **Team Planning**: Set realistic expectations for project timelines

### Team Distribution

* **Balanced**: Work distributed evenly across team members
* **Concentrated**: Few developers handling most of the work
* **Fragmented**: Work spread too thinly across many developers

## How to Improve

### Increase Individual Output

* **Clear Goals**: Set specific, achievable targets for each developer
* **Skill Development**: Provide training on areas that slow them down
* **Tool Optimization**: Ensure developers have the right tools and access
* **Reduced Blockers**: Remove obstacles that prevent work completion

### Improve Team Balance

* **Work Distribution**: Spread work more evenly across the team
* **Cross-training**: Help developers work on different areas
* **Pair Programming**: Encourage collaboration and knowledge sharing
* **Mentorship**: Senior developers help junior team members

### Optimize Workflow

* **Clear Processes**: Define how work flows through the team
* **Automation**: Reduce manual, repetitive tasks
* **Communication**: Improve team coordination and information sharing
* **Review Efficiency**: Streamline the code review process

## Key Differences from Developer Activity

| **Aspect**      | **Developer Activity** | **PRs by Developer**  |
| --------------- | ---------------------- | --------------------- |
| **PR Status**   | ❌ No filtering         | ✅ `status = 'closed'` |
| **Date Basis**  | **Creation** date      | **Completion** date   |
| **Aggregation** | By **specific date**   | By **week**           |
| **Focus**       | Creation activity      | Completed results     |

## Common Patterns

### High Output Developers

* **Characteristics**: Consistently complete many PRs per week
* **Benefits**: Drive team velocity, set performance standards
* **Risks**: Potential burnout, knowledge silos
* **Management**: Ensure sustainable pace, share knowledge

### Low Output Developers

* **Characteristics**: Complete fewer PRs per week
* **Possible Causes**: Learning curve, complex tasks, external factors
* **Support**: Provide mentoring, simplify tasks, check for blockers
* **Goals**: Set incremental improvement targets

## Context Considerations

* **PR Size**: A developer with fewer but larger PRs may be equally productive
* **Complexity**: Some work naturally takes longer to complete
* **Team Role**: Different roles may have different PR patterns
* **Project Phase**: Output varies during different development phases


# Overview
Source: https://docs.kodus.io/how_to_use/en/cockpit/overview

Comprehensive analytics and metrics for engineering team performance

## What is Cockpit Analytics

Cockpit Analytics provides comprehensive insights into your engineering team's performance through key metrics that measure productivity, code quality, and delivery efficiency. These metrics help you identify areas for improvement and track progress over time.

<Warning>
  Cockpit is available exclusively on the **Teams plan (cloud)**. Self-hosted Community installations do not include Cockpit features.
</Warning>

<Frame>
  <img />
</Frame>

## Key Features

* Data refreshes every 2 hours
* Teams plan only (cloud)
* AI-powered metric calculation
* 8+ DORA and custom metrics

## The two tabs

The cockpit is split into two tabs:

* **Kodus Review** — how effective Kodus's reviews are: implementation rate, severity calibration, negative feedback, and the health of your Kody Rules. This is about Kodus itself, and it's where you take action. See [Kodus Review](/how_to_use/en/cockpit/kodus_review).
* **Productivity** — general delivery metrics: deploy frequency, lead time, PR cycle time, PR size, and developer activity.

## Key Metrics Categories

**Available Metrics:**

* **Kodus Review:** Implementation rate (overall, by severity, by category), negative feedback, repository and Kody Rule health
* **Productivity:** Deployment frequency, lead time, PR cycle times
* **Quality:** PR size, code review effectiveness
* **Team Performance:** Collaboration patterns, bottleneck identification

## How Developer Matching Works

Cockpit tracks developers using the **Git commit username**. This may differ from:

* GitHub/GitLab display name
* Email address
* Kodus workspace account

<Tip>
  If you see discrepancies in developer metrics, check that commit usernames are consistent across your team's Git configuration.
</Tip>


# Business Logic Validation
Source: https://docs.kodus.io/how_to_use/en/code_review/business_logic_validation

Compare your pull request against business rules or specs with @kody -v business-logic.

## Overview

Business Logic Validation lets you confirm that a pull request implements the expected behaviour described in a spec, document, or ticket. Kody analyzes the PR diff, brings in the referenced business context, and flags mismatches before you merge.

<img alt="Example of using business logic validation" />

## Prerequisites

* If you want Kody to **automatically fetch task context** from tools like Jira, Linear, Notion, or ClickUp, the corresponding plugin must be connected in your workspace's [Plugins](/how_to_use/en/code_review/plugins) page.
* Any link you share (Jira, Slack, Google Docs, etc.) must be reachable through the plugins installed in your workspace.
* You can always **provide the spec inline** without any plugin — just paste the requirements directly in the PR comment.

## Enabling Business Logic Validation

Business Logic Validation is **enabled by default**. You can control it in two ways:

**Via `kodus-config.yml`:**

```yaml theme={null}
reviewOptions:
  business_logic: true
```

**Via the web UI:**

Go to **Code Review Settings** → **Repository** → **General** → **Analysis Types** and toggle **Business Logic**.

When enabled, Kody runs business logic validation automatically during every PR review, in addition to the on-demand command.

## Running On-Demand

You can also trigger validation manually at any time:

1. Open the main PR comment box (outside of inline code suggestions).
2. Mention Kody and add the validation command: `@kody -v business-logic ...`.
3. Provide the spec content inline or paste a link that Kody can fetch via the available plugins.
4. Submit the comment and wait for Kody's response in the same thread.

The command only triggers from the main conversation box; replies inside inline suggestions are ignored.

You can re-run the validation at any time — simply post the command again in a new comment. Follow-ups must be a fresh command; replying directly to Kody's message in the Git UI is not supported.

### Examples

* Jira ticket: `@kody -v business-logic https://kodustech.atlassian.net/jira/software/c/projects/KC/boards/2?selectedIssue=KC-1292`
* Linear issue: `@kody -v business-logic https://linear.app/your-team/issue/TEAM-123`
* Notion page: `@kody -v business-logic https://www.notion.so/your-workspace/Feature-Spec-abc123`
* Google Doc: `@kody -v business-logic https://docs.google.com/document/d/1234567890/edit`
* Slack conversation: `@kody -v business-logic https://kodustech.slack.com/archives/C070E5E97DE/p1727814000000000`
* Inline spec snippet: `@kody -v business-logic Rule XYZ — orders above $500 must issue cashback credits.`

## What Kody Does

1. **Fetches the PR diff** and pull request metadata.
2. **Retrieves the task context** — from the linked task management tool (Jira, Linear, etc.) or from inline text you supplied.
3. **Classifies task context quality** — determines how thorough the analysis can be based on available information.
4. **Compares implementation against requirements** — checks each acceptance criterion against the PR diff.
5. **Reports findings** with severity levels and requirement tracing.

If Kody cannot reach the resource or lacks permissions, it will call that out so you can adjust access or provide the information another way.

## Task Context Quality

Kody automatically classifies the quality of the task context before analysis, which affects the depth of validation:

| Quality      | Description                                          | Analysis Behavior                            |
| ------------ | ---------------------------------------------------- | -------------------------------------------- |
| **Complete** | Has title, description, and acceptance criteria      | Thorough criterion-by-criterion analysis     |
| **Partial**  | Has title and description but no acceptance criteria | Best-effort analysis from described behavior |
| **Minimal**  | Has only a title or very short description           | Conservative — flags only obvious gaps       |
| **Empty**    | No meaningful task context found                     | Returns a "Need Task Information" response   |

## Understanding the Output

### Finding Severities

Each finding includes a severity level:

* **MUST\_FIX** — A required business rule is not implemented, is incorrect, or contradicts task requirements
* **SUGGESTION** — A relevant edge case, robustness, or maintainability point is not covered
* **INFO** — Useful observation that does not block compliance

### Grounded Findings

Every finding is **traceable to a specific requirement** from the task context. Each finding includes:

* **Requirement** — The exact quote from the task that establishes the requirement
* **Missing in code** — What is absent or wrong in the PR diff
* **Suggested action** — A concrete implementation action

Kody does not invent requirements. If a finding cannot be traced back to a specific sentence in the task, it is not reported.

### Scope Mismatch Detection

If the PR diff appears to be working in a different domain than the task itself, Kody detects this as a **scope mismatch** and reports it as the leading finding, rather than producing misleading gap analysis.

### Example Output

```markdown theme={null}
## Business Rules Validation

**Task:** KC-1441 - Team-scoped Kody rules
**Task Link:** https://kodustech.atlassian.net/browse/KC-1441
**Status:** Issues Found
**Confidence:** high

### Findings

#### MUST_FIX: No evidence of team-scoped rule resolution in this PR diff
**Requirement:** "Rules must be resolved by organization and team
to avoid cross-workspace billing mismatch."
**Missing in code:** No evidence in this PR diff of adding `teamId`
to the relevant persistence or lookup path.
**Suggested action:** Add `teamId` to rule persistence and query filters.

#### SUGGESTION: No evidence of deterministic mixed-license handling
**Requirement:** "When teams have different subscription states,
behavior must remain deterministic."
**Missing in code:** No evidence in this PR diff of logic handling
mixed subscription states.
**Suggested action:** Add deterministic fallback and error handling
scoped to team.

### Requirements Verified
- AC #1: "Team-scoped reads/writes" — Implemented in `rules.service.ts:42`
- AC #2: "Multi-workspace billing path" — Implemented in `billing.service.ts:118`

---
*Analysis performed by Kodus AI Business Rules Validator*
```

## Tips

* Break large specs into sections and validate them individually to keep feedback focused.
* When sharing private links, double-check that the required plugin (e.g., Jira, Slack, Google Drive) is installed and authorized for your workspace.
* After addressing findings, rerun the command to confirm the PR now aligns with the business rules.
* Provide acceptance criteria in your task for the most thorough analysis — tasks with explicit criteria get criterion-by-criterion validation.


# Centralized Config
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/centralized_config

Manage all code review configuration and Kody Rules as code in a single repository. Changes sync automatically after each merge; rollout is controlled from the UI or the CLI.

Centralized Config lets you keep every code review setting and every Kody Rule in **one repository** instead of editing them per-repo in the web UI. Each change flows through a pull request on that repository, giving you version history, review, and rollback on your review configuration.

Use it when you want:

* A single source of truth for review behavior across many repositories.
* Code-review-as-code: history, PR review, rollback, CI validation.
* Consistent Kody Rules (review rules and memories) across the whole organization.
* CLI-driven or CI-driven configuration changes.

## How It Works

1. Choose one repository to hold your centralized config.
2. Enable Centralized Config in the UI and point it at that repository.
3. Pick an **initial sync mode**:
   * `pr` — Kodus opens the initialization PR with your current effective settings and rules.
   * `manual` — Kodus generates the files; your team downloads and opens the PR.
4. After the first merge, every future merge on the centralized repository automatically propagates changes to Kodus.

The centralized repository mirrors Kodus's scope hierarchy (Global → Repository → Directory) through its folder layout.

## Repository Layout

The centralized repository uses folder paths to map files to scopes. The layout covers both review settings (`kodus-config.yml`) and Kody Rules (`.kody-rules/`).

<Note>
  The repository name is arbitrary — pick whatever fits your organization. `kodus-config` is used below as a convention.
</Note>

```
kodus-config/
├── kodus-config.yml                      ← global settings
├── .kody-rules/
│   ├── review/                           ← global review rules
│   │   └── require-tests-for-endpoints.yml
│   └── memories/                         ← global memories
│       └── logging-convention.yml
│
├── backend-api/                          ← matches a Kodus repo
│   ├── kodus-config.yml                  ← repository-level overrides
│   ├── .kody-rules/
│   │   ├── review/
│   │   │   └── no-raw-sql.yml
│   │   └── memories/
│   │       └── auth-module-layout.yml
│   │
│   └── src/auth/                         ← matches a repo subdirectory
│       ├── kodus-config.yml              ← directory-level overrides
│       └── .kody-rules/
│           ├── review/
│           └── memories/
│
└── frontend-web/
    └── kodus-config.yml
```

Rules:

* A `kodus-config.yml` at the **root** of the centralized repo applies globally.
* A top-level folder whose name matches a Kodus repository (e.g. `backend-api/`) scopes files to that repository.
* A nested path inside a repo folder (e.g. `backend-api/src/auth/`) scopes files to that directory, following the same inheritance model as the web UI.
* Rules under `.kody-rules/review/` become **review rules**; rules under `.kody-rules/memories/` become **memories**.

Any file missing a matching scope is ignored on sync.

## Config Files

Each `kodus-config.yml` uses the same schema as the per-repo `kodus-config.yml` documented in [General settings](/how_to_use/en/code_review/configs/general). Fields are applied at the level of the folder where the file lives and follow the usual inheritance rules (see [Config Inheritance & Overrides](/how_to_use/en/code_review/configs/inheritance_overrides)).

Minimal example:

```yaml theme={null}
version: '1.2'
reviewOptions:
  security: true
  kody_rules: true
  error_handling: true
suggestionControl:
  groupingMode: full
  limitationType: pr
  maxSuggestions: 9
  severityLevelFilter: medium
ignorePaths:
  - yarn.lock
  - package-lock.json
automatedReviewActive: true
```

## Kody Rules Files

Each rule is a single YAML file under `.kody-rules/review/` (standard rules) or `.kody-rules/memories/` (memories). The filename is arbitrary — Kodus identifies rules by the `title` field and by the canonical file path stored with the rule.

Example review rule (`.kody-rules/review/require-tests-for-endpoints.yml`):

```yaml theme={null}
title: Require tests for new endpoints
rule: |
  Every new HTTP endpoint handler must include at least one integration test
  that exercises the happy path and one common failure mode.
severity: high
scope: pull-request
path: apps/api/**
examples:
  - snippet: |
      // endpoint added with matching *.spec.ts
    isCorrect: true
  - snippet: |
      // endpoint added with no test file touched in the PR
    isCorrect: false
inheritance:
  inheritable: true
  exclude: []
  include: []
```

See [Kody Rules Overview](/how_to_use/en/code_review/configs/kody_rules) for the full field reference and [Rule Inheritance](/how_to_use/en/code_review/configs/rules_inheritance) for how `inheritance.inheritable`, `exclude`, and `include` behave.

## UI Workflow

From **Settings → Code Review → General**:

1. Open **Centralized Config**.
2. Enable Centralized Config.
3. Select the source repository.
4. Pick the **Initial Sync Method**:
   * Automatic (Create PR now)
   * Manual (Sync later)
5. Save and confirm status.

## Web UI Behavior When Enabled

When Centralized Config is enabled, the source of truth for configuration is the centralized repository. The web UI reflects this:

* **Repository, directory and global code review settings** become read-only in the web UI. Edit them by opening a PR on the centralized repository.
* **Kody Rules and PR Messages** remain editable in the web UI. Saving an edit does not mutate the rule directly — Kodus opens a pull request on the centralized repository with the proposed change. Once the PR is merged, the change becomes active.

This preserves the "everything is reviewed and versioned" guarantee while keeping the visual editing experience for rules and messages.

### UI rules and repo rules coexist

Enabling Centralized Config does **not** wipe rules that were previously created in the web UI, and it does **not** prevent new rules from being created through the UI. Both sources feed the same pool of active rules:

* Rules imported from the centralized repository are persisted with status `SYNCED`.
* Rules created directly in the web UI live alongside them and stay active.
* At review time, Kodus loads **every active rule** from the database regardless of origin. A rule that exists only in the UI is applied exactly like a rule that exists only in the repo.
* Rules in status `PENDING_ADD` (a UI/CLI edit that opened a PR not yet merged) are **excluded** from reviews until the PR is merged and the status transitions to `SYNCED`.

In practice: if you bootstrap the centralized repo by hand and it's missing a rule you already had in the UI, that rule keeps running — it just isn't version-controlled in the repo. To bring it under version control, edit it once in the UI (which opens a PR) or use `init` so Kodus bundles every existing rule into the initialization PR.

## Sync States

Each rule that comes from Centralized Config tracks its lifecycle through a status:

| Status           | Meaning                                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `SYNCED`         | The rule in Kodus matches the file in the centralized repository.                                              |
| `PENDING_ADD`    | A new rule has been created via UI/CLI and a PR was opened; the file does not exist on the default branch yet. |
| `PENDING_EDIT`   | An edit was proposed via UI/CLI and a PR is open; the existing file has not been updated yet.                  |
| `PENDING_DELETE` | A deletion was proposed via UI/CLI and a PR is open; the file still exists on the default branch.              |

`PENDING_*` transitions back to `SYNCED` once the corresponding PR is merged.

## Sync Modes

<Tabs>
  <Tab title="PR (default)">
    Kodus opens the initialization pull request automatically with your
    current effective settings and rules.
  </Tab>

  <Tab title="Manual">
    Kodus generates the files but does not open a PR. Use the download bundle
    to export the files, then open and merge the PR yourselves.
  </Tab>
</Tabs>

## Download Configuration Bundle

You can download a ZIP containing the generated `kodus-config.yml` files and `.kody-rules/` tree that reflect your current settings and rules.

Use this when:

* Auditing generated configuration.
* Sharing setup artifacts with another team.
* Keeping a local backup before a rollout.
* Bootstrapping the centralized repository in `manual` mode.

## Disable Centralized Config

Disabling Centralized Config clears the selected source repository and returns all repositories to the standard non-centralized behavior (settings edited in the web UI, optional per-repo `kodus-config.yml`).

Rules and settings that were synced in remain in Kodus — they are not deleted on disable.

## CLI

Use these commands to manage Centralized Config from terminal workflows and CI scripts.

### Requirements

* Team key authentication.
* At least one selected repository in Kodus.

Authenticate with:

```bash theme={null}
kodus auth team-key --key <your-key>
```

### Check Status

```bash theme={null}
kodus config centralized status
```

### Initialize Centralized Config

```bash theme={null}
kodus config centralized init [owner/repo] --sync-option <pr|manual>
```

Notes:

* `--sync-option` defaults to `pr`.
* If the repository is omitted in an interactive terminal, the CLI prompts for selection.
* In non-interactive environments, the repository must be provided.

Examples:

```bash theme={null}
kodus config centralized init kodustech/kodus-config --sync-option pr
kodus config centralized init kodustech/kodus-config --sync-option manual
```

### Run Sync

```bash theme={null}
kodus config centralized sync
```

### Disable Centralized Config

```bash theme={null}
kodus config centralized disable
```

### Download Config ZIP

```bash theme={null}
kodus config centralized download --out ./centralized-config.zip
```

Notes:

* `--out` is required.
* Output is a ZIP bundle containing the generated config files and `.kody-rules/` tree.

### JSON Output

All centralized commands support structured output with `--json`.

```bash theme={null}
kodus config centralized status --json
kodus config centralized init kodustech/kodus-config --sync-option pr --json
kodus config centralized sync --json
kodus config centralized disable --json
kodus config centralized download --out ./centralized-config.zip --json
```

## Related

* [General Settings](/how_to_use/en/code_review/configs/general)
* [Config Inheritance & Overrides](/how_to_use/en/code_review/configs/inheritance_overrides)
* [Kody Rules Overview](/how_to_use/en/code_review/configs/kody_rules)
* [Rule Inheritance](/how_to_use/en/code_review/configs/rules_inheritance)
* [CLI command reference](/how_to_use/en/cli/commands)


# Custom Messages
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/custom_messages

Configure personalized start and end review messages for Kody

## Overview

Customize the messages that Kody sends at the beginning and end of code reviews. This feature allows you to personalize the communication style and add specific context or instructions for your team.

## Default Behavior

When you haven't customized any messages, Kody works as follows:

1. **Initial Message**: Kody sends a standard start review message
2. **Suggestions**: Kody provides all code review suggestions
3. **Final Message**: Kody updates the initial message with a summary of the review

## Custom Message Behavior

Once you edit either the start or end review message for the first time, Kody's behavior changes to:

1. **Initial Message**: Kody sends your custom start review message
2. **Suggestions**: Kody provides all code review suggestions
3. **Final Message**: Kody sends your custom end review message (without updating the initial message)

This creates a complete timeline: **Initial Message → Suggestions → Final Message**

## Message Configuration Options

### Message Behavior

Use the **Message behavior** dropdown to decide when Kody should post your custom
start and end messages:

* **Important:** Messages are only sent when a review actually runs.\
  If your review cadence is **Manual**, messages are posted only when someone runs `@kody start-review`.

* **Every push**: Kody posts the start message when the pull request opens and
  repeats the start/end pair after every new push **that triggers a review**.
  This happens automatically only when cadence is **Automatic** or **Auto-pause**.

* **Only when opened**: Kody sends the start and end messages only once, right
  after the first review run. If cadence is **Manual**, the first review run is
  when you call `@kody start-review`. Future pushes just add review suggestions
  plus the usual reaction so authors know the review reran.

* **Off**: Custom messages are disabled. Kody still runs the review and posts
  suggestions, but no start or end messages are sent.

When the behavior is `Every push` or `Only when opened`, Kody uses whichever
templates you have filled in. If you only customize the start message, only that
message is sent; same for the end message. This keeps the familiar timeline of
**Initial Message → Suggestions → Final Message** whenever the behavior allows
messages to be posted.

**Example (Manual cadence)**\
PR opened → no message yet\
`@kody start-review` → start message → suggestions → end message

## Dynamic Context

You can enhance your custom messages with dynamic context using the **Add Context** button. This allows you to include:

### changedFiles

A summary of changed files, showing additions and deletions per file. This provides a detailed breakdown of what was modified in the pull request.

### changedSummary

A comprehensive summary of all changes in the pull request, giving an overview of the entire modification scope.

### reviewOptions

A reflection of the team's configured review settings, showing which analysis types are enabled or disabled for the review.

### reviewCadence

Provides the exact follow-up review policy so authors know what happens after
the first automated review:

* **Automatic**: Kody re-reviews every push as soon as it lands.
* **Auto-pause**: Kody re-reviews pushes automatically, but if it detects a
  "push burst" (for example, 3 pushes within 15 minutes, based on your
  thresholds) it pauses follow-up reviews until you resume them. The cadence
  context includes the push and time limits so the team knows when the pause can
  be triggered.
* **Manual**: Kody waits for someone to run `@kody start-review` before doing
  another pass.

### reviewScope

Shows which configuration level — global, repository, or directory — was used to
review this pull request, so authors know which settings applied.

### agentPrompt

<Note>
  **End review message only.** It bundles the review's line-comment suggestions,
  which don't exist until the review has run — so it isn't offered on the start
  message.
</Note>

Bundles every suggestion from the review into a single, copy‑paste prompt block
(rendered as a collapsible **Open Agent Prompt**). Paste it into your coding
agent to apply all of the review's fixes at once.

<Info>
  These context variables will be automatically populated with the actual data
  from your pull request when Kody sends the message.
</Info>

<Note>
  You can always revert to the default behavior by disabling both custom
  messages or clearing the message content.
</Note>


# Custom Prompts
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/custom_prompts

Customize Kody's review prompts for each category and how suggestions are written to match your team's needs

Custom Prompts give you complete control over how Kody analyzes your code and communicates findings. Tailor what the AI looks for in each review category and how it presents suggestions to match your team's standards and communication style.

<Card title="Access Custom Prompts Settings" icon="gear" href="https://app.kodus.io/settings/code-review/global/custom-prompts">
  Configure your custom prompts for all repositories in your organization
</Card>

## Why Use Custom Prompts?

<CardGroup>
  <Card title="Team-Specific Standards" icon="users">
    Align Kody's reviews with your team's unique coding standards, architectural patterns, and best practices
  </Card>

  <Card title="Model Optimization" icon="brain">
    Craft prompts optimized for your specific AI model's strengths when using BYOK
  </Card>

  <Card title="Focus Control" icon="bullseye">
    Direct Kody's attention to issues that matter most to your project and reduce noise
  </Card>

  <Card title="Communication Style" icon="comments">
    Customize how Kody presents suggestions - detailed for critical issues or concise for minor ones
  </Card>
</CardGroup>

## How Custom Prompts Work

Custom Prompts operate at two levels:

### Category Prompts

Define what Kody looks for in each review category:

<Tabs>
  <Tab title="Bug">
    **Focus:** Code correctness and execution issues

    Default coverage:

    * Execution breaks (unhandled exceptions)
    * Wrong results (incorrect output)
    * Resource leaks (files, connections, memory)
    * State corruption (invalid object/data states)
    * Logic errors (incorrect control flow)
    * Race conditions (concurrent access issues)

    **Max length:** 2000 characters
  </Tab>

  <Tab title="Security">
    **Focus:** Security vulnerabilities and data protection

    Default coverage:

    * Injection vulnerabilities (SQL/NoSQL/command/LDAP)
    * Auth/AuthN flaws (missing checks, privilege escalation)
    * Data exposure (sensitive data in logs/responses)
    * Crypto issues (weak algorithms, hardcoded keys)
    * Input validation gaps (missing sanitization/bounds checks)
    * Session management (predictable tokens, missing expiration)

    **Max length:** 2000 characters
  </Tab>

  <Tab title="Performance">
    **Focus:** Speed, efficiency, and resource optimization

    Default coverage:

    * Algorithm complexity (O(n²) when O(n) possible)
    * Redundant operations (duplicate calculations, unnecessary loops)
    * Memory waste (large allocations, leaks)
    * Blocking operations (synchronous I/O in critical paths)
    * Database inefficiency (N+1, missing indexes, full scans)
    * Cache misses (not leveraging available caching)

    **Max length:** 2000 characters
  </Tab>
</Tabs>

### Suggestion Prompts

Control how Kody communicates each individual suggestion. This customizes the message format and tone that appears in PR comments, like:

```
The new file 'create-or-update-issues-parameter.dto.ts' does not follow 
the company's naming convention. According to the Kody Rules, all new files 
must use camelCase. Please rename the file to 'createOrUpdateIssuesParameter.dto.ts' 
to adhere to the standard.
```

Your custom prompt instructs Kody on how to write suggestion messages. The prompt receives context about the severity level, problem description, suggested code, and whether it's a Kody Rules violation. Kody uses this context along with your prompt to generate appropriate messages for each suggestion.

You can customize the tone, level of detail, and communication style based on your team's needs - from detailed explanations for critical issues to concise feedback for minor ones.

## External References

All custom prompts—Category, Suggestion, and PR Summary—support referencing real files from the codebases Kody can access. When you save an update, Kody automatically detects external references and resolves them for future reviews.

* Use `@file:path/to/file.ts` to point at files in the repository you're editing; Kody will try to locate the path locally first.
* Include `@repo:org/project` when referencing files from another repository or when editing prompts at the global level.
* Prefer precise blob-style paths rather than placeholders so the model can reliably find the right file.
* After saving, Kody processes the references in the background. Check the status indicator beside the prompt editor to confirm when resolution completes.

## Best Practices

### Be Specific to Your Context

<CardGroup>
  <Card title="Do: Context-Specific" icon="check">
    ```
    Bug category prompt:
    Focus on null pointer exceptions in our 
    Java services, unclosed database connections 
    in DAO layer, and race conditions in our 
    async event handlers. Check for proper 
    resource cleanup in try-finally blocks.
    ```
  </Card>

  <Card title="Don't: Too Generic" icon="xmark">
    ```
    Bug category prompt:
    Look for bugs in the code.
    Check for issues and problems.
    ```
  </Card>
</CardGroup>

### Avoid Redundancy Between Prompts

Each category should have a distinct focus. Don't repeat the same instructions across different prompts.

<Accordion title="Example: Proper Separation">
  **Bug Category:**
  Focus on execution correctness, null pointer exceptions, and resource cleanup in our Java services.

  **Security Category:**
  Focus on SQL injection, XSS, and CSRF in our API endpoints. Verify input sanitization and parameterized queries.

  **Performance Category:**
  Focus on N+1 queries, missing database indexes, and inefficient loops in data processing.

  **Result:** Each prompt has a clear, non-overlapping focus.
</Accordion>

<Accordion title="Anti-pattern: Redundant Prompts">
  **Bug Category:**
  Check for null pointers, SQL injection, and slow queries.

  **Security Category:**
  Look for SQL injection, null pointers, and performance issues.

  **Performance Category:**
  Find slow queries, null pointers, and security vulnerabilities.

  **Problem:** All prompts overlap, confusing the model and reducing review quality.
</Accordion>

### Be Careful with Examples

<Tabs>
  <Tab title="Good: Pattern Description">
    ```
    Detect SQL injection in database queries:
    - Raw string concatenation in SQL statements
    - User input directly in query strings
    - Missing parameterized queries or ORMs
    - Dynamic query construction without sanitization
    ```

    This describes the pattern broadly, catching multiple variations.
  </Tab>

  <Tab title="Risky: Specific Example">
    ```
    Detect SQL injection like this:
    query = "SELECT * FROM users WHERE id = " + userId
    ```

    The model might only flag this exact pattern and miss:

    * Template literals: `SELECT * FROM users WHERE id = ${userId}`
    * String formatting: `f"SELECT * FROM users WHERE id = {userId}"`
    * Other SQL injection vectors
  </Tab>
</Tabs>

### Keep Suggestions Scannable

For suggestion prompts, make messages easy to scan since developers review many at once:

<Tabs>
  <Tab title="Good: Clear Structure">
    ```
    Write suggestions with clear structure. For critical issues, 
    start with the 🚨 emoji, state the problem, then show "Fix:" 
    followed by the code. For other severities, keep it simple - 
    just the problem and the suggested code.

    Put important information first so developers can quickly 
    understand what needs to be done.
    ```

    Clear hierarchy, important information first
  </Tab>

  <Tab title="Bad: Wall of Text">
    ```
    Explain the problem and why it's important because it could 
    cause issues in production and developers should fix it by 
    applying the suggested code changes that will resolve the issue.
    ```

    Hard to scan, buries the action
  </Tab>
</Tabs>

### Use Context Meaningfully

Only differentiate suggestion formats when there's a real reason:

<Tabs>
  <Tab title="Good: Meaningful Difference">
    ```
    For Kody Rules violations, use a stricter tone: 
    "**Team Standard**: [problem]. Required: [code]"

    For standard suggestions, use a friendlier tone:
    "[problem]. Suggested: [code]"

    The difference in language makes the requirement level clear.
    ```

    Clear distinction: rules are requirements, suggestions are recommendations
  </Tab>

  <Tab title="Bad: Superficial Label">
    ```
    For Kody Rules, add "[RULE]" prefix before the problem.
    For suggestions, add "[SUGGESTION]" prefix before the problem.
    Otherwise format them the same way.
    ```

    Just adding labels doesn't add value
  </Tab>
</Tabs>

## Use Cases

<AccordionGroup>
  <Accordion title="Industry-Specific Requirements">
    **Scenario:** Healthcare application with HIPAA compliance requirements

    **Custom Security Prompt:**

    ```
    Focus on HIPAA compliance in data handling:
    - PHI (Protected Health Information) exposure in logs or errors
    - Missing encryption for PHI at rest and in transit
    - Inadequate access controls for patient data
    - Audit logging gaps for PHI access
    - Data retention violations
    - Missing patient consent verification
    ```

    **Benefit:** Kody catches compliance-specific issues that generic security reviews might miss.
  </Accordion>

  <Accordion title="Tech Stack Optimization">
    **Scenario:** React/Node.js application with specific patterns

    **Custom Bug Prompt:**

    ```
    Focus on React and Node.js common pitfalls:
    - Missing dependency arrays in useEffect/useMemo
    - Unhandled promise rejections in async handlers
    - Memory leaks from event listener cleanup
    - Race conditions in state updates
    - Missing error boundaries
    - Uncaught exceptions in Express middleware
    ```

    **Benefit:** Reviews are laser-focused on your stack's specific gotchas.
  </Accordion>

  <Accordion title="Model-Specific Tuning">
    **Scenario:** Using Gemini 2.5 Flash via BYOK for cost optimization

    **Custom Performance Prompt:**

    ```
    Analyze algorithmic efficiency and resource usage.
    List specific issues in this format:
    1. Issue type and location
    2. Current complexity
    3. Optimization suggestion
    4. Expected improvement

    Prioritize: database queries, loops, memory allocations.
    ```

    **Benefit:** Structured output format that Gemini handles exceptionally well, improving review quality.
  </Accordion>

  <Accordion title="Severity-Based Communication">
    **Scenario:** Want detailed explanations for critical issues but concise feedback for minor ones

    **Custom Suggestion Prompt:**

    ```
    When writing suggestions, adjust the level of detail based on severity:

    For Critical issues: Start with "🚨 CRITICAL:" followed by the problem. 
    Add a line explaining "This requires immediate attention." Then provide 
    the fix with "Fix:" prefix.

    For High severity: Use "⚠️" emoji, state the problem, then show the fix 
    with "Fix:" prefix.

    For Medium and Low: Keep it brief - just state the problem and show the 
    suggested code directly without extra explanation.
    ```

    **Benefit:** Critical issues get extra context while minor issues stay brief, improving review efficiency.
  </Accordion>

  <Accordion title="Direct and Concise Feedback">
    **Scenario:** Team prefers minimal, actionable feedback

    **Custom Suggestion Prompt:**

    ```
    Be direct and concise. State the problem in one sentence, then immediately 
    show the fix with "Fix:" prefix. No additional context or explanations.
    ```

    **Benefit:** Every suggestion is short and to-the-point without extra context.
  </Accordion>

  <Accordion title="Educational Suggestions">
    **Scenario:** Junior developers benefit from detailed explanations

    **Custom Suggestion Prompt:**

    ```
    Structure suggestions in three parts:

    1. **Issue:** State the problem clearly
    2. **Why this matters:** Explain the impact based on severity:
       - Critical: Could cause production failures or security vulnerabilities
       - High: May lead to bugs or performance problems  
       - Medium/Low: Improves code quality and maintainability
    3. **Fix:** Show the recommended code change

    Make explanations educational and help developers learn why it matters.
    ```

    **Benefit:** Every suggestion includes educational context about importance.
  </Accordion>

  <Accordion title="Different Tone for Rules vs Suggestions">
    **Scenario:** Kody Rules are strict requirements, suggestions are recommendations

    **Custom Suggestion Prompt:**

    ```
    Use different tones based on the type:

    For Kody Rules violations:
    - Start with "**Team Standard Violation**" in bold
    - State the problem
    - Add "This violates documented team standards."
    - Show "Required fix:" followed by the code

    For standard suggestions:
    - State the problem directly
    - Show "Suggested improvement:" followed by the code
    - Use a friendly, recommendatory tone
    ```

    **Benefit:** Clear distinction between mandatory rules and optional suggestions.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Reviews Are Too Noisy">
    **Symptoms:** Too many low-value suggestions after customization

    **Solutions:**

    * Make prompts more specific and focused
    * Add exclusions for patterns you want to ignore
    * Raise minimum severity threshold in [Suggestion Control](/how_to_use/en/code_review/configs/suggestion_control)
    * Check for redundancy between category prompts
  </Accordion>

  <Accordion title="Missing Expected Issues">
    **Symptoms:** Kody doesn't catch issues it should

    **Solutions:**

    * Review your prompt for being too narrow or example-specific
    * Check if the issue falls under a category you didn't customize
    * Try resetting to default to see if the issue is caught
    * Consider if the issue might be classified under a different severity
  </Accordion>

  <Accordion title="Inconsistent Results">
    **Symptoms:** Same type of issue flagged sometimes but not always

    **Solutions:**

    * Ensure prompts are clear and unambiguous
    * Remove conflicting instructions across different prompts
    * Check if you're using examples that are too specific
    * Consider if different models in primary/fallback have different capabilities
  </Accordion>

  <Accordion title="Not Sure What to Customize">
    **Symptoms:** Want to use custom prompts but unsure where to start

    **Solutions:**

    * Start by running default reviews for a week
    * Note patterns in false positives or missed issues
    * Customize only the specific prompt related to those patterns
    * Keep other prompts at default until you see a clear need
  </Accordion>
</AccordionGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Do custom prompts apply to all repositories?">
    It depends on where you set them:

    * **Global settings:** Apply to all repositories in your organization
    * **Per-repository settings:** Override global settings for that specific repo

    This lets you have organization-wide standards with repository-specific overrides when needed.
  </Accordion>

  <Accordion title="Can I see the default prompts before customizing?">
    Yes. Click into any prompt in settings to view default content.
  </Accordion>

  <Accordion title="What happens to existing PRs when I change prompts?">
    Changes only affect new reviews. Re-run with `@kody start-review` to apply new prompts to existing PRs.
  </Accordion>

  <Accordion title="Can I customize prompts with kodus-config.yml?">
    No. Custom prompts are web-only to ensure intentional changes. Other settings (ignored paths, branches) can use `kodus-config.yml`.
  </Accordion>

  <Accordion title="Should I customize all prompts or just some?">
    Only customize prompts with clear, specific needs. Keep others at default to benefit from our improvements. Start with 1-2 prompts.
  </Accordion>

  <Accordion title="How do custom prompts work with BYOK?">
    Works seamlessly. Tailor prompts to your model's strengths. Both primary and fallback use the same custom prompts.
  </Accordion>

  <Accordion title="What's the difference between Category prompts and Suggestion prompts?">
    **Category prompts** control what Kody analyzes in each review category. **Suggestion prompts** control how Kody presents findings to your team. You can customize both independently.
  </Accordion>

  <Accordion title="Can I use markdown in suggestion prompts?">
    Yes. Suggestion prompts support standard markdown formatting including bold, italic, code blocks, and links.
  </Accordion>

  <Accordion title="What happens if my suggestion template has syntax errors?">
    Kody will fall back to the default suggestion format and notify you of the error in settings.
  </Accordion>

  <Accordion title="Do suggestion prompts work for both Kody Rules and standard suggestions?">
    Yes. Use the `isKodyRule` variable to create different messages for rules vs suggestions in the same prompt.
  </Accordion>
</AccordionGroup>


# Directory-Level Settings
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/directory_level

Target specific folders in your repo with custom code review settings. Ideal for monorepos.

## Overview

Apply custom code review settings to specific folders in your repository. Ideal for monorepos where different areas have different standards or ownership.

Kody selects a single config per PR: **Directory** → **Repository** → **Global**

<Note>
  Learn how settings flow between levels in <a href="/how_to_use/en/code_review/configs/inheritance_overrides">Config Inheritance & Overrides</a>.
</Note>

## How it works

* Configure any folder at any depth (e.g., `api/src/services`)
* Configure as many folders as you want
* **No overlapping**: if you configure `api/src/services`, you cannot also configure `api/src/services/users`

### Selection rules

* **One configured directory touched**: Uses that directory's config
* **No configured directories touched**: Uses repository config (or global if no repo config)
* **Two or more configured directories touched**: Escalates to repository config (or global if no repo config)

<Note>
  Kody uses one config per PR to keep reviews predictable. Mixing configs causes conflicts.
</Note>

## Examples

<Tabs>
  <Tab title="Single configured directory">
    You configured `src/microservice-alpha`. PR changes files in `src/microservice-alpha` and unconfigured folders.

    Uses **microservice-alpha** config.
  </Tab>

  <Tab title="No configured directories">
    PR only touches directories without specific configs.

    Uses **repository** config (or **global** if no repo config).
  </Tab>

  <Tab title="Multiple configured directories">
    You configured `src/microservice-alpha` and `src/microservice-beta`. PR touches both.

    Escalates to **repository** config (or **global** if no repo config).
  </Tab>
</Tabs>

## Setup

1. Open your repository's Code Review settings
2. Add directory entries and assign configurations
3. Save changes

If you also use `kodus-config.yml`, it overrides web settings (see Config Priority in General settings).


# General
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/general



## Core Settings

<Note>
  Kodus has three config levels: Global, Repository, and Directory. Learn how they work in <a href="/how_to_use/en/code_review/configs/inheritance_overrides">Config Inheritance & Overrides</a>.
</Note>

### Config Priority

`kodus-config.yml` in your repo root overrides web settings. No setup needed—just commit the file.

<Accordion title="Sample kodus-config.yml">
  ```yaml theme={null}
  version: '1.2'
  summary:
    generatePRSummary: true
    customInstructions: ''
    behaviourForExistingDescription: concatenate
  ignorePaths:
    - yarn.lock
    - package-lock.json
    - package.json
    - .env
  baseBranches: []
  reviewOptions:
    security: true
    code_style: true
    kody_rules: true
    refactoring: true
    error_handling: true
    maintainability: true
    potential_issues: true
    documentation_and_comments: true
    performance_and_optimization: true
    business_logic: true
  suggestionControl:
    groupingMode: full
    limitationType: pr
    maxSuggestions: 9
    severityLevelFilter: medium
  ignoredTitleKeywords: []
  automatedReviewActive: true
  pullRequestApprovalActive: false
  isRequestChangesActive: false
  kodyKnowledgeApproval:
      enabled: false
  ```
</Accordion>

## Review Behavior

### Automated Review

Kody can review PRs automatically when opened, or only when you comment `@kody start-review`.

<Info>
  This affects the **initial review** only. For subsequent commits, see Review Cadence below.
</Info>

#### Review Cadence

How Kody handles reviews on subsequent commits:

<Tabs>
  <Tab title="Automatic">
    Review every new push. Continuous feedback on all changes.
  </Tab>

  <Tab title="Auto-pause">
    Pause reviews during rapid consecutive pushes (e.g., 3 pushes in 15 minutes). Prevents spam during active coding.

    Defaults: 3 pushes / 15 minutes
  </Tab>

  <Tab title="Manual">
    Only run follow-up reviews when you comment `@kody start-review`.
  </Tab>
</Tabs>

### PR Workflow

#### Auto-approve PRs

Kody approves PRs when no issues are found.

**Platforms:** GitHub, GitLab, Bitbucket

#### Request Changes

Kody requests changes when finding critical issues.

**Platforms:** GitHub, Bitbucket

### Skip Conditions

**Ignored Files:** Use glob patterns (e.g., `**/*.js`), one per line. Default: `yarn.lock`, `package-lock.json`, `package.json`, `.env`

**Ignored Titles:** Skip PRs with specific keywords (case-insensitive, max 100 chars)

**Base Branches:** Additional branches to review besides default (dev, release, master)

## Analysis Types

### Code Quality

* Security: SQL injection, XSS, security threats
* Performance: Caching, query optimization, speed improvements
* Error Handling: Exception management, error messages
* Potential Issues: Null pointers, resource leaks, infinite loops

### Code Structure

* Refactoring: Code organization, function size, duplication
* Maintainability: Future-proof code patterns
* Code Style: Consistent formatting and standards
* Documentation: Clear comments and API docs
* Kody Rules: Custom rule enforcement
* Business Logic: Validates PR implementation against task requirements and acceptance criteria


# Config Inheritance & Overrides
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/inheritance_overrides

How Global → Repository → Directory settings inherit, override, and propagate.

## Overview

Kodus configurations work across three levels: **Global**, **Repository**, and **Directory**.

<Note>
  The most specific level wins: Directory > Repository > Global
</Note>

```
Global
 ├─ Repository A
 │   ├─ Directory A1
 │   └─ Directory A2
 └─ Repository B
```

## How It Works

Fields inherit from the parent level by default. When you change a field at Global, all repositories and directories without an override update automatically.

<Info>
  Overrides are per field. You can override one field and inherit everything else.
</Info>

Once overridden, a field stops following the parent and uses its local value instead.

## Examples

<Tabs>
  <Tab title="Global change propagates">
    You change **Severity thresholds** at Global.

    All repositories and directories without an override update automatically. Overridden ones stay unchanged.
  </Tab>

  <Tab title="Repository override">
    In Repository X, you override **Review start message**.

    Directories within Repository X now inherit from Repository X (unless they have their own override).
  </Tab>

  <Tab title="Return to inheritance">
    In Repository Y, you remove the override for **Active categories**.

    The field follows Global again and receives future Global changes.
  </Tab>
</Tabs>

## Best Practices

* Start at Global with strong defaults
* Only override when you have a specific need for that repo/directory

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="If I change something at Global, will it break my local adjustments?">
    No. Local overrides stay unchanged.
  </Accordion>

  <Accordion title="Can I override just one field and inherit the rest?">
    Yes. Overrides are per field.
  </Accordion>

  <Accordion title="Does a Directory inherit from Repository or Global?">
    From Repository first. If Repository has no override for that field, it inherits from Global.
  </Accordion>
</AccordionGroup>


# Overview
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/kody_rules

Kody Rules are customizable guidelines your team sets up to automatically enforce code quality, consistency, security, and maintainability.

<iframe title="YouTube video player" />

## Two Types in the Kody Rules UI

Kody Rules are organized into two categories, managed through a tabbed interface in your settings:

<Tabs>
  <Tab title="Review Rules">
    Traditional code review rules that run during the dedicated code review stage. They analyze file diffs and PR metadata to enforce coding standards.

    * Applied at **File-Level** or **Pull Request-Level**
    * Support variables, file references, and MCP functions
    * Triggered during automated code reviews
  </Tab>

  <Tab title="Memories">
    Persistent contextual instructions that are injected across all prompts and conversations. Memories allow Kody to learn and retain how your codebase works so future reviews and suggestions are more relevant.

    * Injected as **high-priority context** in code reviews, cross-file analysis, and conversations
    * Created via **conversation with Kody** or **manually in the UI**
    * Scoped to **directory**, **repository**, or **organization** level
    * Support approval workflows for AI-generated memories
  </Tab>
</Tabs>

## Review Rules

### Create Custom Rules

Define rules based on your team's exact needs. Review Rules can be applied at two different levels: **[File-Level](#file-level-rules)** and **[Pull Request-Level](#pull-request-level-rules)**. Both levels support variables, file references, and MCP functions to build powerful, context-aware rules.

#### Variables, File References & MCP Functions

Rules can access rich context through variables, file references, and MCP functions. Here's what's available:

**Variables:**

Variables represent the context data available during rule execution. Understanding what's available helps you compose better rules by combining variables with MCP functions and file references.

* **File-Level**:
  * `fileDiff` - The specific changes made to the individual file being analyzed

* **PR-Level**:
  * `pr_title` - The title of the Pull Request
  * `pr_description` - The description/body of the Pull Request
  * `pr_total_additions` - Total number of lines added
  * `pr_total_deletions` - Total number of lines deleted
  * `pr_total_files` - Total number of files changed
  * `pr_total_lines_changed` - Total number of lines modified
  * `pr_files_diff` - Complete diff of all changes across the entire Pull Request
  * `pr_tags` - Tags associated with the Pull Request
  * `pr_author` - Author of the Pull Request
  * `pr_number` - Pull Request number

Use these variables in your rule instructions to access context data, and combine them with MCP functions to fetch additional information or perform dynamic analysis.

**File References:**

Reference files directly in your rule instructions to compare code, validate patterns, enforce consistency, and leverage existing templates or standards.

* **`@file:path/to/file.ts`** - Reference files in the same repository where you're editing the rule
  * Use when referencing templates, examples, or configuration files within your current repository
  * Example: `@file:src/services/userService.ts`

* **`@repo:org/project`** - Reference files in another repository or when configuring rules outside a repo context
  * Use when enforcing consistency across multiple repositories or referencing shared standards
  * Example: `@repo:team/api-standards`

**How File References Work:**

* Kody identifies file references automatically when you save a rule
* References are resolved in the background—watch the status indicator next to the editor to confirm completion
* Use accurate blob-style paths (e.g., `src/utils/helpers.ts`) instead of placeholders
* File contents are injected into the rule context, allowing Kody to compare, validate, or enforce patterns
* Works in both File-Level and Pull Request-Level rules

**MCP Functions:**

Access MCP (Model Context Protocol) functions through the `@MCP` dropdown in the rule editor to fetch additional data and context. You can use any MCP tool or server connected in your workspace's [Plugins](/how_to_use/en/code_review/plugins) page.

Available functions include:

* Repository operations: List repositories, get repository files, content, and languages
* PR analysis: Get pull request details, list commits, analyze PR file content
* File content retrieval: Fetch file contents and diffs
* Cross-file validation: Perform advanced analysis across multiple files
* Custom integrations: Any MCP server you've connected as a plugin (Jira, custom tools, etc.)

MCP functions execute during rule evaluation, enabling rules that adapt to current repository state and fetch real-time data.

**Best Practices:**

* Use specific file paths rather than generic placeholders
* Reference stable files that represent your team's standards
* Test file references exist before saving rules to avoid resolution errors
* Combine variables, file references, and MCP functions for comprehensive validation

#### File-Level Rules

Analyze individual files to catch issues within specific code files.

**Available Context:**

See the [Variables, File References & MCP Functions](#variables-file-references--mcp-functions) section above for details. Available at this level: `fileDiff` variable, file references (`@file`, `@repo`), and MCP functions.

**What You Can Do:**

* Compare against reference files using `@file` or `@repo`
* Fetch related files or repository data using MCP functions
* Combine variables, file references, and MCP functions to validate patterns, check consistency, or enforce architectural rules

**How to Configure:**

* **Rule name**: Clearly define the rule purpose
* **File Paths**: Limit rules to specific files or directories using glob patterns
* **Severity**: Set to Critical, High, Medium, or Low
* **Detailed Instructions**: Use `fileDiff`, reference files with `@file`/`@repo`, and call MCP functions to compose powerful rules with rich context

**Configuration Example:**

📋 **Rule**: "Avoid equality operators (==, !=) in loop termination conditions."

📁 **Path**: `src/**/*.ts`

⚠️ **Severity**: Critical

📝 **Instructions**: "Using equality operators (== or !=) can cause infinite loops if exact values aren't matched."

**❌ Bad Example:**

```typescript theme={null}
// Risk of infinite loop if increment is not exactly 1
for (let i = 0; i != 10; i += 2) {
  console.log(i); // Will print 0, 2, 4, 6, 8, 10, 12, 14... forever
}

// Risk if array is modified during iteration
let items = [1, 2, 3, 4, 5];
for (let i = 0; i != items.length; i++) {
  if (items[i] === 3) {
    items.push(6); // Modifies length, can cause infinite loop
  }
}
```

**✅ Good Example:**

```typescript theme={null}
// Safe: loop will always terminate
for (let i = 0; i < 10; i += 2) {
  console.log(i); // Will print 0, 2, 4, 6, 8 and stop
}

// Safe even if array is modified
let items = [1, 2, 3, 4, 5];
for (let i = 0; i < items.length; i++) {
  if (items[i] === 3) {
    items.push(6); // Loop will still terminate safely
  }
}
```

#### Pull Request-Level Rules

Analyze the entire Pull Request for cross-file validation and PR-specific requirements.

**Available Context:**

See the [Variables, File References & MCP Functions](#variables-file-references--mcp-functions) section above for details. Available at this level: PR variables (`pr_title`, `pr_description`, `pr_files_diff`, etc.), file references (`@file`, `@repo`), and MCP functions.

**What You Can Do:**

* Validate PR metadata using variables like `pr_title`, `pr_description`, `pr_author`
* Reference configuration files or templates using `@file` or `@repo`
* Fetch additional context using MCP functions (e.g., check if related files exist, validate against repository structure)
* Combine PR variables, file references, and MCP functions to create comprehensive validation rules

**How to Configure:**

The creation process is identical to file-level rules, but you must select the "Pull-request" scope. This broader context enables analysis of cross-file dependencies and overall PR quality.

**Examples:**

* Every service file must have a corresponding test file
* PR description must be complete, clearly stating what was added or removed
* When a new route is created in a controller, it must be registered in routes.json
* Use `pr_total_lines_changed` to flag PRs exceeding size limits
* Combine `pr_files_diff` with MCP functions to validate cross-file dependencies
* Reference `@file:routes.json` to ensure new routes are registered
* Use MCP functions to check if test files exist for modified service files

#### Composing Powerful Rules

Combine variables, MCP functions, and file references to create sophisticated rules with rich context. Here's what's available at each level:

**File-Level Composition:**

* Use `fileDiff` to analyze the specific changes in a file
* Reference related files with `@file:path/to/template.ts` to compare against patterns
* Call MCP functions to fetch repository data or check if related files exist
* **Example**: "Analyze `fileDiff` and ensure it follows the pattern in `@file:src/utils/example.ts`. Use MCP to verify related test files exist."

**PR-Level Composition:**

* Use PR variables (`pr_title`, `pr_description`, `pr_files_diff`, etc.) to validate PR metadata and size
* Reference configuration files with `@file:config.json` or `@repo:org/shared-config` to enforce consistency
* Call MCP functions to perform cross-file validation, check repository structure, or fetch commit history
* **Example**: "If `pr_files_diff` contains new routes, verify they're registered in `@file:routes.json`. Use MCP to check if corresponding test files exist for all modified service files."

**Cross-Repository Validation:**

* Reference files from other repositories with `@repo:org/project` to maintain consistency across projects
* Combine with MCP functions to validate against shared standards or templates
* **Example**: "Ensure API endpoints follow the pattern defined in `@repo:org/api-standards`. Use MCP to fetch the latest standards document."

**Dynamic Analysis:**

* MCP functions execute during rule evaluation, enabling rules that adapt to current repository state
* Fetch real-time data about files, commits, or repository structure
* **Example**: "Use MCP to check the current repository structure and ensure new files follow the existing directory patterns."

This composition enables rules that understand not just code changes, but the broader context of your codebase, team practices, and project requirements.

### Import from Rules Library

Leverage proven best practices instantly:

* Navigate to Discovery Rules in your Kodus dashboard.
* Filter rules by severity, language, or tags.
* Import and activate rules with a single click.

**Examples:**

* Security: "Disallow use of insecure MD5 hashing."
* Maintainability: "Limit React components to less than 150 lines."

## Memories

Memories are persistent contextual instructions that Kody learns from your team's conversations and coding practices. Unlike Review Rules that run during code review, Memories are injected across all prompts and conversations to provide continuous, high-priority context and improve future suggestions.

### How Memories Work

* **Injected everywhere**: Memories are included in code review analysis (cross-file, safeguards, PR-level rules) and in conversational interactions
* **High-priority context**: Memories are treated as high-priority guidance by the AI, ensuring your team's conventions are consistently applied
* **Better future suggestions**: Memories help Kody avoid repeating the same mistaken assumptions about your repo
* **Intelligent deduplication**: When a new memory is created, Kody uses an LLM-based resolution mechanism to determine whether to create it, skip it (if duplicate), or update an existing memory

### Creating Memories

There are two ways to create memories:

#### Via Conversation

The most natural way to create memories is through conversation with Kody in your PR comments. Kody detects both explicit and implicit intents to save conventions:

**Explicit** — directly asking Kody to remember:

```
@kody remember: this repo mirrors a third-party API, so some payload fields intentionally stay snake_case.
```

```
@kody please remember: this service follows hexagonal architecture and keeps adapters at the edge.
```

**Implicit** — stating a preference or convention that Kody captures:

```
@kody this repo mirrors a third-party API, so some payload fields intentionally stay snake_case.
```

```
@kody in this service, tests usually live next to implementation files rather than in a central test folder.
```

```
@kody the billing module is mid-migration, so prefer incremental fixes over broad refactors.
```

<Info>
  Kody will NOT create memories for transient instructions (e.g., "fix this now"), debugging chatter, questions, vague statements, or requests explicitly scoped to a single task or PR.
</Info>

When a memory is created or updated, Kody responds with a confirmation and provides a **direct link** to view the memory in the UI.

#### Via the UI

You can also create memories manually:

1. Go to **Code Review Settings** → **Repository** → **Kody Rules**
2. Switch to the **Memories** tab
3. Click **Add Memory** to create a new entry
4. Fill in the memory content and scope

### Memory Scopes

Each memory has a scope that determines where it applies:

| Scope            | Description                                                    | Example                            |
| ---------------- | -------------------------------------------------------------- | ---------------------------------- |
| **Directory**    | Applies to files matching a glob pattern within the repository | `src/components/ui`, `src/**/*.ts` |
| **Repository**   | Applies across the entire repository                           | All files in the repo              |
| **Organization** | Applies across all repositories in the organization            | All repos in the org               |

### LLM-Generated Memories Approval

By default, AI-generated memories are automatically activated. You can require manual approval before they take effect:

1. Go to **Code Review Settings** → **Repository** → **Kody Rules** → **Memories** tab
2. Enable **Kody knowledge approval**

When enabled:

* AI-generated rules and memories enter a **pending state** and are not active until approved
* A notification badge appears showing the pending count
* Click **Pending** to review, approve, discard, or convert pending items
* Both new creations and updates to existing rules/memories go through the approval flow

You can also set this in `kodus-config.yml`:

```yaml theme={null}
kodyKnowledgeApproval:
    enabled: true
```

### Pending Memories Review

The Pending Memories modal shows two categories:

* **New Memories**: AI-generated memories waiting for approval
* **Memory Updates**: Proposed changes to existing memories

For each pending item, you can:

* **Apply**: Activate the memory or apply the update
* **Discard**: Reject the memory or update
* **Convert to Review Rule**: Transform a memory into a standard Review Rule

## Next Steps

<CardGroup>
  <Card title="Sync IDE Rules" icon="window" href="/how_to_use/en/code_review/configs/rules_file_detection">
    Automatically import rules from Cursor, Copilot, Claude and other AI coding tools.
  </Card>

  <Card title="Repository Rules" icon="folder" href="/how_to_use/en/code_review/configs/repository_rules">
    Create rules directly in your repository using structured markdown files.
  </Card>

  <Card title="AI Generation" icon="sparkles" href="/how_to_use/en/code_review/learning/kody_rules_generation">
    Let AI generate rules based on your codebase patterns and past reviews.
  </Card>
</CardGroup>


# PR Summarization
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/pr_summary



Kody's PR Summary feature allows you to automate the creation of concise, actionable pull request descriptions.
This configuration guide explains how to tailor the feature to suit your team’s workflow and preferences.

## Enabling Automatic Summaries

Enable or disable the automatic generation of pull request summaries:

Toggle the Enable Automatic Summary Generation option.

When enabled, Kody will generate summaries for every pull request, ensuring consistency and saving time.

## Behavior for Existing Descriptions

Control how Kody interacts with existing pull request descriptions. You can choose from three modes:

### Replace (Default):

Overwrites any existing description with a newly generated summary from scratch.

### Concatenate:

Appends the generated summary to the end of the existing description.

### Complement:

Combines Kody’s generated insights with the current description, highlighting only what’s new or relevant.

## Custom Instructions

Fine-tune how Kody generates summaries by providing specific guidelines:

Add instructions directly in the Custom Instructions text field.

**Examples:**

* "Focus on security changes and performance impacts."
* "Summarize concisely, highlighting modified public APIs."


# Repository Rules
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/repository_rules

Create custom Kody Rules directly in your repository using markdown files with structured templates.

<Info>
  Repository Rules use the same auto-sync mechanism as IDE rule file detection. Enable "Auto-sync rules from repo" in settings to activate both features. See <a href="/how_to_use/en/code_review/configs/rules_file_detection">Rules File Detection</a> for setup.
</Info>

## How to Use

You can create custom Kody Rules directly in your repository by placing structured markdown files in specific directories. This allows you to version control your rules alongside your code and share them across your team.

<Info>
  Repository rule files are imported **verbatim** — no LLM conversion. The frontmatter is parsed as-is, the markdown body becomes the rule's instructions exactly as you wrote it (identifiers, formatting and wording preserved), and the Bad/Good examples are imported structurally. Each file produces one rule. Files that don't parse as the template (missing frontmatter or `title`) fall back to the LLM importer used for free-form files.
</Info>

### Synchronization

* **Automatic Detection**: Repository rules are automatically detected and synchronized when enabled
* **Manual Sync**: Add `@kody-sync` to any rule file to sync it individually (works even with auto-sync disabled)
* **Web Application**: Synchronized rules appear in your Kodus web application dashboard
* **Real-time Updates**: Changes to rule files are synced when Pull Requests are closed

## File Location

Place your rule files in one of these directories:

* `.kody/rules/**/*.md`
* `rules/**/*.md`

## Rule Template

Each rule file must follow this exact template structure:

```markdown theme={null}
---
title: "<rule name>"
scope: "file"            # "file" or "pull-request"
path: []                 # list of globs. example: ["**/*.ts", "apps/web/**"]
severity_min: "high"     # "low", "medium", "high", "critical"
languages: []            # optional. ex: ["jsts", "go", "php", "ruby", "java", "csharp", "dart", "kotlin", "rust"]
buckets: []              # optional. ex: ["style-conventions", "error-handling", "security"]
uuid: ""                 # optional. use for stable rule ID
enabled: true            # optional
---

## Instructions
Describe what to review and how to decide. Be direct and objective.
- Focus on security, performance and public contract impacts.
- Give team preferences or patterns when applicable.
- If it's a PR rule, explain what to consider in the changeset.

## Examples

### Bad example
\`\`\`lang
// paste here a short counter-example that violates the rule
\`\`\`

### Good example  
\`\`\`lang
// paste here a short example that follows the rule
\`\`\`
```

## Template Fields

### Required Fields

| Field          | Description                                                                          | Values                                      |
| -------------- | ------------------------------------------------------------------------------------ | ------------------------------------------- |
| `title`        | Rule name displayed in the interface                                                 | Any descriptive string                      |
| `scope`        | Rule analysis scope                                                                  | `"file"` or `"pull-request"`                |
| `path`         | File paths where rule applies. The rule fires on files matching **any** of the globs | Array of glob patterns                      |
| `severity_min` | Minimum severity level                                                               | `"low"`, `"medium"`, `"high"`, `"critical"` |

### Optional Fields

| Field                  | Description                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------ |
| `uuid`                 | Stable rule identifier — keeps the same platform rule across renames                 |
| `enabled`              | Set to `false` to skip importing this file (an already-imported rule is not removed) |
| `languages`, `buckets` | Informational metadata                                                               |

## Example Rules

### File-Level Rule Example

```markdown theme={null}
---
title: "Avoid console.log in production code"
scope: "file"
path: ["src/**/*.ts", "src/**/*.tsx"]
severity_min: "medium"
languages: ["jsts"]
buckets: ["style-conventions"]
enabled: true
---

## Instructions
Check for console.log statements in production TypeScript/JavaScript files.
- Console logs should not appear in production code
- Use proper logging libraries instead
- Allow console.log only in development utilities

## Examples

### Bad example
\`\`\`typescript
function processUser(user: User) {
  console.log('Processing user:', user.id);
  return user.process();
}
\`\`\`

### Good example
\`\`\`typescript
import { logger } from './logger';

function processUser(user: User) {
  logger.info('Processing user:', user.id);
  return user.process();
}
\`\`\`
```

### Pull Request-Level Rule Example

```markdown theme={null}
---
title: "New API endpoints must have tests"
scope: "pull-request"
path: ["**/*"]
severity_min: "high"
buckets: ["testing"]
enabled: true
---

## Instructions
When new API endpoints are added, ensure corresponding tests are included in the PR.
- Check for new route definitions in controllers
- Verify test files exist for new endpoints
- Ensure both positive and negative test cases

## Examples

### Bad example
Added new endpoint `/api/users/profile` but no test file included in the PR.

### Good example
Added new endpoint `/api/users/profile` with corresponding test file `tests/api/users/profile.test.ts` that covers success and error cases.
```

## Setup Requirements

To use Repository Rules, you have two options:

### Option 1: Enable Auto-Sync (Recommended)

1. **Enable Rules File Detection**: Toggle "Auto-sync rules from repo" in settings
2. **Create rule files**: Place `.md` files in `.kody/rules/**` or `rules/**` directories
3. **Automatic sync**: All rule files sync when PRs are closed

### Option 2: Manual Sync (Selective)

1. **Create rule files**: Place `.md` files in `.kody/rules/**` or `rules/**` directories
2. **Add sync marker**: Include `@kody-sync` anywhere in the rule file
3. **Commit changes**: Only marked files will sync (auto-sync toggle stays off)

<Tip>
  Repository Rules use the same synchronization mechanism as [Rules File Detection](/how_to_use/en/code_review/configs/rules_file_detection). Use manual sync (`@kody-sync`) to selectively sync specific rules without enabling automatic synchronization.
</Tip>


# Rules File Detection
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/rules_file_detection

Automatically detect and import your existing rule files from popular AI coding tools to enhance Kody's code review capabilities with your team's established coding standards.

Kodus can automatically sync and import your existing IDE rule files to enhance Kody's code review with your team's established coding standards and preferences.

<Frame>
  <img />
</Frame>

## What is Rules File Detection?

Rules File Detection automatically detects and imports configuration files from popular AI coding tools and assistants in your repository. This ensures Kody understands and respects your existing coding standards without requiring manual setup.

## Supported Rule Files

Kodus automatically detects and imports the following rule file patterns:

### Cursor

* `.cursorrules` - Main Cursor rules file (legacy)
* `.cursor/rules/**/*.mdc` - Cursor rules in subdirectories

### GitHub Copilot

* `.github/copilot-instructions.md` - Copilot instructions
* `.github/instructions/**/*.instructions.md` - Detailed instruction files

### Agentic (agents.md convention)

* `AGENTS.md` - The de-facto standard agent guidance file
* `.agents.md` / `.agent.md` - Dotfile variants

### Claude

* `CLAUDE.md` - Claude-specific rules
* `.claude/settings.json` - Claude configuration settings

### Windsurf

* `.windsurfrules` - Windsurf IDE rules

### Sourcegraph Cody

* `.sourcegraph/**/*.rule.md` - Cody rule files

### OpenCode

* `.opencode.json` - OpenCode configuration

### Aider

* `.aider.conf.yml` - Aider configuration
* `.aiderignore` - Aider ignore patterns

### Generic/Internal Rules

* `.rules/**/*` - Generic rules directory
* `.kody/rules/**` and `rules/**/*.md` - Kody-specific rules (see [Repository Rules](/how_to_use/en/code_review/configs/repository_rules) — these are imported verbatim, without LLM rewriting)
* `docs/coding-standards/**/*` - Documentation-based coding standards

### Detection details

* **Nested files are discovered.** Every pattern above is matched at the repository root **and under any subdirectory**. A `services/billing/CLAUDE.md` is imported and automatically scoped to `services/billing/**` — per-directory guidance files (the common monorepo convention) work out of the box.
* **Matching is case-insensitive.** `claude.md` and `CLAUDE.md` are equivalent.
* **`@file` references are followed.** If a rule file references another file with the standard `@` convention (e.g. `@AGENTS.md` inside `CLAUDE.md`), the referenced file's content is fetched and included during import (one level deep, up to 5 references per file, 100KB per referenced file).
* **Multiple globs per rule are supported.** A rule path like `app/**/*.rb,lib/**/*.rb` (or a `path: []` list in [Repository Rules](/how_to_use/en/code_review/configs/repository_rules) frontmatter) applies the rule to files matching **any** of the globs.

## How It Works

### Initial Setup

1. **Enable Auto-sync**: Toggle the "Auto-sync rules from repo" option in your settings
2. **First Sync Modal**: A modal will appear asking if you want to sync for the first time
3. **Repository Scan**: When you confirm, Kodus scans your entire repository for supported rule files
4. **Rule Generation**: An LLM processes the found files and automatically creates corresponding Kody Rules. Exception: `.kody/rules/**` and `rules/**/*.md` template files are imported **verbatim** — no LLM conversion — so your instructions, examples and identifiers are preserved exactly as authored.

Each imported file produces **one Kody Rule**. If a file contains several distinct guidelines, the LLM merges them into a single comprehensive rule — split guidance across multiple files when you want independently manageable rules.

### Ongoing Synchronization

* **Automatic Updates**: Sync happens automatically when a Pull Request is closed
* **File Changes Detected**:
  * **New rule files** → Creates new Kody Rules
  * **Modified rule files** → Updates existing Kody Rules
  * **Deleted rule files** → Removes corresponding Kody Rules

### Manual Sync (Toggle Disabled)

You can sync individual rule files without enabling auto-sync:

1. Add `@kody-sync` anywhere in your rule file
2. Commit the change
3. Kody will sync only that specific file

This lets you selectively sync rules without enabling automatic synchronization for all files.

### Excluding a file (`@kody-ignore`)

To keep a rule/guidance file in your repository but stop Kody from turning it into Kody Rules, add `@kody-ignore` anywhere in the file:

1. Add `@kody-ignore` anywhere in the rule file (case-insensitive)
2. Commit the change

On the next sync Kody will **skip** that file **and remove any Kody Rules previously created from it**. The rules come back automatically if you later remove the `@kody-ignore` marker (or add `@kody-sync`). Use this to keep house-style docs like a `CLAUDE.md` or `AGENTS.md` in the repo without them becoming enforced review rules.

<Warning>
  If you manually edit a Kody Rule that was created from an IDE rule file, your changes will be overwritten the next time the corresponding file is modified and synced.
</Warning>

## Verifying sync and rule evaluation (self-hosted)

On self-hosted deployments the API logs carry grep-able markers for debugging:

* `[kody-rules-sync]` — per-run sync summary: which files were imported, skipped (with the reason) or removed.
* `[kody-rules-eval]` — per-file evaluation trace during a review: exactly which rules (uuid + title) were selected into the prompt for each reviewed file.

```bash theme={null}
docker logs kodus_api 2>&1 | grep "kody-rules-sync"
docker logs kodus_api 2>&1 | grep "kody-rules-eval"
```

If a rule shows as active in the UI but never appears in `[kody-rules-eval]` for the files you expect, check its **Path** glob — a rule only runs on files matching its path.

## Rule limits

Self-hosted instances running **without a valid license** (Community Edition) evaluate at most **10 rules** per review (oldest first). Licensed self-hosted and cloud instances have no such limit. If rules beyond the 10th silently don't fire on an unlicensed instance, this limit is why.


# Rule Inheritance
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/rules_inheritance

How Global → Repository → Directory rules are inherited, and how to stop or exclude inheritance at specific levels.

## Overview

By default, Kody Rules are inherited down the hierarchy:

**Global → Repository → Directory**

The effective rule set at each level is:

* Rules defined at that level, plus
* Rules inherited from the parent level,
* Minus any rules explicitly excluded at that level.

## Default behavior

* Global rules apply to all repositories and directories by default.
* Repository rules inherit all Global rules, plus any rules defined specifically for that repository.
* Directory rules inherit all rules from their repository, plus any rules defined specifically for that directory.

No action is required to enable inheritance — it is automatic.

## Breaking inheritance

There are two ways to stop a rule from being inherited:

### 1) Mark a rule as non‑inheritable (at creation time)

When creating a rule at any level (Global, Repository, or Directory), you can mark it as “non‑inheritable.”

Effect:

* The rule applies only at the level where it was created.
* It does not appear in child levels.

Use this when a rule is intentionally specific to a particular scope and should not flow down the hierarchy.

### 2) Exclude a parent rule from a child level

From a child configuration (Repository or Directory), you can explicitly exclude a rule that would otherwise be inherited from the parent.

Effect:

* The rule is not applied at that exact child level.
* The exclusion does not cascade further — grandchildren still see the parent’s rule unless they also exclude it (or the rule was created as non‑inheritable).

Use this to fine‑tune behavior for a specific repository or directory without affecting other children.

## Examples

### Excluding at the repository level

Suppose a Global rule “Require tests for new endpoints” exists. In repository “shop”, you exclude this rule at the repository level.

Result:

* At the repository level, the rule no longer applies.
* If you have a configured directory inside the same repository (e.g., `apps/api`), that directory still inherits the Global rule and will apply it — unless you also exclude it at the directory level, or the original Global rule was created as non‑inheritable.

### Creating a non‑inheritable Global rule

You create a Global rule and mark it as non‑inheritable.

Result:

* The rule applies only at the Global level.
* Repositories and directories do not inherit it.

## Practical tips

* Keep foundational rules at the Global level so all repos benefit by default.
* Use non‑inheritable rules for highly specific contexts that shouldn’t affect children.
* Use child‑level exclusions to make targeted exceptions without impacting other repos or directories.

## Related

* <a href="/how_to_use/en/code_review/configs/kody_rules">Kody Rules Overview</a>
* <a href="/how_to_use/en/code_review/configs/directory_level">Directory-Level Settings</a>
* <a href="/how_to_use/en/code_review/configs/inheritance_overrides">Config Inheritance & Overrides</a>
* <a href="/how_to_use/en/code_review/configs/centralized_config">Centralized Config</a> — manage rules as YAML files under `.kody-rules/` in a single repository.


# Suggestion Control
Source: https://docs.kodus.io/how_to_use/en/code_review/configs/suggestion_control

Control how Kody provides feedback in your PRs.

## Suggestion Limit

### Limitation Type

* By PR (default): Max suggestions in entire pull request
* By File: Max suggestions per file

### Maximum Suggestions

Set how many suggestions Kody can make:

* Minimum: 6 suggestions
* Default: 10 suggestions
* Set to 0 for unlimited

Pro tip: Start with 10 and adjust based on your team's feedback. Too many suggestions can be overwhelming, too few might miss important issues.

## Severity Levels

### Minimum Severity

Choose which issues Kody will report:

* Low/All: Style issues, minor improvements
* Medium: Common best practices, potential bugs
* High: Significant issues, definite bugs
* Critical: Security issues, major problems

## Suggestion Grouping

### Unified Comments (default)

<img alt="Unified Comments" />

Combines similar issues into one comment, showing all affected files and lines. Great for:

* Large PRs with repeated issues
* Keeping discussions focused
* Reducing notification noise

### Individual Comments

<img alt="Individual Comments" />

Separate comment for each issue. Better when:

* You need direct links to each location
* Team prefers focused, line-specific discussions


# Code Review Flow
Source: https://docs.kodus.io/how_to_use/en/code_review/flow



## Overview

Kody reviews your PRs automatically or on demand, adds clear suggestions, and helps your team decide when to merge. Below is the simple, user-facing view of how it works.

Reference: <a href="https://www.figma.com/board/ZZJcIJMJWGuyzRGMh3w5di/Kodus-Code-Review-Flow?node-id=4-274">Figma board</a>

## When Kody Runs

* PR opened
* New commit pushed to the PR (depending on cadence)
* Manual trigger via comment: `@kody start-review`

## When Kody Skips

* No new commits since the last run
* Only merge commits with no effective changes
* All changed files ignored by configured patterns
* PR exceeds the configured file limit
* Invalid or missing configuration

<Note>
  To override a skip and force a fresh pass — for example after "no new commits" — comment `@kody review --force`.
</Note>

## What Kody Does

* Resolves which settings apply (global → repo → directory) and validates them
* Collects the relevant diffs and context for this PR
* Runs PR-level checks (e.g., custom rules and cross-file analysis when enabled)
* Reviews changed files with focus on the diff
* Filters and prioritizes suggestions to reduce noise (relevance, severity, dedupe, safeguards)
* Posts inline comments and, when applicable, a PR-level summary
* Optionally approves or requests changes if those policies are enabled
* Remembers the last analyzed commit to keep follow-ups incremental

## What You Get

* Inline comments with concrete suggestions
* Optional PR-level summary with highlights
* Optional status: approved or changes requested (if enabled)

## Status Reactions

Kody uses emoji reactions to show the live status of your code review directly in your Git provider. No guessing whether she’s working, done, or ran into a problem. She always replaces the previous emoji with the latest status (for example: 🚀 → 🎉, 👀, 👎 or 😕).

<Note>
  Supported on GitHub and GitLab. Azure DevOps and Bitbucket do not support
  reactions yet.
</Note>

### What each emoji means

* 🚀 Processing — Kody is working on your code:
  * Analyzing files
  * Checking rules and policies
  * Generating suggestions
* 🎉 Completed — Review finished:
  * All comments posted
  * Analysis complete
  * You can review the suggestions
* 👀 Skipped — Review was skipped. Common reasons include:
  * No new commits since the last run
  * Only merge commits detected
  * PR/MR exceeds the configured file limit
  * No relevant files to review (ignored patterns)
  * Branch not configured for review
  * PR/MR in draft mode (if configured to skip drafts)
* 👎 No license — The user is not licensed:
  * Kody cannot run without a valid license
  * Ensure the user that opened the PR/MR has a license assigned
  * Optionally, enable [Auto License Assignment](/how_to_use/en/auto_license_assignment) to assign licenses automatically
* 😕 Error — Something went wrong:
  * Temporary technical issue during the review
  * Try again; join our [Discord community](https://discord.gg/TFZBRk9fT6) if it persists

### Where reactions appear

* Automatic review (PR opened or new commit): reaction on the PR/MR description (top of the thread)
* Manual review (comment `@kody start-review`): reaction on your comment where you invoked Kody

### Example scenarios

* New PR (automatic): 🚀 while running → 🎉 when finished
* Manual command: 🚀 on your comment → 🎉 when finished
* No changes since last run: 👀 reaction
* Unlicensed user: 👎 reaction
* Temporary issue: 😕 reaction

### FAQs

**I don't see reactions**

* GitHub/GitLab: ✅ | Azure DevOps/Bitbucket: ❌ (not supported yet)

**Why did the emoji change?**

* Normal—Kody replaces previous status (🚀 → 🎉/👀/😕)

**I saw 👀 but wanted a review**

* Likely skipped: no new commits, merge-only, ignored files, or file limit
* Fix: comment `@kody review --force` — a plain `start-review` will skip again if there are no new commits

**I saw 👎**

* The user that opened the PR/MR is not licensed
* Fix: assign a license or enable [Auto License Assignment](/how_to_use/en/auto_license_assignment)

**I saw 😕**

* Retry with `@kody start-review`. If persists, check [Troubleshooting](/how_to_use/en/code_review/troubleshooting) or [Discord](https://discord.gg/TFZBRk9fT6)

## Settings That Matter

* Automated vs manual reviews and follow-up cadence
* Ignore patterns and base branches in scope
* Custom rules and cross-file analysis
* Suggestion controls: severity filter, grouping, and max suggestions
* File limits and timeouts

<CardGroup>
  <Card title="General Config" icon="sliders" href="/how_to_use/en/code_review/configs/general">
    Configure modes, cadence, branches, and suggestion options
  </Card>

  <Card title="Review Policy" icon="shield-check" href="/how_to_use/en/code_review/policy">
    Understand suggestions vs blocking and when to enable each
  </Card>

  <Card title="Troubleshooting" icon="triangle-exclamation" href="/how_to_use/en/code_review/troubleshooting">
    Fix common issues and learn about limits
  </Card>
</CardGroup>

## Tips

* Keep PRs small—large diffs reduce review quality
* Link specs/tickets in PR description
* Re-run with `@kody start-review` after addressing feedback


# Azure DevOps PAT Token
Source: https://docs.kodus.io/how_to_use/en/code_review/general_config/azure_devops_pat



## Introduction to the PAT

To enable Kody to perform automatic Code Reviews, you need to generate a Personal Access Token (PAT) in Azure DevOps. This token allows Kody to securely access your repositories and conduct code analysis in a controlled way.

## Generating the PAT (Personal Access Token)

You can access the PAT settings directly using this link: [Azure DevOps PATs](https://dev.azure.com/).

Follow these steps to set up the token correctly:

1. **Access Azure DevOps and go to your security settings:**

   * Go to [Azure DevOps](https://dev.azure.com/) and sign in.
   * Click on your profile picture in the top-right corner.
   * Select **"Security"** from the dropdown.

2. **Create a new PAT:**

   * Under the **Personal Access Tokens** section, click on **"New Token"**.

3. **Set up the new token with the following specifications:**

   * **Name:** Choose an easily identifiable name, such as `kody_code_review`.
   * **Organization:** Select your target organization.
   * **Expiration:** Choose an appropriate expiration time (e.g., 90 or 180 days).
   * **Scopes:** Select the following permissions:

     * **Analytics:** Read
     * **Code:** Read & Write
     * **Graph:** Read
     * **Identities and Groups:** Read
     * **Project and Team:** Read
     * **User Profile:** Read

4. **Click Create.**

Copy the generated token and store it securely, as you’ll need it to configure Kody.

<Note>
  Write access to Code is required for Kody to post comments and manage pull request feedback.
</Note>

## Adding the Token to Kody

After generating the token, paste it into the Kody automation setup screen. The configuration modal will open automatically when you attempt to enable the automation.

## Troubleshooting: Kody isn't reviewing PRs in Azure DevOps

If Kody is connected but **nothing happens on new pull requests** — no reactions, no comments, no PRs appearing in the Kodus dashboard — the cause is almost always one of three issues, in order of how often we see them.

### 1. Check the PAT scopes

Open the PAT in Azure DevOps and confirm every scope listed under [Generating the PAT](#set-up-the-new-token-with-the-following-specifications) is enabled. The one most often missed is **Code: Read & Write** — without **Write**, Kody can read your repositories but cannot post review comments, so the reviews "run silently".

If the PAT was created before a scope was added, Azure DevOps won't retroactively add it. Create a new PAT with the full scope list and update it in the Kody automation setup.

### 2. Check the user's project permissions

A PAT inherits the permissions of the Azure DevOps user who created it. If that user does not have access to the target project, repository, or PR workflow, even a correctly-scoped PAT will be silently rejected by Azure.

Verify the PAT owner can, from the web UI:

* Open the repository and view pull requests.
* Post a comment on a pull request.
* See the PR's threads and reactions.

If any of the above fails for the user, Kody won't be able to do it either. Grant the user **Contribute** and **Contribute to pull requests** on the repository before retrying.

### 3. As a last resort: add the user to Project Collection Administrators

Some Azure DevOps organizations enforce stricter org-level policies that block even correctly-permissioned users from posting PR comments via a PAT. If steps 1 and 2 look correct but Kody still doesn't post anything, add the PAT owner to the **Project Collection Administrators** group:

1. Open **Organization Settings** → **Permissions** (left sidebar).
2. Click the **Project Collection Administrators** group.
3. Open the **Members** tab → click **Add**.
4. Add the user that generated the Kodus PAT.

<Warning>
  **Project Collection Administrators is a high-privilege group** — it grants administrative control over the entire Azure DevOps organization. Use this as a diagnostic to confirm the issue is permission-related, and once confirmed, work with your Azure DevOps admin to grant only the specific permissions the PAT owner needs (usually Contribute + Contribute to pull requests on the relevant projects) rather than leaving them as PCA.
</Warning>

Once the permission is in place, Kody should start reacting and posting reviews on the next PR event. No restart is needed.

### Still stuck?

If none of the above resolves the issue, the problem is usually on the webhook side rather than the PAT. See [Creating a Webhook](/how_to_deploy/en/platforms/azure_devops/azdevops_webhook) — particularly the troubleshooting section, which covers the `?token=` signed-URL requirement that only Azure Repos has.


# Bitbucket API Token
Source: https://docs.kodus.io/how_to_use/en/code_review/general_config/bitbucket_pat



## Introduction

To enable Kody to perform automatic code reviews on Bitbucket Cloud, you need to generate an **API Token**. This token allows Kody to access your repositories, pull requests, webhooks, issues, pipelines etc., with the specific permissions listed below.

***

## Generating the API Token in Bitbucket

1. Open the [Atlassian API tokens page](https://id.atlassian.com/manage-profile/security/api-tokens) directly (or, from your Atlassian profile, navigate to **Security → API tokens**).
2. Click **Create API token with scopes**.
3. Give the token a name (for example `kody_code_review`) and set an expiration date.
4. If prompted, select **Bitbucket** as the application.
5. Select all the required scopes (see below).
6. Review your choices, then click **Create token**.
7. **Copy** the token immediately and store it securely — after creation you will not be able to view it again.

***

## Required Scopes for Kody

The token must include **all** of the following scopes for full functionality with Kody:

| Scope                         | Purpose / What it Enables                                                                   |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| `read:user:bitbucket`         | Read basic user or account information.                                                     |
| `read:workspace:bitbucket`    | Read information about the workspace (projects, members, repositories).                     |
| `read:project:bitbucket`      | Read metadata about projects.                                                               |
| `read:repository:bitbucket`   | Read code, branches, source files in repositories.                                          |
| `write:repository:bitbucket`  | Modify repository contents where needed (comments, file updates, etc.).                     |
| `admin:repository:bitbucket`  | Administrative operations on repository: manage webhooks, permissions, repository settings. |
| `read:pullrequest:bitbucket`  | View pull requests, their statuses, comments.                                               |
| `write:pullrequest:bitbucket` | Create or modify pull request comments; approve, decline or merge PRs.                      |
| `read:issue:bitbucket`        | Read issue tracker information.                                                             |
| `read:webhook:bitbucket`      | View existing webhooks and their settings.                                                  |
| `write:webhook:bitbucket`     | Create or update webhooks.                                                                  |
| `read:pipeline:bitbucket`     | Read status/logs of pipelines associated with repositories or PRs.                          |

> ⚠️ Ensure you grant only these necessary permissions; avoid granting more than required to reduce security risk.

***

## Adding the Token to Kody

* Once the token is generated with all the required scopes, paste it into the **Kody integration / automation setup screen** when enabling the Bitbucket integration.
* Make sure the token has `admin:repository:bitbucket` (or equivalent) if Kody needs to configure webhooks or listen for pull request events.

***

## Important Notes

* The token will be **displayed only once** upon creation. Save it securely, because you will **not** be able to view it again.
* Set an **expiry date** if possible, to limit the token’s lifetime.
* If the token is ever compromised, revoke it immediately and create a new one.
* Periodically audit the tokens and their scopes to confirm they are still necessary and valid.
* Check whether your Bitbucket plan / account allows all the above scopes; some scopes (project, workspace, admin) may depend on subscription / permissions.


# Forgejo Access Token
Source: https://docs.kodus.io/how_to_use/en/code_review/general_config/forgejo_pat



<Note>
  Forgejo support is maintained by the community.
</Note>

## Introduction

To enable Kody to perform automatic code reviews on Forgejo, you need to generate an **Access Token**. This token allows Kody to access your repositories, pull requests, webhooks, issues, etc., with the specific permissions listed below.

***

## Generating the Access Token in Forgejo

1. Go to your Forgejo instance and click the avatar icon in the top right corner
2. Select **Settings**
3. Navigate to **Applications**
4. Under **Generate New Token**, give it a name (e.g. `kodus_code_review`)
5. Select the required permissions (see below)
6. Click **Generate Token**
7. **Copy** the token immediately and store it securely — you won't be able to see it again after closing the page

***

## Required Permissions for Kody

The token must include **all** of the following permissions for full functionality with Kody:

| Category       | Level            | Purpose                                                           |
| -------------- | ---------------- | ----------------------------------------------------------------- |
| `repository`   | **Read & Write** | Access code, branches, files, create PR comments, manage webhooks |
| `issue`        | **Read & Write** | View and modify issues, labels, and milestones                    |
| `notification` | **Read**         | View notifications                                                |
| `user`         | **Read**         | Read basic user information                                       |

***

## Adding the Token to Kody

Paste the generated token into the **Kody integration settings screen** when enabling the Forgejo integration.

***

## Important Notes

* The token is **shown only once** after creation. Save it securely.
* If the token is compromised, revoke it immediately and create a new one.
* Periodically audit tokens and their permissions to confirm they are still needed.


# Github FGPAT Token
Source: https://docs.kodus.io/how_to_use/en/code_review/general_config/github_pat



## Introduction to FGPAT

To enable Kody to perform automatic Code Reviews, you need to generate a Fine-Grained Personal Access Token (FGPAT) in GitHub. This token allows Kody to securely access your repositories and perform code analysis in a controlled manner.

## Check Fine-Grained Access Permissions

By default, a Fine-Grained PAT may not have access to your organization’s content. Ensure access by following these steps:

<img alt="title" />

1. You must be the organization owner.
2. Go to your organization's settings in GitHub:
   * You can use this URL replacing with your org name: <small>[https://github.com/organizations/YOUR\_ORG\_NAME/settings/personal-access-tokens](https://github.com/organizations/YOUR_ORG_NAME/settings/personal-access-tokens))</small>.
3. Under **Fine-Grained Personal Access Tokens**, select **"Allow access via fine-grained personal access tokens"** to enable secure access for Kody.

## Generating the FGPAT (Fine-Grained Personal Access Token)

<iframe title="YouTube video player" />

Follow these steps to set up the token correctly:

1. **Access GitHub and go to your profile settings**:

   * [Click here to access the profile settings page](https://github.com/settings/profile).

2. **Navigate to `Developer Settings`**:

   * In the left sidebar, scroll down to find `Developer Settings` and click on it.

3. **Go to `Personal Access Tokens`**:

   * Still in the left sidebar, under `Developer Settings`, select `Personal Access Tokens`.
   * Then, click on [Fine-grained Tokens](https://github.com/settings/tokens?type=beta).

4. **Generate a new token**:

   * Click the `Generate new token` button.

5. **Set up the new token with the following specifications**:

   * **Token Name**: Choose an easily identifiable name, such as `kody_code_review`.
   * **Expiration Date**: If possible, select a long expiration date, preferably at least 180 days.
   * **Resource Owner**: Ensure the organization is set as the token owner, as the team’s repositories are under the organization.
   * **Repository Access**: Select **All repositories** to allow the token access to all repositories.
   * **Permissions**: Configure the following read-only permissions:
   * **Repository**:
     * **Actions**: Read permission.
     * **Commit statuses**: Read permission.
     * **Contents**: Read and write permission.
     * **Deployments**: Read permission.
     * **Issues**: Read permission.
     * **Metadata**: Read permission.
     * **Pull requests**: Read and write permission.
     * **Webhooks**: Read and write permission.
   * **Organization**:
     * **Members**: Read permission.

6. **Finalize and save the token**:
   * After setting up the permissions, click on `Generate token`.
   * Make sure to copy the generated token and store it securely, as you’ll need it to configure Kody.

## Adding the Token to Kody

After generating the token, paste it in the Kody configuration screen for automation setup. The modal will open automatically as soon as you attempt to enable automation.


# GitLab PAT Token
Source: https://docs.kodus.io/how_to_use/en/code_review/general_config/gitlab_pat



## Introduction to the PAT

To enable Kody to perform automatic Code Reviews, you need to generate a Personal Access Token (PAT) in GitLab. This token allows Kody to securely access your repositories and conduct code analysis in a controlled way.

## Generating the PAT (Personal Access Token)

Follow these steps to set up the token correctly:

1. **Access GitLab and go to your profile settings**:

   * [Click here to access the profile settings page](https://gitlab.com/-/user_settings/personal_access_tokens).

2. **Navigate to `Access Tokens`**:

   * In the left sidebar, scroll to find `Access Tokens` and click on it.

3. **Add a new token**:

   * Click on the `Add new token` button.

4. **Set up the new token with the following specifications**:

   * **Token Name**: Choose an easily identifiable name, such as `kody_code_review`.
   * **Expiration Date**: If possible, select a long expiration date, preferably at least 180 days.
   * **Permissions**: Set the following permissions:
     * **api**: Read access.
     * **read\_api**: Read access.
     * **read\_user**: Read access.
     * **read\_repository**: Read access.
     * **write\_repository**: Read access.

5. **Finalize and save the token**:
   * After configuring the permissions, click `Generate token`.
   * Make sure to copy the generated token and store it securely, as you’ll need it to configure Kody.

## Adding the Token to Kody

After generating the token, paste it into the Kody automation setup screen. The configuration modal will open automatically when you attempt to enable the automation.


# Reinforcement Learning
Source: https://docs.kodus.io/how_to_use/en/code_review/learning/kody_learning

Kody gets smarter with every interaction. By learning from your team's feedback, she continuously adapts her code suggestions to match your team's preferences and standards.

## Quick Overview

* 👍 Thumbs up: Kody learns what your team likes
* 👎 Thumbs down: Kody learns what to avoid
* ✨ Auto-learning: Kody tracks which suggestions get implemented

## How the Learning Works

<img alt="Kody Learnings" />

### 1. Collecting Feedback

Kody learns from three main sources:

* **Direct Reactions**: Team members can react to Kody's suggestions on any code management tool:

  * 👍 = "This is what we want"
  * 👎 = "This doesn't match our style"

  How you react depends on your Git platform:

  | Platform                | How to give feedback                                                                                                                                  |
  | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
  | GitHub, GitLab, Forgejo | Add a 👍/👎 **emoji reaction** directly on Kody's suggestion comment                                                                                  |
  | Azure DevOps, Bitbucket | No emoji reactions on PR comments — **reply** inside the suggestion thread with 👍 or 👎 anywhere in your message (e.g. `👎 we handle this upstream`) |

  <Note>
    On Azure DevOps and Bitbucket each person counts as one vote per suggestion, and extra text in the reply is welcome — it helps Kody learn the "why".
  </Note>

* **Implementation Tracking**: When your team implements Kody's suggestions, she marks it as positive feedback

* **Pattern Recognition**: Kody builds knowledge clusters based on your team's preferences

### 2. Smart Filtering

Once Kody has enough data, she:

1. Analyzes new code suggestions
2. Compares them against your team's preference clusters
3. Only shows suggestions that match your team's style
4. Filters out suggestions similar to previously rejected ones

## Why Your Feedback Matters

The more feedback you provide, the better Kody becomes at:

* ✅ Matching your coding style
* 🎯 Making relevant suggestions
* 🚫 Avoiding unwanted patterns
* 💡 Understanding team preferences

## Best Practices

1. **Be Consistent**: Encourage the team to provide feedback regularly
2. **React Promptly**: Give feedback while the context is fresh
3. **Team Alignment**: Ensure the team agrees on what makes a good suggestion


# Automatic Rules Generation
Source: https://docs.kodus.io/how_to_use/en/code_review/learning/kody_rules_generation

Kody can automatically generate custom rules by analyzing your team's code review history. Let her learn from your past reviews to create personalized coding standards.

<Warning>
  **Requires at least 3 months of Kody review history on the repository.** This feature derives rules from Kody's past reviews on your PRs, so repositories that have just onboarded won't produce useful suggestions. If you recently started using Kody, come back after a few months of real reviews.
</Warning>

## Quick Overview

* **Auto-Generation**: Kody analyzes your review history to create new rules
* **Data-Driven**: Uses 3 months of review data for intelligent insights
* **Smart Suggestions**: Generates rules based on actual team patterns
* **Manual Import Required**: Generated rules must be manually reviewed and imported to take effect
* **Continuous Learning**: Weekly rule updates as your team evolves

<iframe title="YouTube video player" />

## How It Works

### 1. Accessing Rules Generation

Navigate to your repository settings:

1. Go to **Code Review Settings** → **Repository** → **Kody Rules**
2. Look for the **"Generate Kody Rules"** button
3. Click to start the automatic generation process

### 2. Analysis Process

When you click "Generate Kody Rules", Kody will:

* **Scan Review History**: Analyzes the last 3 months of code reviews in your repository
* **Identify Patterns**: Discovers common feedback themes and coding preferences
* **Extract Standards**: Converts review patterns into actionable rules
* **Generate Suggestions**: Creates custom rule suggestions tailored to your team's style

### 3. Reviewing Generated Rules

Once the analysis is complete:

1. A **"Check Out New Rules"** button will appear
2. Click to review the generated rule suggestions
3. Browse through the proposed rules and their explanations
4. **Important**: Rules are not active yet - they are only suggestions at this point

### 4. Importing Rules (Required for Activation)

<Warning>
  **Critical Step**: Generated rules will NOT take effect until you manually
  import them.
</Warning>

To make the rules active:

* **Choose Selectively**: Import only the rules that match your team's needs
* **Customize**: Modify rules before importing if needed
* **Apply**: Add selected rules to your active rule set
* **Activation**: Only imported rules will be enforced during code reviews

## Continuous Learning

After the initial setup, Kody maintains an ongoing learning cycle:

* **Weekly Updates**: Kody generates new rule suggestions every week
* **Evolving Standards**: Rule suggestions adapt as your team's coding style evolves
* **Refined Accuracy**: Suggestions become more precise over time
* **Regular Reviews**: New rule suggestions appear for your review weekly

## Requirements

* **Minimum Data**: At least 3 months of review history in the repository
* **Active Reviews**: Regular code review activity for better pattern detection
* **Repository Access**: Proper permissions to modify repository rules


# Plugins
Source: https://docs.kodus.io/how_to_use/en/code_review/plugins

Plugins are a way to bring external business context directly into Kody's review workflow.

<Callout icon="alien">This is a beta feature. It is not yet production-ready and may not work as expected.</Callout>

## Overview

Plugins let you bring external business context directly into Kody's review workflow. They extend Kody's understanding with data from tools such as Jira, so feedback and actions stay aligned with your team's processes.

## What Plugins Are

Plugins are Model Context Protocol (MCP) servers curated by Kodus. Each plugin exposes specific capabilities—like fetching tasks or checking specs—that Kody can use while collaborating with you on pull requests.

## Kodus MCP

Every workspace ships with the Kodus MCP already connected. It aggregates secure adapters for every supported Git provider—GitHub, GitLab, Bitbucket, and Azure DevOps—so you never need to install separate code-manipulation plugins.

Beyond source control, the Kodus MCP unlocks first-party automations:

* Manage Kody rules directly from a review thread (create, edit, or remove).
* Open Kody issues manually when you need a custom follow-up outside of the automated flow.

## Using Plugins in Suggestions

<img alt="Example of using a plugin in a suggestion" />

Interact with a plugin inside a code review suggestion by explicitly mentioning Kody in your comment. Once invoked, Kody calls the relevant plugin and replies in the same thread.

### Example prompts

* `@kody, update this kody rule to ignore test files`
* `@kody, move this task https://jira.com/task-123 to DONE`

These prompts keep the discussion in context and let teammates follow the full conversation insida e the PR.

## Validating Business Logic

Use the `@kody -v business-logic` command when you want Kody to compare a pull request against a specification. Provide the spec content inline or share a link:

* `@kody -v business-logic https://jira.com/task-123`

Kody will fetch the referenced specification through the plugin and confirm whether the implementation matches the documented behavior.

<Card title="Business Logic Validation Guide" icon="shield-check" href="/how_to_use/en/code_review/business_logic_validation">
  Explore the in-depth walkthrough with prerequisites and troubleshooting for `@kody -v business-logic`.
</Card>

## Controlling Access

Kody only sees the tools you enable for each workspace. Install the plugins that matter to your workflow and keep everything else private.

## Custom Plugins

Bring your own MCP servers when you need capabilities beyond the curated catalog.

1. Open the plugin catalog inside your workspace and click **Add Custom Plugin**.
2. Provide the endpoint details:
   * **Plugin Name** (required) and optional **Description** to help teammates understand the integration.
   * Optional **Logo URL** for a recognizable icon in the catalog.
   * The MCP **URL** that hosts your server along with the expected **Protocol** (HTTP or WebSocket).
   * Any required **Authorization** method or custom headers for authentication.
3. Click **Create Plugin** to instantly make it available to Kody within the current workspace.

Custom plugins follow the same permissions model as curated integrations: only workspaces where the plugin is installed can invoke it, and Kody never accesses endpoints you do not explicitly configure.

## Tips

* Mention Kody only once per request so the correct plugin runs without duplication.
* Keep links accessible to your workspace; Kody needs permission to reach the target resource through the plugin.
* Review the plugin catalog periodically—new integrations are added as Kodus curates additional MCP servers.


# Review Policy
Source: https://docs.kodus.io/how_to_use/en/code_review/policy



## Purpose

Clarify how to interpret Kody's feedback and how it interacts with your repository's merge policies.

## Suggestions vs. Blocking

* Suggestions: By default, Kody posts non-blocking comments for you to evaluate.
* Request Changes (optional): If enabled, Kody can mark a review as "changes requested" for critical issues.
* Auto-approve (optional): If enabled, Kody approves PRs when no issues are found.

<Note>
  Enable blocking behaviors only when your team agrees on the thresholds and has strong CI in place.
</Note>

## When to Enable Request Changes

* Security-sensitive areas where critical issues must never ship.
* Performance hotspots where regressions are costly.
* Repositories with clear coding standards and stable review rules.

## When to Use Auto-approve

* Small, low-risk changes (docs/tests).
* Teams with high test coverage and reliable CI.

## Human Decision Always Matters

Kody accelerates feedback but does not replace human judgment. Your team decides which suggestions to adopt and when to merge.


# Steer a Review (Focus)
Source: https://docs.kodus.io/how_to_use/en/code_review/review_directive

Direct Kody's attention to a specific area of a pull request with a one-off review directive, via PR comment or CLI

A **review directive** lets you tell Kody where to focus its deepest analysis for a single review. Instead of changing any configuration, you attach a short instruction when you trigger the review — for example, "focus on the auth and session logic" — and Kody spends its hardest analysis on the changed code that matches.

<Note>
  A directive is **ephemeral**: it applies to that one review run only. It is not saved to your settings and does not affect future reviews. To change Kody's behavior permanently, use [Custom Prompts](/how_to_use/en/code_review/configs/custom_prompts) or [Kody Rules](/how_to_use/en/code_review/configs/kody_rules) instead.
</Note>

## When to Use It

* A PR touches many files but you care most about one risky area (auth, payments, a migration).
* You want Kody to trace the callers and callees of a specific change and challenge it harder.
* You're re-running a review and want to steer attention without editing any config.

## Priority, Not a Filter

This is the most important thing to understand:

<Warning>
  A directive sets **priority, not a filter**. Kody prioritizes the focus area, but it still reports any concrete bug, security, or performance issue it notices **elsewhere** in the diff. It never suppresses findings outside the focus, and it never approves the rest of the PR unseen.
</Warning>

Use a directive to say *"look here hardest"* — not *"only look here."*

## How to Trigger It

<Tabs>
  <Tab title="PR / MR Comment">
    Add your focus text right after the review command in a pull request comment:

    ```text theme={null}
    @kody review focus on the auth and session logic
    ```

    You can also use `start-review`, and combine it with `--force`:

    ```text theme={null}
    @kody start-review focus on the new database migration
    @kody review --force focus on error handling in the webhook parser
    ```

    <Note>
      `--force` re-runs the review even when Kody would normally skip it ("no new commits since the last review"). Use it — with or without a focus directive — to get a fresh pass after fixing whatever made the previous run fail, or to apply updated settings to an already-reviewed PR.
    </Note>

    <Note>
      Only the **first line** after the command is used as the directive. Everything on later lines is ignored, so keep your focus to a single line.
    </Note>

    Works on GitHub, GitLab, Azure DevOps, Bitbucket, and Forgejo.
  </Tab>

  <Tab title="CLI">
    Pass the `--focus` flag when running a review:

    ```bash theme={null}
    kodus review --focus "the auth and session logic"
    ```

    See the [CLI commands reference](/how_to_use/en/cli/commands) for the full command surface.
  </Tab>
</Tabs>

## Writing a Good Directive

* **Be specific about the area, not the verdict.** "focus on concurrency in the queue consumer" works better than "find bugs".
* **Name the code, not the outcome.** Point at a module, flow, or concern ("the retry logic", "the SQL in the reports service").
* **Keep it short.** Directives are capped at **500 characters**; only the first line of a comment is read.

<AccordionGroup>
  <Accordion title="Good examples">
    - `@kody review focus on the authentication and token-refresh flow`
    - `@kody review focus on the new Stripe webhook handling`
    - `kodus review --focus "race conditions in the background worker"`
  </Accordion>

  <Accordion title="Weak examples">
    * `@kody review please be thorough` — no area to prioritize.
    * `@kody review only comment on file X` — a directive is not a filter; use [ignore paths](/how_to_use/en/code_review/configs/general) to scope files instead.
  </Accordion>
</AccordionGroup>

## Notes & Limits

* **Length:** directives are truncated at 500 characters.
* **First line only:** for PR comments, only the first line after the command becomes the directive.
* **Untrusted by design:** because anyone who can comment on the PR can supply a directive, the text is sanitized before use (control characters and angle brackets are stripped). This does not change your focus — it only prevents the text from tampering with Kody's internal prompt.
* **Not persisted:** nothing is written to your repository or organization settings.


# Troubleshooting
Source: https://docs.kodus.io/how_to_use/en/code_review/troubleshooting

Troubleshooting Kody Code Review

## Kody Code Review Not Working? Steps to Fix Common Issues

### Token Issues

If you're connected via a token, ensure these points are checked:

* **GitHub Users**: Verify that your token is enabled for your organization:
  1. You must be the organization owner.
  2. Go to your organization's settings in GitHub:
     * Use the following URL and replace `YOUR_ORG_NAME` with the name of your organization:
       <small>
         `https://github.com/organizations/YOUR_ORG_NAME/settings/member_privileges`
       </small>
       .
  3. Under **Fine-Grained Personal Access Tokens**, ensure **"Allow access via fine-grained personal access tokens"** is selected.
* **Personal Access Token (PAT)**: Confirm that your token is configured for your organization and has the required permissions. [Manage tokens](https://github.com/settings/tokens?type=beta).
* **Token Expiry**: Make sure your token is active. [Check token status](https://github.com/settings/tokens?type=beta).

<Frame>
  <img alt="Token Example" />
</Frame>

***

### Configuration Issues

* **Automated Reviews**: Ensure automated reviews are enabled in your [Global Settings](https://app.kodus.io/automations/AutomationCodeReview/global/general). If disabled, start reviews manually with `@kody start-review`.
* **Review Types**: Ensure at least one review type is selected for Kody to provide suggestions. [Configure review types](https://app.kodus.io/automations/AutomationCodeReview/global/general).
* **Branch Reviews**: By default, Kody reviews PRs merged into the default branch. To include additional branches, [update your configuration](https://app.kodus.io/automations/AutomationCodeReview/global/general).
* **Large PRs**: Be aware that PRs with a high number of changes may take longer to process.

***

### Global vs. Repository Settings

Kody uses a hierarchical configuration system. Here's how it works:

* **Global Settings**: Applied to all repositories by default.
* **Repository-Specific Settings**: If configured, they will override global settings for that specific repository.

#### Steps to Troubleshoot

1. **Check Global Configuration**: Review and confirm global settings are correct. [Access Global Settings](https://app.kodus.io/automations/AutomationCodeReview/global/general).
2. **Verify Repository Settings**:
   * Navigate to the **By Repositories** section in your settings.
   * Confirm if custom configurations are set for the repository in question.
3. **Align or Clear Configurations**:
   * To apply global settings, clear any repository-specific configurations.
   * Alternatively, adjust the repository-specific settings to meet your needs.

#### Common Symptoms

* Automated reviews are not triggered for a repository.
* Kody applies unexpected settings or suggestions.
* Global settings are not reflected in specific repositories.

## No Response or No Comments from Kody

Work through this quick checklist:

1. PR contains reviewable code changes (not only docs or images)? Kody may skip if there's nothing relevant to analyze.
2. Branch is in scope? By default, only PRs targeting the default branch are reviewed unless additional base branches are configured.
3. **Large PRs:** Kody reviews PRs with up to 200 **reviewable files** (after applying ignore patterns). Example: PR with 250 total files but 60 are `.lock` files → Kody reviews the remaining 190 files ✅
4. Mode: If automated reviews are disabled, trigger manually with `@kody start-review`.
5. Push cadence: If using auto-pause, wait for the cool-down or request a manual review.
6. Repository overrides: Repo-specific settings can override global ones. Clear or align them as needed.

<Card title="Review Modes & Cadence" icon="clock" href="/how_to_use/en/code_review/configs/general">
  Check automated review, cadence, and branch filters.
</Card>

<Card title="Limits & Pricing" icon="scale-balanced" href="/how_to_use/en/pricing">
  Learn about suggested limits and how they affect reviews.
</Card>


# Overview
Source: https://docs.kodus.io/how_to_use/en/issues/overview

Track and manage unimplemented suggestions with the Kody Issues feature.

## Quick Overview

* **Auto-tracking**: Automatically captures unimplemented suggestions from closed PRs
* **Smart resolution**: Auto-resolves when suggestions are implemented in future PRs
* **Advanced filtering**: Save custom views by status, severity, and category
* **Zero setup**: Works automatically with your existing code review workflow

## What It Is

The **Kody Issues** feature automatically tracks all suggestions generated by Kody that were **not implemented** in your pull requests (PRs). It acts like a sonar, providing a live list of pending improvements to ensure you never lose sight of critical feedback.

<Frame>
  <img alt="Kody Issues Dashboard" />
</Frame>

## Key Benefits

<CardGroup>
  <Card title="Continuous Visibility" icon="eye">
    Always stay aware of outstanding improvements without manual tracking
  </Card>

  <Card title="Quality Tracking" icon="chart-line">
    Prioritize and address critical fixes efficiently with severity levels
  </Card>

  <Card title="Error Prevention" icon="shield-check">
    Ensure vital suggestions don't fall through the cracks during development
  </Card>

  <Card title="Team Flexibility" icon="users">
    Customize statuses and severities to fit your workflow perfectly
  </Card>
</CardGroup>

## How It Works

### 1. Issue Creation

<Note>
  Issues are only created when PRs are **closed** - not when they're opened or
  during review.
</Note>

<Warning>
  Kody rules of type **PR** do not generate issues. Only file-level and code-specific suggestions create trackable issues.
</Warning>

* When a PR is **closed**, Kody compiles all suggestions made in that PR that were **not applied**
* For each unimplemented suggestion, Kody automatically creates an **Issue** linked to the repository
* Each issue includes the original suggestion context, file location, and severity level

### 2. Automatic Resolution

* If a developer implements the suggested change in a **subsequent PR**, Kody marks the associated Issue as **Resolved**
* Kody intelligently matches implemented changes to existing issues using code analysis
* Resolution happens automatically without manual intervention

### 3. Manual Management

#### Status Control

* **Open**: New issues requiring attention
* **Resolved**: Automatically marked when suggestions are implemented
* **Dismissed**: Manually marked when suggestions aren't relevant to your team

#### Severity Adjustment

* Each Issue has a severity level (`Critical`, `High`, `Medium`, `Low`)
* You can update severity levels at any time to reflect your team's priorities
* Use severity to focus on the most impactful improvements first

### 4. Advanced Filtering

<Warning>
  Filters are powerful tools - save custom views to quickly access issues that
  matter most to your workflow.
</Warning>

* **Status filters**: Open, Resolved, Dismissed
* **Severity filters**: Critical, High, Medium, Low
* **Category filters**: Security, Performance, Code Style, etc.
* **Repository filters**: Focus on specific projects
* **Save custom views**: Automatically apply your preferred filters

## Why It Matters

### For Development Teams

* **Never lose track** of important code improvements
* **Prioritize work** based on actual impact and severity
* **Learn patterns** from commonly dismissed vs. implemented suggestions

### For Engineering Managers

* **Track code quality** trends across repositories
* **Identify bottlenecks** in suggestion implementation
* **Measure improvement** in code review follow-through

## Best Practices

<CardGroup>
  <Card title="Regular Review Sessions" icon="calendar">
    Schedule weekly team reviews of open issues to maintain code quality
    momentum
  </Card>

  <Card title="Severity Guidelines" icon="triangle-exclamation">
    Establish team standards for when to adjust issue severity levels
  </Card>

  <Card title="Dismissal Criteria" icon="circle-xmark">
    Create clear guidelines for when issues should be dismissed vs. implemented
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Kody Rules Setup" icon="user-police" href="/how_to_use/en/code_review/configs/kody_rules">
    Configure custom rules that will be tracked as issues
  </Card>

  <Card title="Team Learning" icon="graduation-cap" href="/how_to_use/en/code_review/learning/kody_learning">
    Learn how Kody improves suggestions based on your team's feedback
  </Card>
</CardGroup>


# Introduction
Source: https://docs.kodus.io/how_to_use/en/overview



## What is Kodus

Kodus builds open source AI Agents to help engineering teams improve code quality. Our first agent is **Kody**, an AI Code Reviewer that streamlines your review process.

<Frame>
  <img />
</Frame>

## Key Features

<CardGroup>
  <Card title="100% Open Source" icon="github">
    All source code is available on GitHub for anyone to inspect, use, and improve.
  </Card>

  <Card title="No Inference Games" icon="hand-holding-dollar">
    You pay providers directly at their rates. Predictable costs and full model capabilities
  </Card>

  <Card title="AI-Powered Code Analysis" icon="sparkles">
    Deep code understanding across multiple languages with context-aware recommendations
  </Card>

  <Card title="Future Proof by Design" icon="wand-magic-sparkles">
    New model released? Use it immediately. Works with any AI provider, any model
  </Card>

  <Card title="True Visibility" icon="magnifying-glass">
    Not just "explainable AI" but complete transparency. See every file read, every decision considered, every token used
  </Card>

  <Card title="Seamless Git Integration" icon="code-branch">
    Works directly with GitHub, GitLab, and Bitbucket without disrupting your workflow
  </Card>

  <Card title="Customizable Rules" icon="sliders">
    Define and enforce your team's coding standards and best practices
  </Card>

  <Card title="Knowledge Retention" icon="brain">
    Learns from your codebase and team feedback to provide increasingly relevant reviews
  </Card>
</CardGroup>

## Supported Languages

Kody works with any programming language or file type out of the box using semantic (LLM) analysis, backed by code search (grep-style) for precise, repository-wide context.

## Benefits for Your Team

* **Faster Reviews**: Automate routine checks and focus on complex aspects
* **Consistent Quality**: Ensure all code meets your team's standards
* **Continuous Learning**: Kody improves as it learns from your team's feedback

## Our Long Term Vision

At Kodus, our mission is to empower engineering teams to achieve 10x results through AI-enhanced workflows:

* 🚀 **Productivity**: Deliver faster without compromising quality
* 🎯 **Impact**: Boost business value with every recommendation
* 💜 **Satisfaction**: Create an environment where team members thrive

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="quickstart">
    Quickly set up Kody and integrate with your team's tools and platforms.
  </Card>

  <Card title="Workspace Roles & Permissions" icon="users" href="workspace_roles">
    Learn about role-based access control and how to manage workspace members effectively.
  </Card>

  <Card title="Explore Pricing" icon="money-bill-wave" href="https://kodus.io/pricing">
    Dive deep into our pricing structure and find the plan that suits your
    needs.
  </Card>
</CardGroup>


# Pricing Deep Dive
Source: https://docs.kodus.io/how_to_use/en/pricing



Everything you need to choose the right plan. For live pricing, see [kodus.io/pricing](https://kodus.io/pricing).

<Note>
  **Reviews are unlimited on every plan** — they run on your own AI key (BYOK).
  Plans differ by **features**, not by how many PRs Kody can review. Every plan
  includes unlimited users and unlimited pull requests, with no per-seat minimum.
</Note>

## Plans at a glance

<CardGroup>
  <Card title="Community" icon="github">
    **Free, forever.** BYOK. Self-hosted or cloud.

    For indie devs, students, OSS maintainers, and small teams.
  </Card>

  <Card title="Teams" icon="users">
    **\$10/dev/month** + token costs (BYOK). Cloud only.

    14-day free trial, no credit card. 20% off annually.
  </Card>

  <Card title="Enterprise" icon="building">
    **Custom pricing.** Self-hosted or cloud.

    Hardened security, governance, and hands-on onboarding.
  </Card>
</CardGroup>

## The free trial (Teams)

A Teams trial runs on **two separate, independent clocks** — the 14 days govern Team **features**, never your ability to review PRs:

<CardGroup>
  <Card title="14 days of Team features" icon="calendar">
    Cockpit, unlimited Kody Rules and plugins, priority queue, and more.
  </Card>

  <Card title="Your first 5 PR reviews on us" icon="gift">
    We cover the AI tokens, so you can try Kody with **zero setup — no API key
    needed.** (Earn a few more by completing onboarding steps.)
  </Card>
</CardGroup>

**To keep reviewing past the 5 trial reviews — or to go unlimited right away — [connect your AI key](/how_to_use/en/byok).** Reviews then run on your key: unlimited, on any plan, even after the 14 days end. Trial reviews run on a model Kodus picks for you; with your own key you can run frontier models for the best quality.

If trial reviews run out before you connect a key, Kody pauses reviews and posts a comment with a one-click link to add your key.

## What's included

| Feature                       | Community            | Teams           | Enterprise                              |
| ----------------------------- | -------------------- | --------------- | --------------------------------------- |
| **Price**                     | Free                 | \$10/dev/mo     | Custom                                  |
| **Deployment**                | Self-hosted or cloud | Cloud           | Self-hosted or cloud                    |
| **Code reviews**              | Unlimited            | Unlimited       | Unlimited                               |
| **Users**                     | Unlimited            | Unlimited       | Unlimited                               |
| **Kody Rules**                | Up to 10             | Unlimited       | Unlimited                               |
| **Plugins / MCPs**            | Up to 3              | Unlimited       | Unlimited                               |
| **Quality Radar issues**      | Unlimited            | Unlimited       | Unlimited                               |
| **Kody Learnings & Memory**   | ✓                    | ✓               | ✓                                       |
| **Priority queue**            | —                    | ✓               | ✓                                       |
| **Kodus Cockpit (metrics)**   | —                    | ✓               | ✓                                       |
| **SSO / SAML**                | —                    | —               | ✓                                       |
| **RBAC + audit logs**         | —                    | —               | ✓                                       |
| **SOC 2 compliant**           | —                    | —               | ✓                                       |
| **Dedicated instance & SLAs** | —                    | —               | ✓                                       |
| **Support**                   | Discord              | Email + Discord | Private Discord + up to 5h/mo dedicated |

## How pricing works

<CardGroup>
  <Card title="Pay per active developer" icon="user-check">
    Only developers who open PRs count toward a seat. No minimums, no seat
    lock-in.
  </Card>

  <Card title="Adjust anytime" icon="sliders">
    Change your active-developer count in account settings whenever your team
    changes.
  </Card>
</CardGroup>

## BYOK: the default across all plans

Kodus does **not** sell LLM tokens by default. Community, Teams, and Enterprise all run on **Bring Your Own Key** — you connect your own provider (OpenAI, Anthropic, Gemini, or any OpenAI-compatible), and tokens are billed directly by that provider. Kodus never marks up tokens.

| Plan           | What you pay Kodus | Tokens                       |
| -------------- | ------------------ | ---------------------------- |
| **Community**  | \$0                | You pay your provider (BYOK) |
| **Teams**      | \$10/active dev/mo | You pay your provider (BYOK) |
| **Enterprise** | Custom             | You pay your provider (BYOK) |

See the [BYOK overview](/how_to_use/en/byok) for supported providers and setup.

## Teams pricing — \$10/active dev/month

In addition to your provider's token cost (no Kodus markup).

<CardGroup>
  <Card title="What the $10/dev covers" icon="box">
    * Managed cloud hosting + automatic updates
    * Priority queue for Kody Agents
    * Kodus Cockpit (engineering metrics)
    * Unlimited Kody Rules & plugins/MCPs
    * Email + Discord support
  </Card>

  <Card title="What tokens cover" icon="coins">
    * Every LLM call Kody makes during a review
    * Billed by your provider; switch anytime
    * You pick the model — cost-effective (Gemini Flash, GPT-5-mini) or frontier (Claude 4.5 Sonnet, GPT-5)
  </Card>
</CardGroup>

**Billing:** monthly, or **20% off** annually · 14-day free trial, no card · cancel anytime (effective end of cycle).

## Enterprise pricing

Custom-priced via contract. Like every plan, Enterprise is **BYOK** — Kodus bills only the per-seat fee and you pay your LLM provider directly.

Enterprise adds SSO / SAML, RBAC with audit logs and analytics, a dedicated instance, custom SLAs, up to **5 hours/month** of dedicated support, and a private Discord channel. Kodus is **SOC 2 compliant**.

[Contact sales](https://kodus.io/pricing) for a quote tailored to your organization.

## Unlimited pull requests

No PR limit on any plan. The only hard limit: we don't review PRs with more than **200 changed files**. Git-provider-side rate limits may also apply.

## Kody Pilot Program

We subsidize Kodus with **30–100% discounts** for teams that move the industry forward or couldn't otherwise afford it:

* Early-stage startups
* Open-source projects with active development
* Teams in economically disadvantaged regions
* Non-profit organizations

<Steps>
  <Step title="Join our Discord">
    Hop into the [community](https://discord.gg/TFZBRk9fT6).
  </Step>

  <Step title="Tell us about you">
    Share your org name, website, and a brief description of your work.
  </Step>

  <Step title="Show eligibility">
    Startup stage/funding, OSS repo links, region context, or proof of
    non-profit status.
  </Step>

  <Step title="Hear back in 3 business days">
    We review your application and follow up.
  </Step>
</Steps>

## Payments & billing

* **Powered by Stripe** — secure, globally trusted payment processing.
* **Cancel anytime** — changes take effect at the end of your billing cycle.
* **Invoices & Nota Fiscal** — for Brazilian customers 🇧🇷, we provide invoices and issue a Nota Fiscal for every transaction.

***

Questions? Join our [Discord community](https://discord.gg/TFZBRk9fT6), or see the latest plan details at [kodus.io/pricing](https://kodus.io/pricing).


# Getting Started
Source: https://docs.kodus.io/how_to_use/en/quickstart



<Steps>
  <Step title="Create an Account">
    Sign up by entering your name, email, and password, or use a social provider like Google, GitHub, or GitLab.
  </Step>

  <Step title="Configure a Code Management Tool">
    <AccordionGroup>
      <Accordion title="Set Up GitHub" icon="github">
        Connect GitHub via OAuth or token:

        * **OAuth (Recommended)**: Click the "via OAuth" button. You'll be redirected to GitHub's authentication page.
          * ✅ Kody appears as a dedicated bot in PRs
          * ✅ Better audit trail (clear distinction between human and AI reviews)
          * Requires `owner` permissions for your organization
          * Grant access to all repositories you want Kody to analyze (you can adjust this later)
        * **Token**: Reviews appear under your username. <a href="/how_to_use/en/code_review/general_config/github_pat">Visit the GitHub Token Setup page for detailed instructions.</a>

        <Note>Using GitHub Enterprise? Allowlist Kodus's IP `52.55.217.197` in your network firewall before connecting.</Note>
      </Accordion>

      <Accordion title="Set Up GitLab" icon="gitlab">
        Connect GitLab via OAuth or token:

        * **OAuth (Recommended)**: Click the "via OAuth" button, and you'll be redirected to GitLab's authentication page.
          * ✅ Kody appears as a dedicated bot in PRs
          * Grant access to all repositories you want Kody to analyze (you can adjust this later)
        * **Token**: Reviews appear under your username. <a href="/how_to_use/en/code_review/general_config/gitlab_pat">Visit the GitLab Token Setup page for detailed instructions.</a>

        <Note>Using a self-hosted GitLab instance? Allowlist Kodus's IP `52.55.217.197` in your network firewall before connecting.</Note>
      </Accordion>

      <Accordion title="Set Up Bitbucket" icon="bitbucket">
        Connect Bitbucket via OAuth or token:

        * **Token**: <a href="/how_to_use/en/code_review/general_config/bitbucket_pat">Visit the Bitbucket Token Setup page for detailed instructions.</a>

        <Note>Using Bitbucket Data Center (self-hosted)? Allowlist Kodus's IP `52.55.217.197` in your network firewall before connecting.</Note>
      </Accordion>

      <Accordion title="Set Up Azure DevOps" icon="microsoft">
        Connect Azure DevOps via OAuth or token:

        * **Token**: <a href="/how_to_use/en/code_review/general_config/azure_devops_pat">Visit the Azure DevOps Token Setup page for detailed instructions.</a>

        <Note>Using Azure DevOps Server (self-hosted)? Allowlist Kodus's IP `52.55.217.197` in your network firewall before connecting.</Note>
      </Accordion>

      <Accordion title="Set Up Forgejo" icon="https://mintcdn.com/kodus/av-AClqC_WJBKjTo/images/forgejo.svg?fit=max&auto=format&n=av-AClqC_WJBKjTo&q=85&s=f371aea65c661ab220b281b884b98c55">
        Connect Forgejo via token:

        * **Token**: <a href="/how_to_use/en/code_review/general_config/forgejo_pat">Visit the Forgejo Token Setup page for detailed instructions.</a>

        <Note>Forgejo support is maintained by the community.</Note>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Select Repositories">
    Choose the repositories you want Kody to access for automated reviews and
    actionable insights.
  </Step>

  <Step title="Run Your First PR Review">
    Select a pull request (PR) for Kody to review. This will showcase the power of
    automated code reviews. Once selected, Kody will perform the review directly
    in your Git tool. Don’t worry, this is just for the first time—after that,
    Kody will automatically review every PR you open.
  </Step>

  <Step title="Enjoy Kody Automated Reviews! 🔥">
    Sit back and let Kody streamline your review process with intelligent
    suggestions and actionable insights.
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Configure Kody with your team Rules" icon="Hand-love" href="code_review/configs/kody_rules">
    Learn how to configure Kody with your team rules.
  </Card>
</CardGroup>


# AI Model Security
Source: https://docs.kodus.io/how_to_use/en/security/data_usage



## Models Used

Kodus uses the following language models for code analysis:

* **GPT-4o and derivatives** (OpenAI)
* **Gemini 1.5 Pro and derivatives** (Google)
* **Claude 3.5 Sonnet and derivatives** (Anthropic)

## Data Handling

Your code is processed temporarily and never used for training:

* Data retained only during the review session
* Immediately discarded after completion
* Never used to train or improve models
* Privacy maintained per provider agreements

## Terms of Use for Each Model

* **GPT-4o and derivatives**: [GPT-4o Terms of Use](https://openai.com/enterprise-privacy/)
* **Gemini 1.5 Pro and derivatives**: [Gemini 1.5 Pro Terms of Use](https://ai.google.dev/gemini-api/terms)
* **Claude 3.5 Sonnet and derivatives**: [Claude 3.5 Sonnet Terms of Use](https://support.anthropic.com/en/articles/7996885-how-do-you-use-personal-data-in-model-training)

## Security Measures

* **Encryption**: Data encrypted in transit and at rest
* **Data Isolation**: Models don't store or retain data after processing
* **Controlled Access**: Strict access controls for authorized personnel only (see [Workspace Roles](/how_to_use/en/workspace_roles))
* **Regular Audits**: Periodic security audits for compliance
* **Security Updates**: Regular patches and updates

## Self-hosted telemetry

If you run Kodus self-hosted, each instance sends one anonymous daily
heartbeat to `telemetry.kodus.io` with aggregated counters and runtime
metadata — never code, identities, or anything that could trace back to
your users. You can inspect the exact payload with `yarn telemetry:preview`
or disable it with `KODUS_TELEMETRY_DISABLED=true`. Full schema, retention
policy, and source code links are documented in
[Anonymous Telemetry](/how_to_deploy/en/deploy_kodus/telemetry).

Questions? Contact our support team or join [Discord](https://discord.gg/TFZBRk9fT6).


# Single Sign-On
Source: https://docs.kodus.io/how_to_use/en/security/sso

Enable Single Sign-On (SSO) for secure and efficient access to Kodus.

## Overview

Single Sign-On (SSO) allows you to manage access to Kodus through a single identity provider, streamlining authentication and enhancing security.

## Getting Started

<Steps>
  <Step title="Access SSO settings">
    Navigate to your organization settings at
    [app.kodus.io/organization/sso](https://app.kodus.io/organization/sso)
  </Step>

  <Step title="Fill in your IdP configuration">
    Fill in your IdP's settings such as their Issuer id, their URL and the signing certificate. These can be filled in manually or by providing either your IdP's metadata URL or a metadata XML file.

    <Info>
      These values can usually be found in your IdP's documentation or in their admin console.
    </Info>
  </Step>

  <Step title="Configure Kodus as a SP in your IdP">
    Configure Kodus as a SP in your IdP by providing our entity ID (`kodus-orchestrator` by default) and your organization's callback URL found in the SSO settings page.

    Make sure the name ID format is set to email.

    <Warning>
      Ensure you disable signing certificates in your IdP's SP configuration.
    </Warning>
  </Step>

  <Step title="Enable and test SSO">
    Enable SSO in Kodus and test the configuration by logging out and logging back in. When attempting to log in with an email domain associated with your IdP, you will have the option to log in via SSO.
  </Step>
</Steps>

## Optional Configuration

### Mapping Attributes

You can map the following attributes from your IdP to Kodus users, improving the user experience.

* First Name, mapped to `firstName`
* Last Name, mapped to `lastName`


# Monthly Spend Limit
Source: https://docs.kodus.io/how_to_use/en/spend-limit

Get alerted as your BYOK model spend approaches a monthly cap. Alerts only — reviews keep running.

The monthly spend limit watches how much you're spending on your **BYOK models** and notifies your organization's Owners as that spend approaches a cap you set. It's an early-warning signal, not a hard stop.

<Warning>
  **This is a notification, not a cap. Kodus never blocks or pauses reviews when the limit is hit.** Spend keeps accruing on your provider account past 100%. To actually stop spend, set a hard limit in your **model provider's** dashboard (OpenAI, Anthropic, Google, etc.) — that's the only thing that can enforce it. Treat the Kodus limit as a heads-up so the provider cap is never a surprise.
</Warning>

## What it tracks

* **BYOK models only.** Spend is measured against the models you configured under [Bring Your Own Key](/how_to_use/en/byok) — the keys you pay your provider for directly. Models Kodus runs on its own side don't count.
* **Priced at current rates, per model.** Each model's tokens are priced at that model's current rate. There's no snapshot — if a model's price changes (catalog update or a manual edit), that model's month-to-date usage is recomputed at the new rate. Switching to a different model doesn't re-price the model you were using before.
* **Per calendar month (UTC).** The window runs from the 1st of the month to the 1st of the next. Usage resets to \$0 automatically at the start of each month — there's nothing to reset by hand.

<Info>
  For the figure to reflect only Kodus, we recommend the **API key you give Kodus is used exclusively with Kodus**. If the same key also powers other tools, your provider usage — and any estimate based on it — mixes the two.
</Info>

## Configure it

The limit lives on the BYOK screen, below your Main and Fallback models.

<Steps>
  <Step title="Open BYOK settings">
    Go to [app.kodus.io/organization/byok](https://app.kodus.io/organization/byok) and scroll to **Monthly spend limit**. (The section appears once you have at least one BYOK model configured.)
  </Step>

  <Step title="Check the model prices">
    Each configured model shows its per-token price — **input, output, cache read, cache write** — as **\$ / 1M tokens**. A **Catalog** badge means Kodus found the price automatically; a **Manual** badge means you've entered it yourself.
  </Step>

  <Step title="Fix any model with no price">
    A model badged **No price** couldn't be priced automatically (a custom or uncatalogued model). Type its per-token prices from your provider's pricing page. You can't enable the limit until every model has a price — spend can't be tracked for a model Kodus can't price.
  </Step>

  <Step title="Set the monthly limit and enable">
    Enter your cap in US\$, flip **Enable spend alerts** on, and click **Save spend limit**.
  </Step>
</Steps>

### Model pricing

<AccordionGroup>
  <Accordion title="Catalog vs. manual prices">
    Kodus looks each model up in a public pricing catalog and pre-fills what it finds (**Catalog**). If the catalog is wrong or missing a model, type the correct per-token rates — the badge switches to **Manual** and your values are used instead.
  </Accordion>

  <Accordion title="Revert a manual price back to catalog">
    On a model you've overridden, click **Revert to catalog price**. The inputs reset to the catalog values and the badge flips back to **Catalog**. From then on that model tracks the live catalog price again (no frozen snapshot).
  </Accordion>

  <Accordion title="Why a model might show 'No price'">
    Custom endpoints, self-hosted models, or models the catalog hasn't indexed have no automatic price. Enter the rates manually to make them trackable. Until then, the limit can't be enabled.
  </Accordion>
</AccordionGroup>

## Alerts

Once enabled, Kodus checks your month-to-date spend roughly **once an hour** and notifies your organization's **Owners** in the notification center as you cross each threshold:

| Threshold     | What you get                                                                                                         |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| **50%**       | Heads-up alert                                                                                                       |
| **75%**       | Heads-up alert                                                                                                       |
| **90%**       | Heads-up alert                                                                                                       |
| **100%**      | "Limit reached" alert                                                                                                |
| **Over 100%** | One final "you're over your limit — we won't notify again this month" notice, then silence for the rest of the month |

Each threshold fires **at most once per month**, so you won't get repeat pings for the same level. The slate clears automatically when the new month starts.

<Note>
  Reviews continue running normally the entire time — at 50%, at 100%, and beyond. The alerts are the only thing that happens.
</Note>

You can manage where these land (and which roles receive them) under **Spend Limit** in [Notification settings](https://app.kodus.io/organization/notifications).

## Accuracy

Spend is an **estimate**. It's derived from the tokens your reviews used and the per-token prices shown on the BYOK screen — it won't match your provider invoice to the cent.

<CardGroup>
  <Card title="Keep prices accurate" icon="tags">
    Check the catalog prices against your provider's pricing page and correct any that are off. Subscription/flat-rate plans especially won't match per-token catalog pricing.
  </Card>

  <Card title="Use the key only with Kodus" icon="key">
    A dedicated key means the usage Kodus sees is the usage Kodus caused — nothing else inflates the figure.
  </Card>
</CardGroup>

<Warning>
  **Concurrent reviews can briefly overshoot the cap.** Many PRs reviewed at once near the limit can push month-to-date spend a bit past 100% before the next hourly check catches it. This is expected — another reason the real cap belongs at your provider.
</Warning>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does hitting the limit stop my reviews?">
    No. It's notification-only. To stop spend, set a hard limit in your model provider's billing dashboard.
  </Accordion>

  <Accordion title="What counts toward the spend?">
    Only token usage on your **BYOK** models, priced at the current rates shown on the BYOK screen. Kodus-hosted models don't count.
  </Accordion>

  <Accordion title="When does the spend reset?">
    On the 1st of each calendar month (UTC). Month-to-date spend goes back to \$0 and all threshold alerts re-arm automatically.
  </Accordion>

  <Accordion title="I switched models mid-month — does my spend jump?">
    No. Spend is tracked **per model**: each model's tokens are priced at *that model's* rate. If you spent \$50 on model A and then switch to model B, model A's usage stays at \$50 — switching to B never re-prices A's tokens at B's rate. Your total just grows by what model B then uses.

    The only thing that re-prices already-incurred usage is a change to **that same model's price** — when the pricing catalog updates a model's rate, or you edit its manual price on the BYOK screen, that model's month-to-date usage is recomputed at the new rate (there's no frozen snapshot).
  </Accordion>

  <Accordion title="Why can't I enable the limit?">
    Every configured model must have a price (catalog or manual) and the monthly limit must be greater than \$0. Fix any **No price** model and set a positive amount, then save.
  </Accordion>

  <Accordion title="Who gets the alerts?">
    Your organization's Owners, in the in-app notification center. Adjust routing under **Spend Limit** in Notification settings.
  </Accordion>
</AccordionGroup>


# Workspace Roles
Source: https://docs.kodus.io/how_to_use/en/workspace_roles

Learn about role-based access control (RBAC) in Kodus workspaces, including the different user roles and their permissions.

<Note>
  **Workspace Members vs. PR Licenses**: These are completely separate and don't affect each other.

  * **Workspace Members**: Admins who configure Kodus settings (unlimited)
  * **PR Licenses**: Developers from your Git organization who get Kody reviews (based on your plan)
</Note>

## Understanding PR Licenses

PR licenses are automatically detected from your Git repositories based on developers who opened PRs in recent months.

**Why isn't a developer showing up?** If a developer isn't appearing in your PR license count, it means Kody isn't installed in a repository where that developer has opened PRs.

**Example:** You can have 1 workspace admin managing settings, while 20 developers get automated reviews. All plans include unlimited PRs—your plan only determines which developers get review access.

## Overview

Kodus workspaces supports **Role-Based Access Control (RBAC)**, allowing you to manage user permissions and access levels within your organization. Each workspace member can be assigned one of four distinct roles, each with specific permissions and capabilities.

## Available Roles

Each role provides different levels of access and capabilities within the workspace:

### Owner

**Full administrative access** to the workspace and all its resources. Can view, edit, and delete all configurations across all repositories.

### Billing Manager

**Financial and billing management** access with access to billing/subscription management and view access to most configurations, but no edit access to code review settings.

### Repository Admin

**Repository management** access. Sees all configurations, pull requests, issues, cockpit, and plugins across the whole organization (read-only), and can edit code review configurations and Kody Rules for the repositories assigned to them.

### Contributor

**Read-only access** to the whole organization. Contributors can view configurations, Kody Rules, pull requests, and issues across all repositories — no repository assignment needed — but cannot edit anything. Cockpit, token usage, billing, and user management stay admin-only.

## Role Permissions Matrix

Here's a detailed breakdown of what each role can do, based on the actual permissions matrix:

<Snippet />

## Managing Workspace Members

### Adding New Members

1. Navigate to your workspace **Members** section
2. Click **"Invite member"** button
3. Enter the member's email address
4. Select the appropriate role for the new member
5. Send the invitation

### Auto-Join for Workspace Members

Enable auto-join to allow users with matching email domains to join your workspace automatically.

**How to enable:**

1. Go to [Organization Settings](https://app.kodus.io/organization/general)
2. Enable auto-join for your organization
3. Currently works with your registered account email domain only
4. Need a different domain? Contact us in the community

**How it works:**

* Users who sign up with your email domain can choose to join your organization
* They must confirm their email after choosing to join
* All auto-join users enter as **Contributor** role (read-only access to the whole organization)
* As Owner, adjust their role if they need edit rights

### Changing Member Roles

1. Go to the **Members** section in your workspace
2. Find the member whose role you want to change
3. Click on their current role dropdown
4. Select the new role from the available options
5. The change takes effect immediately

### Removing Members

1. In the **Members** section, locate the member to remove
2. Click the **"Actions"** menu (three dots)
3. Select **"Remove from workspace"**
4. Confirm the removal in the dialog

## Security Considerations

1. **Principle of Least Privilege**: Always assign the role with the minimum necessary permissions
2. **Regular Audits**: Periodically review member roles and adjust as needed
3. **Access Reviews**: Conduct quarterly reviews of workspace access and permissions
4. **Immediate Revocation**: Remove access immediately when a member leaves the organization

## Troubleshooting

<AccordionGroup>
  <Accordion title="I can't invite new members to the workspace">
    **Solutions:**

    * Verify you have Owner or Repository Admin role
    * Check if your workspace has reached any system limits
    * Ensure you have the correct permissions in your account
  </Accordion>

  <Accordion title="A member can't edit code review configurations">
    **Solutions:**

    * Confirm the member has Repository Admin or Owner role for the specific repository
    * Check if the member has "own" permissions for the repository they want to edit
    * Verify the member's role assignment is correct
  </Accordion>

  <Accordion title="Billing information is not visible to a team member">
    **Solutions:**

    * Ensure the member has Owner or Billing Manager role
    * Check if billing features are enabled for your workspace
    * Verify the member's access hasn't been restricted
  </Accordion>

  <Accordion title="A member can't access cockpit features">
    **Solutions:**

    * Confirm the member has Repository Admin or Owner role (cockpit is not visible to Contributors or Billing Managers)
    * Verify the member's role assignment is correct
  </Accordion>

  <Accordion title="A developer isn't showing up in PR licenses">
    **Solutions:**

    * Verify Kody is installed in the repositories where this developer opens PRs
    * Check if the developer has opened PRs in recent months
    * Remember: PR licenses come from Git activity, not workspace members
    * Ensure the repository webhook is properly configured
  </Accordion>
</AccordionGroup>


# Can I use my own LLM provider for code review
Source: https://docs.kodus.io/knowledge_base/en/can-i-use-my-own-llm-provider

Bring your own API key and choose your preferred LLM provider for AI-powered code review with Kodus.

Yes. Kodus supports Bring Your Own Key (BYOK) on every plan, letting you use your preferred LLM provider. You pay the provider directly — Kodus never marks up tokens and never sees your key in plain text.

## How it works

1. Open **Settings → BYOK** ([app.kodus.io/organization/byok](https://app.kodus.io/organization/byok))
2. Pick a **recommended model** from the curated catalog, or click **Configure manually** for any other provider/endpoint
3. Paste your API key and click **Test & save** — Kodus validates the key with a cheap metadata call before persisting

## Curated recommended models

Ready-to-click cards with pre-tuned defaults (temperature, max tokens, reasoning level):

* Claude Sonnet 4.6 / Opus 4.7 (Anthropic)
* Gemini 3.1 Pro custom tools (Google)
* GPT-5.4 (OpenAI)
* Kimi K2.6 Coding (Moonshot AI — Developer API or Kimi Code Plan)
* GLM 5.1 (Z.ai — Developer API or Coding Plan)

For models outside this list, the **Configure manually** wizard walks you through any OpenAI, Anthropic, Google, OpenRouter, Novita, or OpenAI-compatible endpoint.

## Why use your own provider

* **Data control** — requests go directly to your provider
* **Cost management** — use your existing billing relationship, no markup
* **Model choice** — pick the model that works best for your codebase
* **Compliance** — meet internal requirements for AI tool usage
* **Fallback resilience** — configure a Main + Fallback to keep reviews running during provider outages

## Self-hosted LLM providers

If you self-host Kodus, you can point BYOK at self-hosted or aggregator endpoints like:

* Novita, Groq, Together AI, Fireworks AI
* Chutes, Synthetic
* Your own Ollama / vLLM / TGI instance (via the `OpenAI Compatible` provider)

For setup guides, see the [Cookbook](/cookbook/en/novita) and the provider-specific docs in the knowledge base.

For the full BYOK flow (catalog, manual wizard, plan selectors, advanced tuning), see [Bring Your Own Key](/how_to_use/en/byok).


# What is the difference between Review Rules and Memories
Source: https://docs.kodus.io/knowledge_base/en/difference-between-review-rules-and-memories

Understand when to use Review Rules vs Memories in Kody for the best code review results.

In the Kody Rules UI, you configure two different things, and knowing when to use each one makes your code reviews more effective.

A useful rule of thumb:

* **Memories** teach Kody how your codebase works so future reviews and suggestions are more relevant.
* **Review Rules** tell Kody what to flag when a PR does not match your standards.

## Review Rules

Review Rules are **traditional code review checks** that run during the dedicated code review stage. They analyze file diffs or the entire PR against your defined criteria.

**Best for:**

* Architecture boundaries ("domain layer must not import infrastructure")
* Code patterns ("avoid `==` in loop conditions")
* PR requirements ("every service file must have a test")
* Structural validation using variables like `fileDiff`, `pr_files_diff`

**How they work:**

* Applied at file-level or PR-level scope
* Run only during code review
* Support file references (`@file`, `@repo`) and MCP functions
* Produce suggestions with severity levels

## Memories

Memories are **persistent contextual instructions** injected across all interactions — code reviews, conversations, and AI suggestions. They represent the background knowledge Kody should carry about your codebase, conventions, and preferences.

**Best for:**

* Codebase context ("this repo mirrors a third-party API, so some external payload fields intentionally stay snake\_case")
* Suggestion preferences ("when suggesting JS utilities here, prefer native methods over Lodash")
* Migration context ("the billing module is mid-migration, so prefer incremental fixes over broad refactors")
* Architectural context ("this service follows hexagonal architecture and keeps adapters at the edge")

**How they work:**

* Injected as high-priority context in all prompts
* Improve future suggestions by grounding Kody in repo-specific context
* Created via conversation (`@kody remember: ...`) or manually in the UI
* Scoped to directory, repository, or organization level
* Kody auto-deduplicates and resolves conflicts between memories

## When to use which

| Scenario                                                                                        | Use         |
| ----------------------------------------------------------------------------------------------- | ----------- |
| Check if a test file exists for every service                                                   | Review Rule |
| "This repo mirrors an external API, so some response fields intentionally stay snake\_case"     | Memory      |
| PR description must follow a template                                                           | Review Rule |
| "Tests in this service usually live next to implementation files, not in a central test folder" | Memory      |
| Flag imports that violate architecture layers                                                   | Review Rule |
| "The auth module is mid-migration, so prefer incremental changes over broad refactors"          | Memory      |

## Can I convert between them?

Yes. In the Pending Memories modal, you can **convert a memory into a Review Rule** if you decide it needs more structured enforcement with file paths and severity levels.

For details, see [Kody Rules](/how_to_use/en/code_review/configs/kody_rules).


# How to automate code review on GitHub, GitLab, and Bitbucket
Source: https://docs.kodus.io/knowledge_base/en/how-to-automate-code-review

Set up AI-powered code review that runs automatically on every pull request across GitHub, GitLab, Bitbucket, and Azure DevOps.

Manual code reviews create bottlenecks. Reviewers context-switch, PRs queue up, and feedback quality varies. AI-powered code review runs instantly on every PR, catching issues before a human reviewer even looks at the code.

## How Kodus automates code review

Once connected, Kodus automatically reviews every pull request. It analyzes code for security vulnerabilities, performance issues, error handling, maintainability, and your custom rules — then posts comments directly in the PR.

### Supported platforms

* **GitHub** — via GitHub App
* **GitLab** — via OAuth + webhooks
* **Bitbucket** — via webhooks
* **Azure DevOps** — via webhooks

### What gets analyzed

By default, Kodus checks for:

* Security issues (SQL injection, XSS, hardcoded secrets)
* Performance problems (N+1 queries, missing indexes)
* Error handling gaps
* Potential bugs (null pointers, resource leaks)
* Code style and maintainability
* Your custom Kody Rules
* Business logic compliance (validates against linked task requirements)

### Review cadence options

| Mode           | Behavior                                                          |
| -------------- | ----------------------------------------------------------------- |
| **Automatic**  | Reviews every push — continuous feedback                          |
| **Auto-pause** | Pauses during rapid pushes (e.g., 3 in 15 minutes) to avoid noise |
| **Manual**     | Only reviews when you comment `@kody start-review`                |

## Getting started

1. Create a workspace at [kodus.io](https://kodus.io) or [self-host Kodus](/how_to_deploy/en/deploy_kodus/generic_vm)
2. Connect your Git provider (GitHub, GitLab, Bitbucket, or Azure DevOps)
3. Select which repositories to monitor
4. Open a PR — Kodus reviews it automatically

For platform-specific setup, see:

* [GitHub setup](/knowledge_base/en/how-to-set-up-ai-code-review-on-github)
* [GitLab setup](/knowledge_base/en/how-to-set-up-ai-code-review-on-gitlab)
* [Azure DevOps setup](/knowledge_base/en/how-to-set-up-ai-code-review-on-azure-devops)
* [Bitbucket setup](/how_to_deploy/en/platforms/bitbucket/bitbucket_webhook)


# How to check code against Google Docs specs
Source: https://docs.kodus.io/knowledge_base/en/how-to-check-code-against-google-docs

Validate your pull request implementation against specifications written in Google Docs.

Product specs and requirements often live in Google Docs. Kodus can fetch the document content and compare it against your PR diff to verify that the implementation matches the spec.

## How it works

1. **Connect the Google Docs plugin** in your workspace's [Plugins](/how_to_use/en/code_review/plugins) page
2. Make sure the document is accessible to the connected account
3. Comment on your PR:

```
@kody -v business-logic https://docs.google.com/document/d/1abc123/edit
```

4. Kody fetches the document, extracts the requirements, and compares them against the PR diff

## What you get

Kody produces a structured validation report:

* **Findings** with severity: MUST\_FIX, SUGGESTION, or INFO
* **Requirement tracing** — each finding quotes text from the Google Doc
* **Requirements Verified** — what was correctly implemented

## Tips

* Keep specs structured with clear sections and numbered requirements for best results
* You can also paste the spec content inline:

```
@kody -v business-logic
## Requirements
1. Users with role "admin" can delete any comment
2. Users can only edit their own comments within 24 hours
3. Deleted comments show "[removed]" placeholder
```

* Break large documents into sections and validate them individually for more focused feedback

For details, see [Business Logic Validation](/how_to_use/en/code_review/business_logic_validation).


# How to connect Jira to your code review tool
Source: https://docs.kodus.io/knowledge_base/en/how-to-connect-jira-to-code-review

Link Jira to Kodus so your AI code reviews automatically validate PRs against task requirements and acceptance criteria.

Connecting Jira to Kodus enables two powerful features: automatic **business logic validation** against Jira tickets, and richer context for code review suggestions.

## How to connect

1. Go to **Settings** → **Plugins**
2. Find **Jira** in the available plugins
3. Click **Connect** and authorize access to your Jira workspace
4. Select which projects Kodus can access

## What it enables

### Automatic business logic validation

When a PR is linked to a Jira ticket, Kodus automatically:

* Fetches the ticket title, description, and acceptance criteria
* Compares the PR diff against the requirements
* Reports missing implementations, scope mismatches, and gaps

### On-demand validation

Paste any Jira URL in a PR comment:

```
@kody -v business-logic https://your-org.atlassian.net/browse/PROJ-123
```

### Richer code review context

With Jira connected, Kody can use MCP functions in your rules to fetch task context, check issue status, and cross-reference requirements.

## Requirements

* Jira Cloud or Jira Data Center
* OAuth or API token access
* Permissions to read the relevant projects

For details on business logic validation, see [Business Logic Validation](/how_to_use/en/code_review/business_logic_validation). For plugin setup, see [Plugins](/how_to_use/en/code_review/plugins).


# How to connect Linear to your code review tool
Source: https://docs.kodus.io/knowledge_base/en/how-to-connect-linear-to-code-review

Link Linear to Kodus so your AI code reviews automatically validate PRs against issue requirements.

Connecting Linear to Kodus enables automatic **business logic validation** against Linear issues and richer context for code review suggestions.

## How to connect

1. Go to **Settings** → **Plugins**
2. Find **Linear** in the available plugins
3. Click **Connect** and authorize access
4. Select which workspaces Kodus can access

## What it enables

### Automatic business logic validation

When a PR is linked to a Linear issue, Kodus automatically:

* Fetches the issue title, description, and acceptance criteria
* Compares the PR diff against the requirements
* Reports missing implementations and gaps

### On-demand validation

Paste any Linear URL in a PR comment:

```
@kody -v business-logic https://linear.app/your-team/issue/TEAM-123
```

### Richer code review context

With Linear connected, Kody can reference task context in rules and conversations.

For details, see [Business Logic Validation](/how_to_use/en/code_review/business_logic_validation) and [Plugins](/how_to_use/en/code_review/plugins).


# How to create custom code review rules
Source: https://docs.kodus.io/knowledge_base/en/how-to-create-custom-code-review-rules

Define rules tailored to your team's architecture, patterns, and coding preferences that are enforced automatically on every PR.

Every team has conventions that generic linters don't cover — architecture boundaries, naming patterns, testing requirements, or business-specific constraints. Custom code review rules let you encode these into automated checks.

## Creating a rule in Kodus

1. Go to **Code Review Settings** → **Kody Rules**
2. Click **Add Rule**
3. Configure:
   * **Name** — what the rule checks (e.g., "Service files must have tests")
   * **Scope** — File-level (analyzes individual files) or PR-level (analyzes the entire PR)
   * **Path** — glob pattern to target specific files (e.g., `src/services/**/*.ts`)
   * **Severity** — Critical, High, Medium, or Low
   * **Instructions** — detailed description of what to check

## What makes rules powerful

Rules can access rich context:

* **Variables** like `fileDiff`, `pr_title`, `pr_description`, `pr_files_diff`
* **File references** with `@file:path/to/file.ts` to compare against patterns
* **MCP functions** to fetch data from connected tools (Jira, repository structure, etc.)

### Example: Architecture boundary rule

```
Name: Domain layer must not depend on infrastructure
Scope: Pull Request
Instructions: Check pr_files_diff for any import in src/domain/
that references src/infrastructure/. Reference
@file:docs/architecture.md for allowed dependencies.
```

### Example: Test coverage rule

```
Name: Every service must have a test file
Scope: Pull Request
Instructions: For each file modified in src/services/,
verify a corresponding test file exists in test/services/.
Use MCP to check the repository file tree.
```

## More ways to add rules

* **Import from Rules Library** — browse proven rules by language and category
* **Sync from IDE tools** — auto-import rules from Cursor, Copilot, Claude
* **Repository rules** — define rules in markdown files in your repo
* **Auto-generation** — Kody suggests rules based on your review history

For the full reference, see [Kody Rules](/how_to_use/en/code_review/configs/kody_rules).


# How to enforce coding standards in pull requests
Source: https://docs.kodus.io/knowledge_base/en/how-to-enforce-coding-standards-in-pull-requests

Learn how to automatically enforce your team's coding conventions, architecture rules, and best practices on every pull request.

Enforcing coding standards manually is time-consuming and inconsistent. Different reviewers catch different things, and conventions drift over time. The solution is to codify your standards into automated rules that run on every PR.

## How it works with Kodus

Kodus lets you define **Kody Rules** — custom instructions that are checked automatically during every code review. There are two types:

* **Review Rules** run during code review and analyze file diffs or the entire PR against your standards
* **Memories** are persistent conventions that Kody applies across all interactions — code reviews, conversations, and suggestions

### Example: Enforcing a naming convention

You can create a file-level rule like:

* **Rule**: "React components must use PascalCase file names"
* **Path**: `src/components/**/*.tsx`
* **Severity**: High
* **Instructions**: "Flag any component file that doesn't follow PascalCase naming."

### Example: Enforcing architectural boundaries

A PR-level rule can validate cross-file concerns:

* **Rule**: "Domain layer must not import from infrastructure"
* **Scope**: Pull Request
* **Instructions**: "Check `pr_files_diff` for any import statement in `src/domain/` that references `src/infrastructure/`. This violates our hexagonal architecture."

## Other approaches

You can also enforce standards by:

* **Importing from the Rules Library** — browse pre-built rules for security, performance, and style
* **Syncing IDE rules** — automatically import rules from Cursor, Copilot, Claude, and other AI tools
* **Repository rules** — define rules in markdown files directly in your repo (`kodus/rules/`)
* **Auto-generating rules** — let Kody analyze 3 months of review history and suggest rules based on your team's patterns

## Getting started

1. Go to **Code Review Settings** → **Kody Rules**
2. Click **Add Rule** and define your standard
3. Set the path, severity, and detailed instructions
4. Kody will enforce it on every future PR

For more details, see the [Kody Rules documentation](/how_to_use/en/code_review/configs/kody_rules).


# How to fix webhook issues with GitHub or GitLab
Source: https://docs.kodus.io/knowledge_base/en/how-to-fix-webhook-issues

Debug and resolve webhook connectivity problems between your Git provider and Kodus.

Webhooks are how Kodus knows when a PR is opened or updated. If they're not working, reviews won't trigger.

## Diagnosing the issue

### GitHub

1. Go to your repository **Settings** → **Webhooks**
2. Find the Kodus webhook
3. Click on it and check **Recent Deliveries**
4. Look for failed deliveries (non-2xx status codes)

### GitLab

1. Go to your project **Settings** → **Webhooks**
2. Find the Kodus webhook
3. Check the delivery history for errors

## Common fixes

### Webhook URL is wrong or outdated

If you changed your Kodus deployment URL, update the webhook URL in your Git provider settings.

### SSL certificate issues

If you're self-hosting, ensure your SSL certificate is valid. GitHub and GitLab reject webhooks with invalid certificates.

### Firewall blocking

If Kodus is behind a firewall, ensure your Git provider's IP ranges can reach the webhook endpoint.

### Webhook was deleted

Re-register the webhook by going through the Kodus setup flow again, or manually add the webhook URL.

## Testing

Most Git providers let you **redeliver** a recent webhook payload. Use this to test without creating a new PR.

For platform-specific guides, see:

* [GitHub webhooks](/how_to_deploy/en/platforms/github/github_webhook)
* [GitLab webhooks](/how_to_deploy/en/platforms/gitlab/gitlab_webhook)
* [Bitbucket webhooks](/how_to_deploy/en/platforms/bitbucket/bitbucket_webhook)


# How to generate code review rules automatically
Source: https://docs.kodus.io/knowledge_base/en/how-to-generate-rules-automatically

Let AI analyze your code review history and suggest custom rules based on your team's actual patterns and standards.

Writing code review rules from scratch can be tedious. Kodus can analyze your team's review history and automatically suggest rules based on the patterns it finds.

## How it works

1. Go to **Code Review Settings** → **Kody Rules**
2. Click **Generate Kody Rules**
3. Kodus scans 3 months of code review history in your repository
4. It identifies recurring feedback patterns and coding preferences
5. Generates rule suggestions tailored to your team

## What happens next

* Review the generated suggestions — they're not active yet
* Import the rules that match your team's needs
* Customize them if needed before activating
* Only imported rules are enforced during code reviews

## Continuous learning

After the initial setup, Kodus generates new rule suggestions **weekly** as your team's coding style evolves. Check back regularly for new suggestions.

## Requirements

* At least **3 months** of review history in the repository
* Regular code review activity for better pattern detection
* Repository access with proper permissions

For details, see [Automatic Rules Generation](/how_to_use/en/code_review/learning/kody_rules_generation).


# How to import rules from Cursor, Copilot, or Claude
Source: https://docs.kodus.io/knowledge_base/en/how-to-import-rules-from-ide-tools

Sync your existing AI coding tool rules into Kodus so the same standards apply in your IDE and in code review.

If you already have rules defined in Cursor, GitHub Copilot, Claude, or other AI coding tools, you can import them into Kodus so the same conventions are enforced during code review.

## How it works

Kodus detects rule files in your repository and offers to sync them as Kody Rules. Supported file formats include:

* `.cursorrules` (Cursor)
* `.github/copilot-instructions.md` (GitHub Copilot)
* `.claude` files (Claude)
* Other AI tool configuration files

## Setting it up

1. Go to **Code Review Settings** → **Kody Rules**
2. Kodus automatically detects compatible rule files in your repository
3. Review the detected rules and import the ones you want
4. Imported rules are added as Kody Rules and enforced during code review

## Why this matters

Without syncing, your IDE and code review tools enforce different standards. A developer following Cursor's rules might still get flagged during review for something their IDE didn't catch — or vice versa.

Importing ensures **one source of truth** for coding standards across your entire workflow.

For details, see [Sync IDE Rules](/how_to_use/en/code_review/configs/rules_file_detection).


# How to reduce code review noise and false positives
Source: https://docs.kodus.io/knowledge_base/en/how-to-reduce-code-review-noise

Fine-tune your AI code review to surface only the most relevant suggestions and avoid alert fatigue.

Too many low-priority suggestions can make developers ignore code review feedback entirely. The key is to tune the review so it surfaces what matters and stays quiet on what doesn't.

## Suggestion control

Kodus gives you fine-grained control over how many suggestions appear and at what severity:

* **Max suggestions per PR** — limit the total number of suggestions (e.g., 9)
* **Severity filter** — only show suggestions at or above a threshold (e.g., Medium and above)
* **Grouping mode** — control how suggestions are organized in the PR

Configure these in **Code Review Settings** → **Suggestion Control**, or in `kodus-config.yml`:

```yaml theme={null}
suggestionControl:
  groupingMode: full
  limitationType: pr
  maxSuggestions: 9
  severityLevelFilter: medium
```

## Ignore files and paths

Skip files that generate noise (lock files, generated code, configs):

```yaml theme={null}
ignorePaths:
  - yarn.lock
  - package-lock.json
  - "**/*.generated.ts"
  - dist/**
```

## Skip PRs by title

Skip PRs that don't need review (releases, version bumps):

```yaml theme={null}
ignoredTitleKeywords:
  - "release"
  - "bump version"
  - "chore"
```

## Toggle analysis categories

Disable entire review categories you don't need:

```yaml theme={null}
reviewOptions:
  security: true
  code_style: true
  refactoring: false        # disable if too noisy
  documentation_and_comments: false  # disable if not relevant
```

## Review cadence

Use **Auto-pause** to prevent spam during active development — Kodus pauses reviews when it detects rapid consecutive pushes (default: 3 pushes in 15 minutes).

For details, see [General Configuration](/how_to_use/en/code_review/configs/general) and [Suggestion Control](/how_to_use/en/code_review/configs/suggestion_control).


# How to review PRs with project-specific context
Source: https://docs.kodus.io/knowledge_base/en/how-to-review-prs-with-project-context

Give Kody access to your project docs, handbooks, and architecture guides for more relevant code reviews.

Generic code review catches generic issues. To get feedback that's actually relevant to your project, Kody needs to understand your specific context — architecture decisions, conventions, and business rules.

## Ways to provide context

### Memories

Teach Kody your conventions through conversation:

```
@kody remember: this project uses hexagonal architecture.
Domain layer must never depend on infrastructure.
```

Memories persist and are applied across all future reviews.

### File references in rules

Reference your own documentation directly in rules:

```
Instructions: Validate that new endpoints follow the patterns
in @file:docs/api-conventions.md and use the base classes
defined in @file:src/shared/base-controller.ts.
```

### Custom prompts

Add project-specific instructions that Kody includes in every review:

1. Go to **Code Review Settings** → **Custom Prompts**
2. Add context like architecture descriptions, team guidelines, or domain knowledge
3. Kody includes this in every code review analysis

### MCP plugins

Connect external tools to give Kody access to richer context:

* **Jira/Linear** — task requirements and acceptance criteria
* **Slack** — team discussions and decisions
* **Google Docs** — specs and design documents
* **Custom MCP servers** — any tool your team uses

## Example workflow

1. Define architecture rules via **Memories**: `@kody remember: we follow CQRS pattern in this service`
2. Create **Review Rules** that reference your docs: `@file:docs/architecture.md`
3. Connect **Jira** so Kody validates PRs against task requirements
4. Add **Custom Prompts** for domain-specific knowledge

For details, see [Custom Prompts](/how_to_use/en/code_review/configs/custom_prompts) and [Plugins](/how_to_use/en/code_review/plugins).


# How to self-host an AI code review tool
Source: https://docs.kodus.io/knowledge_base/en/how-to-self-host-ai-code-review

Deploy Kodus on your own infrastructure with full control over data, models, and configuration.

Kodus is open-source and can be self-hosted on your own infrastructure. This gives you full control over your data, network access, and LLM provider.

## Deployment options

### Docker (recommended)

Deploy Kodus using Docker Compose on any VM:

1. Clone the Kodus repository
2. Configure environment variables
3. Run `docker compose up`
4. Access the web UI and connect your Git provider

### Local development

For testing or contributing:

1. Use the orchestrator for a quick local setup
2. Includes all services in a single command

## What you control

* **Data** — all code and review data stays on your infrastructure
* **LLM provider** — use any provider or self-hosted models
* **Network** — runs behind your firewall, no external access required
* **Configuration** — full control over all settings

## Requirements

* Docker and Docker Compose
* Sufficient compute resources for the API and worker services
* Network access to your Git provider (GitHub, GitLab, Bitbucket)

For the full deployment guide, see [Deploy with Docker](/how_to_deploy/en/deploy_kodus/generic_vm).


# How to set up AI code review on Azure DevOps
Source: https://docs.kodus.io/knowledge_base/en/how-to-set-up-ai-code-review-on-azure-devops

Install and configure Kodus for Azure DevOps repositories to get automated AI code review on every pull request.

Kodus integrates with Azure DevOps via webhooks. Once configured, every pull request gets reviewed automatically.

## Steps

1. **Create an account** at [kodus.io](https://kodus.io) or [self-host Kodus](/how_to_deploy/en/deploy_kodus/generic_vm)
2. **Connect Azure DevOps** — authorize during setup and configure your Personal Access Token
3. **Configure webhooks** — follow the guided setup to enable pull request events
4. **Select repositories** — choose which Azure DevOps repositories Kodus should review
5. **Open a pull request** — Kodus reviews it automatically

## What you get

* Automated reviews on every PR
* Comments posted directly in the pull request
* Customizable rules and suggestion controls
* Business logic validation against linked work items

## Custom configuration

Drop a `kodus-config.yml` in your repo root to customize behavior per repository. The file overrides web settings automatically.

## Using a Personal Access Token

Azure DevOps requires a PAT for Kodus to access your repositories and post review comments. Make sure the token has the appropriate scopes for code read and PR comment access.

For the full setup guide, see [Azure DevOps Webhooks](/how_to_deploy/en/platforms/azure_devops/azdevops_webhook) and [Azure DevOps PAT](/how_to_use/en/code_review/general_config/azure_devops_pat).


# How to set up AI code review on GitHub
Source: https://docs.kodus.io/knowledge_base/en/how-to-set-up-ai-code-review-on-github

Install and configure Kodus for GitHub repositories to get automated AI code review on every pull request.

Setting up Kodus on GitHub takes a few minutes. Once connected, every pull request gets reviewed automatically.

## Steps

1. **Create an account** at [kodus.io](https://kodus.io) or [self-host Kodus](/how_to_deploy/en/deploy_kodus/generic_vm)
2. **Connect GitHub** — install the Kodus GitHub App when prompted during setup
3. **Select repositories** — choose which repositories Kodus should review
4. **Open a PR** — Kodus reviews it automatically and posts comments

## What you get

* Automated reviews on every PR (or on-demand with `@kody start-review`)
* Comments posted directly in the PR with code suggestions
* Customizable rules, severity filters, and suggestion limits
* Business logic validation against linked tasks

## Custom configuration

Drop a `kodus-config.yml` in your repo root to customize behavior per repository. The file overrides web settings automatically.

## Using a Personal Access Token

For private repositories or organizations with stricter permissions, you may need to configure a GitHub Personal Access Token (PAT).

For the full setup guide, see [Quickstart](/how_to_use/en/quickstart) and [GitHub App setup](/how_to_deploy/en/platforms/github/github_app).


# How to set up AI code review on GitLab
Source: https://docs.kodus.io/knowledge_base/en/how-to-set-up-ai-code-review-on-gitlab

Install and configure Kodus for GitLab projects to get automated AI code review on every merge request.

Kodus integrates with GitLab via OAuth and webhooks. Once configured, merge requests are reviewed automatically.

## Steps

1. **Create an account** at [kodus.io](https://kodus.io) or [self-host Kodus](/how_to_deploy/en/deploy_kodus/generic_vm)
2. **Connect GitLab** — authorize via OAuth during setup
3. **Configure webhooks** — follow the guided setup to enable merge request events
4. **Select projects** — choose which GitLab projects Kodus should review
5. **Open a merge request** — Kodus reviews it automatically

## What you get

* Automated reviews on every MR
* Comments posted directly in the merge request
* Customizable rules and suggestion controls
* Business logic validation against linked tasks

## Custom configuration

Drop a `kodus-config.yml` in your repo root to customize behavior per project.

For the full setup guide, see [GitLab OAuth](/how_to_deploy/en/platforms/gitlab/gitlab_oauth) and [GitLab Webhooks](/how_to_deploy/en/platforms/gitlab/gitlab_webhook).


# How to share coding standards across repositories
Source: https://docs.kodus.io/knowledge_base/en/how-to-share-standards-across-repositories

Use rule inheritance and organization-level rules to maintain consistent coding standards across all your repositories.

When you have multiple repositories, keeping coding standards consistent is a challenge. Kodus supports rule inheritance so you can define rules once and apply them everywhere.

## Organization-level rules

Create rules at the organization level and they automatically apply to all repositories:

1. Go to **Code Review Settings** → **Global** → **Kody Rules**
2. Create your rules — they apply to every repository in the organization
3. Individual repositories can inherit, override, or exclude specific rules

## Rule inheritance

Rules flow down from organization → repository → directory:

* **Organization rules** apply everywhere by default
* **Repository rules** can override or extend organization rules
* **Directory rules** can further specialize for specific paths

A repository can **exclude** an inherited rule if it doesn't apply to that codebase.

## Cross-repository references

Use `@repo:org/project` in rule instructions to reference files from other repositories:

```
Ensure API endpoints follow the pattern defined in @repo:team/api-standards.
```

This lets you maintain a central standards repository that all rules reference.

## Memories across the organization

Memories scoped to **organization level** apply across all repositories. For example:

```
@kody remember: across all repos, we use ESLint flat config format.
```

For details, see [Rules Inheritance](/how_to_use/en/code_review/configs/rules_inheritance).


# How to teach AI your team's coding conventions
Source: https://docs.kodus.io/knowledge_base/en/how-to-teach-ai-your-team-conventions

Use Memories to make Kody learn your coding preferences, architectural decisions, and team conventions through natural conversation.

Every team has unwritten context — technology preferences, naming conventions, architectural decisions, migration details. Instead of documenting them all upfront, you can teach Kody through natural conversation so future reviews are more relevant and repetitive bad suggestions go away.

## How it works

When you talk to Kody in PR comments, it detects when you're stating codebase context or a team preference and automatically saves it as a **Memory**. Memories are then applied as high-priority context in all future code reviews and conversations.

### Explicit teaching

Directly tell Kody to remember something:

```
@kody remember: this repo mirrors a third-party API, so some payload fields intentionally stay snake_case.
```

```
@kody please remember: this service follows hexagonal architecture and keeps adapters at the edge.
```

### Implicit learning

State a preference naturally — Kody picks it up:

```
@kody this repo mirrors a third-party API, so some payload fields intentionally stay snake_case.
```

```
@kody in this service, tests usually live next to the implementation files rather than in a central test folder.
```

```
@kody the billing module is mid-migration, so prefer incremental fixes over broad refactors.
```

## What Kody won't save

Kody is selective about what becomes a memory:

* Temporary instructions ("fix this now", "skip this for today")
* Questions ("what's the deadline?")
* Debugging chatter ("I see an error")
* Vague statements without actionable information
* Requests scoped to a single PR or task

## Memory scopes

Each memory applies at a specific level:

| Scope            | Example                                                       |
| ---------------- | ------------------------------------------------------------- |
| **Directory**    | "In `src/components/ui`, always use our design system tokens" |
| **Repository**   | "This repo uses hexagonal architecture"                       |
| **Organization** | "All repos use ESLint flat config"                            |

## Approval workflow

If you want to review AI-generated memories before they take effect, enable **LLM-generated memories approval** in settings. Memories will enter a pending state until you approve them.

## Managing memories

Go to **Code Review Settings** → **Kody Rules** → **Memories** tab to view, edit, or delete memories. You can also create memories manually from the UI.

For details, see [Kody Rules — Memories](/how_to_use/en/code_review/configs/kody_rules#memories).


# Chutes — Subscription-Capped Inference for Open-Source Models
Source: https://docs.kodus.io/knowledge_base/en/how-to-use-chutes-with-kodus

Learn how to connect Chutes AI's subscription plans — covering DeepSeek, Llama, Qwen, MiniMax and more — to Kodus.

## How Chutes works

Chutes AI is a decentralized serverless compute platform for open-source models. It exposes an **OpenAI-compatible** inference endpoint and offers **subscription plans** that bundle API usage up to a cap expressed as a multiple of the equivalent pay-per-token value — similar in structure to the Z.AI GLM Coding Plan, but covering the full open-source catalog (DeepSeek, Llama, Qwen, MiniMax, Kimi, and many more).

Kodus talks to Chutes through the same OpenAI-compatible adapter it uses for everything else, so there are no code changes — just BYOK credentials.

## Plans at a glance

<Info>
  Pricing and quota rules change. Always confirm at [chutes.ai/pricing](https://chutes.ai/pricing) before choosing a tier.
</Info>

Since early 2026, every Chutes subscription includes a usage allowance equal to **5× the equivalent pay-as-you-go value** of the tier, calculated from each model's per-million-token price.

Representative tiers (confirm current numbers on the pricing page):

| Tier       | Monthly fee | Notes                                                           |
| ---------- | ----------- | --------------------------------------------------------------- |
| Base       | \~\$3/mo    | Entry tier; limited model selection.                            |
| Standard   | \~\$10/mo   | Required for frontier models (DeepSeek V3, MiniMax M2.1, etc.). |
| Pro        | \~\$20+/mo  | Higher 5× cap for heavier review volume.                        |
| Enterprise | custom      | Contact Chutes.                                                 |

* The 5× cap resets monthly and is computed against the same per-token prices you'd pay pay-as-you-go.
* Some models require **Standard or higher** — the base tier does not carry frontier coding models.
* Chutes marks some models with a `-TEE` suffix indicating trusted-execution-environment (confidential compute) variants.

### Recommended models

Chutes uses HuggingFace-style `org/model` identifiers, sometimes with a `-TEE` suffix for the confidential-compute variant:

| Model id                              | Notes                                                                |
| ------------------------------------- | -------------------------------------------------------------------- |
| `deepseek-ai/DeepSeek-V3-0324-TEE`    | Frontier coding model; strong agentic behavior. Requires ≥ Standard. |
| `moonshotai/Kimi-K2-Instruct`         | Long-context Kimi K2 — great on large PRs.                           |
| `Qwen/Qwen3-Coder-480B-A35B-Instruct` | Specialized coder.                                                   |
| `chutes/MiniMaxAI/MiniMax-M2.1-TEE`   | Alternative frontier option.                                         |

See the live list and current pricing at [llm.chutes.ai/v1/models](https://llm.chutes.ai/v1/models).

## Creating an API Key

<Warning>A Chutes account with an active subscription (or pay-as-you-go balance) is required.</Warning>

1. Go to [chutes.ai](https://chutes.ai) and create an account.
2. Subscribe to a tier at [chutes.ai/pricing](https://chutes.ai/pricing), or enable pay-as-you-go if you prefer.
3. Open the developer console and create an API key. Copy it immediately.

## Configure Chutes in Kodus

### Option 1 — BYOK on Kodus Cloud (recommended)

1. In the Kodus web UI, open **Settings → BYOK** ([app.kodus.io/organization/byok](https://app.kodus.io/organization/byok)).

2. Chutes isn't in the curated catalog — click **Configure manually** at the bottom of the model list. Use `?slot=fallback` in the URL if configuring a fallback instead of the main model.

3. Fill the wizard:

   | Field                       | Value                                                                       |
   | --------------------------- | --------------------------------------------------------------------------- |
   | **Provider**                | `OpenAI Compatible`                                                         |
   | **Base URL**                | `https://llm.chutes.ai/v1`                                                  |
   | **Model**                   | e.g. `deepseek-ai/DeepSeek-V3-0324-TEE`                                     |
   | **API Key**                 | your Chutes API key                                                         |
   | **Max Concurrent Requests** | `3–5` is a safe start; raise if you don't hit cap (under Advanced settings) |

4. Click **Test & save**. Kodus probes the endpoint and persists the config on success.

<Tip>
  The 5× cap is computed from per-token prices. Expensive frontier models burn through the cap faster than small ones — if you want to maximize reviews per dollar, pair Chutes with a cheaper model (Llama, Qwen smaller variants) for routine PRs and save the frontier models for complex reviews via a Kody rule or separate BYOK profile.
</Tip>

<Note>
  Because Chutes runs on decentralized compute, cold-start and tail latency vary more than on dedicated providers. Configure an OpenAI or Anthropic key as **Fallback** so Kodus can fail over when a node is slow or the monthly cap is hit.
</Note>

### Option 2 — Self-hosted (environment variables)

If you run Kodus in Fixed Mode (single global provider, no per-org BYOK), configure Chutes in the `.env` of your API + worker containers:

```env theme={null}
# Chutes configuration (Fixed Mode)
API_LLM_PROVIDER_MODEL="deepseek-ai/DeepSeek-V3-0324-TEE"   # any model id from the catalog
API_OPENAI_FORCE_BASE_URL="https://llm.chutes.ai/v1"
API_OPEN_AI_API_KEY="your-chutes-api-key"
```

<Note>
  This path is only needed for self-hosted Kodus installs that deliberately disable BYOK. If BYOK is enabled on your self-hosted instance, prefer **Option 1** — the UI-based flow is the same as on Cloud.
</Note>

Restart the API and worker containers after editing `.env`, then verify:

```bash theme={null}
docker-compose logs api worker | grep -iE "chutes|llm\.chutes"
```

For the full self-hosted setup (domains, security keys, database, webhooks, reverse proxy), follow the [generic VM deployment guide](https://docs.kodus.io/docs/how_to_deploy/en/deploy_kodus/generic_vm) and only swap the LLM block for the one above.

## When to pick Chutes

* **You want the broadest open-source catalog at a subscription price** — frontier DeepSeek / MiniMax / Qwen at a flat fee with predictable caps.
* **You care about confidential compute** — Chutes offers `-TEE` variants that run inside trusted execution environments, useful if your compliance posture requires it.
* **You're running at low-to-mid volume** and fit within the 5× PAYG cap of a cheap tier.

Pick Synthetic instead if you want a simpler flat subscription with no per-model cap math. Pick Z.AI if your preferred model is the GLM family specifically.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Model requires higher tier">
    * Frontier models (DeepSeek V3, MiniMax M2.1, some Qwen variants) are gated to the Standard tier and above since Feb 2026.
    * Either upgrade, or pick a model available on your current tier (smaller Llama or Qwen variants).
  </Accordion>

  <Accordion title="Monthly 5× cap reached">
    * Check current usage in the Chutes dashboard.
    * Switch temporarily to a cheaper model to extend the cap, or upgrade tier.
    * Configure a `Fallback` BYOK provider so reviews keep running while you're capped.
  </Accordion>

  <Accordion title="401 / authentication errors">
    * Confirm the key is active in the Chutes dashboard and the subscription is current.
    * Make sure there are no trailing spaces or quotes in the `.env` value.
  </Accordion>

  <Accordion title="Model not found">
    * Chutes uses the `org/model` format, with some variants ending in `-TEE` (confidential compute). Double-check exact capitalization at [llm.chutes.ai/v1/models](https://llm.chutes.ai/v1/models).
  </Accordion>

  <Accordion title="Slow or inconsistent latency">
    * Chutes runs on decentralized compute, so tail latency is higher than on dedicated clouds.
    * For latency-sensitive reviews, prefer dedicated providers; reserve Chutes for overnight or batch review jobs, or configure a fast provider as `Main` and Chutes as `Fallback`.
  </Accordion>

  <Accordion title="Connection errors">
    * Confirm your server can reach `llm.chutes.ai`.
    * Review API and worker logs for the exact upstream error.
  </Accordion>
</AccordionGroup>

## Related

* [Chutes pricing](https://chutes.ai/pricing)
* [Chutes API reference](https://chutes.ai/docs/api-reference/overview)
* [Live model catalog](https://llm.chutes.ai/v1/models)
* [BYOK overview](/how_to_use/en/byok)


# Moonshot (Kimi) - OpenAI-Compatible Inference
Source: https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus

Learn how to connect Moonshot AI's Kimi K2.6 models to Kodus — via the Moonshot Developer API or the Kimi Code Plan.

## How Moonshot works

Moonshot AI publishes the **Kimi** family of models (K2, K2.5, K2.6, K2.6 Coding). Kimi is particularly strong on long-context code understanding and agentic workflows, and the API is fully OpenAI-compatible — Kodus talks to it via the `OpenAI Compatible` provider (or directly through the curated **Kimi K2.6 Coding** card in BYOK).

Moonshot offers **two paths** to the same model family, each with its own endpoint:

* **Developer API** (`platform.moonshot.ai`) — pay-per-token, billed per usage. Concurrency scales with your recharge tier.
* **Kimi Code Plan** (`kimi.com/code`) — subscription with a **dedicated coding endpoint**. Flat pricing, capped concurrency (30 concurrent).

<Note>
  Moonshot's consumer Kimi.com chat subscriptions (Andante, Moderato, etc.) are separate from both API paths. Chat subscriptions do **not** grant API access. Kimi Code Plan is the API-specific subscription.
</Note>

Moonshot also operates a China-only platform (`platform.moonshot.cn`, base URL `https://api.moonshot.cn/v1`) billed in CNY. Use that only if you operate inside mainland China.

## Plans at a glance

### Kimi Code Plan (subscription)

| Attribute       | Value                                      |
| --------------- | ------------------------------------------ |
| **Endpoint**    | `https://api.kimi.com/coding/v1`           |
| **Concurrency** | Capped at 30 concurrent requests           |
| **Billing**     | Flat-rate subscription                     |
| **Keys from**   | [kimi.com/code](https://www.kimi.com/code) |

### Developer API (pay-per-token)

| Model                              | Pricing (1M input / output tokens) | Context Window | Notes                               |
| ---------------------------------- | ---------------------------------- | -------------- | ----------------------------------- |
| **Kimi K2.6 Coding** `recommended` | \~$0.60 / $2.50                    | \~256k tokens  | Latest, tuned for code review.      |
| **Kimi K2.5**                      | $0.60 / $2.50                      | \~256k tokens  | Previous generation, still capable. |
| **Kimi K2 (0905)**                 | lower tier                         | \~128k tokens  | Stable general-purpose model.       |

Developer API endpoint: `https://api.moonshot.ai/v1` (international). Concurrency scales with recharge tier — Tier 1 (\$10 recharge) starts at \~50 concurrent, up to \~1000 concurrent on Tier 5.

## Creating an API Key

<Warning>A Moonshot account is required to create an API key.</Warning>

<Tabs>
  <Tab title="Kimi Code Plan subscriber">
    1. Go to [kimi.com/code](https://www.kimi.com/code) and subscribe to the plan.
    2. Open the key management area for your subscription.
    3. Create a Kimi Code key and copy it.

    <Note>
      Kimi Code keys only work against `https://api.kimi.com/coding/v1`. They will return 401 if sent to `api.moonshot.ai`.
    </Note>
  </Tab>

  <Tab title="Developer API (pay-per-token)">
    1. Sign in at [platform.moonshot.ai](https://platform.moonshot.ai) (or [platform.moonshot.cn](https://platform.moonshot.cn) if you operate inside mainland China).
    2. Add a payment method — Moonshot may grant a small starter balance when you first add billing.
    3. Open the **API Keys** section at [platform.moonshot.ai/console/api-keys](https://platform.moonshot.ai/console/api-keys).
    4. Click **Create API Key**, give it a descriptive name (e.g. `kodus-prod`), and copy the key immediately.

    <Note>
      Developer API keys only work against `api.moonshot.ai/v1` (international) or `api.moonshot.cn/v1` (China). Keys are **not** portable between regions.
    </Note>
  </Tab>
</Tabs>

## Configure Moonshot in Kodus

The primary flow is BYOK on Kodus Cloud — the curated **Kimi K2.6 Coding** card handles the endpoint swap for you. Self-hosted users who prefer fixing the provider at the process level can use environment variables instead.

### Option 1 — BYOK on Kodus Cloud (recommended)

<Steps>
  <Step title="Open BYOK and pick Kimi K2.6 Coding">
    Go to [app.kodus.io/organization/byok](https://app.kodus.io/organization/byok) and click the **Kimi K2.6 Coding** card in the Main model section.
  </Step>

  <Step title="Select your plan">
    The card expands with a **Plan** selector. Pick:

    * **Developer API** — if your key is from [platform.moonshot.ai](https://platform.moonshot.ai/console/api-keys)
    * **Kimi Code Plan** — if your key is from a [kimi.com/code](https://www.kimi.com/code) subscription

    The base URL and "Get a key" link update automatically.
  </Step>

  <Step title="Paste your API key">
    Just the key. For Kimi Code Plan users, Kodus pre-fills `maxConcurrentRequests=30` in Advanced settings (matches the documented cap).
  </Step>

  <Step title="Test & save">
    Click **Test & save**. Kodus probes the endpoint with a cheap metadata call and persists the config on success. 401 means the key doesn't match the selected plan's endpoint.
  </Step>
</Steps>

### Tuning reasoning (optional)

Reasoning is ON by default for Kimi K2.6 Coding — the curated card pre-fills **Thinking: Medium**, which for OpenAI-compatible providers emits `thinking: { type: "enabled" }`. Two common overrides:

* **Disable thinking** for faster/cheaper reviews on small PRs:

  ```json theme={null}
  {
    "thinking": { "type": "disabled" }
  }
  ```

* **Force a specific token budget** (if Moonshot adds support for `budget_tokens` on your tier):

  ```json theme={null}
  {
    "thinking": { "type": "enabled", "budget_tokens": 25000 }
  }
  ```

<Note>
  No namespace wrapping needed — Kodus auto-wraps under `openaiCompatible` (the active provider) before sending. See the [main BYOK doc → Custom JSON override](/how_to_use/en/byok#custom-json-override) for details.
</Note>

### Tuning concurrency

* **Kimi Code Plan**: keep the pre-filled `maxConcurrentRequests=30` (the documented cap). Going higher returns 429.
* **Developer API**: start empty (no cap). Your actual limit scales with your recharge tier — Tier 1 (\~$10 recharge) allows ~50 concurrent; Tier 5 (~$3000) allows \~1000. Lower it explicitly if you see 429s at review time.

<Note>
  Configure Kimi as **Main** and keep an OpenAI or Anthropic key as **Fallback** — if Moonshot returns 429 or 402, Kodus fails over automatically.
</Note>

### Option 2 — Manual configuration

If you need a Kimi variant not in the curated catalog (e.g. `kimi-k2.5` or `kimi-k2-0905`), click **Configure manually** at the bottom of the catalog and fill:

| Field                       | Value                                                                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provider**                | `OpenAI Compatible`                                                                                                                                         |
| **Base URL**                | `https://api.moonshot.ai/v1` (Developer API)<br />`https://api.kimi.com/coding/v1` (Kimi Code Plan)<br />`https://api.moonshot.cn/v1` (mainland China only) |
| **Model**                   | `kimi-k2.6`, `kimi-k2.6`, `kimi-k2.5`, `kimi-k2-0905`, `kimi-k2`                                                                                            |
| **API Key**                 | your Moonshot or Kimi Code key (matching the base URL above)                                                                                                |
| **Max Concurrent Requests** | `30` on Kimi Code Plan; leave empty on Developer API (scales with recharge tier)                                                                            |

### Option 3 — Self-hosted (environment variables)

If you run Kodus in Fixed Mode (single global provider, no per-org BYOK), configure Moonshot in the `.env` of your API + worker containers:

```env theme={null}
# Moonshot (Kimi) configuration (Fixed Mode)
API_LLM_PROVIDER_MODEL="kimi-k2.6"
API_OPENAI_FORCE_BASE_URL="https://api.moonshot.ai/v1"    # or https://api.kimi.com/coding/v1 for Kimi Code Plan
API_OPEN_AI_API_KEY="your-moonshot-or-kimi-code-api-key"
```

<Note>
  This path is only needed for self-hosted Kodus installs that deliberately disable BYOK. If BYOK is enabled on your self-hosted instance, prefer **Option 1** — the curated card handles the endpoint logic for you.
</Note>

Restart the API and worker containers after editing `.env`, then verify the integration:

```bash theme={null}
docker-compose logs api worker | grep -iE "moonshot|kimi"
```

For the full self-hosted setup (domains, security keys, database, webhooks, reverse proxy), follow the [generic VM deployment guide](https://docs.kodus.io/docs/how_to_deploy/en/deploy_kodus/generic_vm) and only swap the LLM block for the one above.

## Choosing between Kimi Code Plan, Developer API, and aggregators

* **Kimi Code Plan** — predictable flat-rate cost, 30-concurrent cap, dedicated `api.kimi.com/coding/v1` endpoint optimized for coding workflows. Best for steady-state teams with predictable PR volume.
* **Moonshot Developer API** — pay-per-token, concurrency scales with recharge tier, largest flexibility. Best for bursty workloads.
* **OpenRouter proxy** — if you want one billing relationship across many providers, OpenRouter exposes Kimi models with a small routing markup. Pick this when Kimi is part of a mixed-provider fleet, not a primary workload.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 after Test — key doesn't match endpoint">
    * Kimi Code Plan keys only work against `api.kimi.com/coding/v1`.
    * Developer API keys from `platform.moonshot.ai` only work against `api.moonshot.ai/v1`.
    * Developer API keys from `platform.moonshot.cn` only work against `api.moonshot.cn/v1`.
    * In the curated card, confirm the **Plan** selector matches your key origin.
  </Accordion>

  <Accordion title="Insufficient balance">
    * Developer API bills pay-per-token. If balance runs out, requests return HTTP 402.
    * Add funds in the billing section of the console or set a monthly cap to avoid surprises.
    * Kimi Code Plan has flat pricing but is bound by its 30-concurrent cap and quota windows — 429 means you've hit one.
  </Accordion>

  <Accordion title="Model not found">
    * Confirm the model name matches the catalog (`kimi-k2.6`, `kimi-k2.6`, `kimi-k2.5`, `kimi-k2-0905`, `kimi-k2`).
    * Check [platform.kimi.ai/docs](https://platform.kimi.ai/docs) for the current list — new versions ship regularly.
  </Accordion>

  <Accordion title="Slow first response">
    * First call after idle periods may cold-start on Moonshot's side.
    * If latency matters, `kimi-k2-0905` is generally faster than the K2.6 variants for routine reviews.
  </Accordion>

  <Accordion title="Region / connectivity">
    * Users outside China should always use `api.moonshot.ai` or `api.kimi.com`. `api.moonshot.cn` may be unreachable or rate-limited from outside mainland China.
    * Confirm outbound HTTPS to the chosen endpoint is allowed from your Kodus deployment.
  </Accordion>
</AccordionGroup>

## Related

* [Moonshot platform (international)](https://platform.moonshot.ai)
* [Kimi Code Plan](https://www.kimi.com/code)
* [Kimi API documentation](https://platform.kimi.ai/docs)
* [BYOK overview](/how_to_use/en/byok)


# Synthetic — Flat-Rate Subscription for Open-Source Coding Models
Source: https://docs.kodus.io/knowledge_base/en/how-to-use-synthetic-with-kodus

Learn how to connect Synthetic.new's subscription-based API — bundling Kimi, DeepSeek, Qwen Coder, GLM and more — to Kodus.

## How Synthetic works

Synthetic is a subscription service that runs open-source coding LLMs on dedicated infrastructure and serves them over an **OpenAI-compatible** (and Anthropic-compatible) API. Instead of paying per-token, you pay a **flat monthly subscription** and get a generous rate-limit budget covering every model on the platform.

It's positioned as a direct alternative to Claude's $20/month and $200/month plans for developers who do a lot of coding: the same price point, several-times-higher rate limits, and your choice of open-source models.

Kodus reaches Synthetic through the OpenAI-compatible endpoint, so there are no adapter changes — just BYOK credentials.

## Plans at a glance

<Info>
  Pricing and rate limits change. Always confirm at [synthetic.new/pricing](https://synthetic.new/pricing) before choosing a tier.
</Info>

### Subscription (recommended for code review)

| Plan                         | Price             | Rate limit                       |
| ---------------------------- | ----------------- | -------------------------------- |
| **Monthly**                  | \~$30/mo ($1/day) | \~500 messages per 5-hour window |
| **Enterprise / usage-based** | contact Synthetic | pay-per-token option             |

* All standard models are covered by the subscription — pick any of them by changing the `model` field.
* Rate limits are enforced on a **5-hour rolling window**, not per month — plan concurrency to fit inside that window.
* Synthetic does not train on your prompts/completions and deletes API data within 14 days.

### Recommended models

Synthetic exposes models using a HuggingFace-style prefix (`hf:org/model`). A few strong picks for code review:

| Model id                                 | Notes                                            |
| ---------------------------------------- | ------------------------------------------------ |
| `hf:zai-org/GLM-4.6`                     | GLM family; balanced for general-purpose review. |
| `hf:moonshotai/Kimi-K2-Instruct`         | Long-context Kimi K2 — great on large PRs.       |
| `hf:Qwen/Qwen3-Coder-480B-A35B-Instruct` | Strong specialized coder.                        |
| `hf:deepseek-ai/DeepSeek-V3.1`           | DeepSeek V3.1; strong agentic/coding behavior.   |

See the full catalog at [dev.synthetic.new/docs/openai/models](https://dev.synthetic.new/docs/openai/models).

## Creating an API Key

<Warning>A Synthetic account with an active subscription is required to use the API.</Warning>

1. Go to [synthetic.new](https://synthetic.new) and sign up or log in.
2. Subscribe to a plan at [synthetic.new/pricing](https://synthetic.new/pricing).
3. Open the developer console and create an API key. Copy it immediately — you will not see the full key again.

## Configure Synthetic in Kodus

The primary flow is BYOK on Kodus Cloud. Self-hosted installs can use environment variables as a secondary option.

### Option 1 — BYOK on Kodus Cloud (recommended)

1. In the Kodus web UI, open **Settings → BYOK** ([app.kodus.io/organization/byok](https://app.kodus.io/organization/byok)).

2. Synthetic isn't in the curated catalog — click **Configure manually** at the bottom of the model list. Use `?slot=fallback` in the URL if configuring a fallback instead of the main model.

3. Fill the wizard:

   | Field                       | Value                                                                           |
   | --------------------------- | ------------------------------------------------------------------------------- |
   | **Provider**                | `OpenAI Compatible`                                                             |
   | **Base URL**                | `https://api.synthetic.new/openai/v1`                                           |
   | **Model**                   | e.g. `hf:zai-org/GLM-4.6` (use the `hf:` prefix and the full HuggingFace path)  |
   | **API Key**                 | your Synthetic API key                                                          |
   | **Max Concurrent Requests** | start at `3–5` to fit the 5-hour budget on bigger PRs (under Advanced settings) |

4. Click **Test & save**. Kodus probes the endpoint and persists the config on success. 401 means the key is wrong; 404 usually means the base URL or model path is wrong.

<Tip>
  The 500-messages-per-5-hours budget is per subscription, not per PR. For teams doing heavy continuous review, keep `Max Concurrent Requests` low enough that one big multi-file PR doesn't eat the window, or split the work across multiple subscriptions.
</Tip>

<Note>
  Configure Synthetic as **Main** and keep an OpenAI or Anthropic key as **Fallback** — when the 5-hour window fills up, Kodus automatically fails over and reviews keep flowing.
</Note>

### Option 2 — Self-hosted (environment variables)

If you run Kodus in Fixed Mode (single global provider, no per-org BYOK), configure Synthetic in the `.env` of your API + worker containers:

```env theme={null}
# Synthetic configuration (Fixed Mode)
API_LLM_PROVIDER_MODEL="hf:zai-org/GLM-4.6"                    # any model id from the catalog
API_OPENAI_FORCE_BASE_URL="https://api.synthetic.new/openai/v1"
API_OPEN_AI_API_KEY="your-synthetic-api-key"
```

<Note>
  This path is only needed for self-hosted Kodus installs that deliberately disable BYOK. If BYOK is enabled on your self-hosted instance, prefer **Option 1** — the UI-based flow is the same as on Cloud.
</Note>

Restart the API and worker containers after editing `.env`, then verify:

```bash theme={null}
docker-compose logs api worker | grep -iE "synthetic|api\.synthetic"
```

For the full self-hosted setup (domains, security keys, database, webhooks, reverse proxy), follow the [generic VM deployment guide](https://docs.kodus.io/docs/how_to_deploy/en/deploy_kodus/generic_vm) and only swap the LLM block for the one above.

## When to pick Synthetic

* **Your primary model is open-source** (Kimi, DeepSeek, Qwen Coder, GLM) and you want a single flat-rate bill instead of juggling per-provider token spend.
* \*\*You're comparing to Claude Max ($200/mo)** for review throughput — Synthetic at $30/mo delivers several times the rate-limit budget for similarly-capable coding models.
* **You want strong data posture** — Synthetic is explicit about no-training and 14-day prompt/completion retention.

Pick pay-per-token (Moonshot, Fireworks, Together, Groq) instead if traffic is bursty, or a different subscription (Z.AI GLM Coding Plan) if you specifically want the GLM family with tiered commits.

## Troubleshooting

<AccordionGroup>
  <Accordion title="429 Too Many Requests inside the 5-hour window">
    * The subscription budget is per **5-hour rolling window**, not per hour or per month. Check how many requests you've sent recently in the Synthetic dashboard.
    * Either wait for the window to roll forward, lower `Max Concurrent Requests` in BYOK, or upgrade/stack plans.
    * Configure a `Fallback` BYOK provider so reviews keep running while you're rate-limited.
  </Accordion>

  <Accordion title="401 / authentication errors">
    * Confirm the key is active and the subscription is current in the Synthetic dashboard.
    * Make sure there are no trailing spaces or quotes in the `.env` value.
  </Accordion>

  <Accordion title="Model not found">
    * Synthetic uses the `hf:org/model` format. Leaving off the `hf:` prefix or using a different capitalization will 404.
    * Cross-check against [dev.synthetic.new/docs/openai/models](https://dev.synthetic.new/docs/openai/models).
  </Accordion>

  <Accordion title="Long cold-start on first call">
    * Some larger models may cold-start the first time they're used after a period of inactivity.
    * If first-call latency is blocking Kodus health checks, warm the model by issuing a tiny test request before opening PRs.
  </Accordion>

  <Accordion title="Connection errors">
    * Confirm your server can reach `api.synthetic.new`.
    * Review API and worker logs for the exact upstream error.
  </Accordion>
</AccordionGroup>

## Related

* [Synthetic pricing](https://synthetic.new/pricing)
* [Synthetic API docs](https://dev.synthetic.new/docs/api/getting-started)
* [Synthetic model catalog](https://dev.synthetic.new/docs/openai/models)
* [BYOK overview](/how_to_use/en/byok)


# Z.AI (GLM Coding Plan) - Subscription-Based Inference
Source: https://docs.kodus.io/knowledge_base/en/how-to-use-z-ai-with-kodus

Learn how to connect Z.AI's GLM models — including the GLM Coding Plan subscription — to Kodus.

## How Z.AI works

Z.AI (developed by Zhipu AI) serves the GLM family of models. It's one of the few major providers offering a **flat-rate subscription** for API access: the **GLM Coding Plan** bundles model usage at a fixed monthly price, with rate limits applied over 5-hour and weekly windows instead of per-token billing.

For higher-volume or variable workloads, Z.AI also offers pay-per-token access to the same models on its standard Developer API.

Both paths expose an OpenAI-compatible endpoint, so Kodus talks to them via the `OpenAI Compatible` provider (or directly through the curated **GLM 5.1** card in BYOK).

## Plans at a glance

<Info>
  Pricing and quotas change regularly. Always confirm current numbers at [z.ai/subscribe](https://z.ai/subscribe) and [docs.z.ai](https://docs.z.ai/devpack/overview) before choosing a tier.
</Info>

### GLM Coding Plan (subscription)

| Tier     | Price (monthly equivalent)   | Approximate API-value equivalent | Concurrency         |
| -------- | ---------------------------- | -------------------------------- | ------------------- |
| **Lite** | \~\$18/mo (billed quarterly) | \~15× the monthly fee            | \~1 concurrent      |
| **Pro**  | \~\$30/mo (billed quarterly) | \~20× the monthly fee            | \~1 concurrent      |
| **Max**  | \~\$80/mo (billed quarterly) | \~30× the monthly fee            | up to 30 concurrent |

* Quotas reset on a rolling **5-hour** window and a **weekly** window — plan around the ceiling, not a monthly cap.
* Coverage includes GLM-5.1, GLM-5-Turbo, GLM-5, GLM-4.5, and GLM-4.5-Air.
* Dedicated endpoint: `https://api.z.ai/api/coding/paas/v4` — Coding Plan keys **only work here**.

### Pay-per-token Developer API

| Model                     | Pricing (1M input / output tokens) | Context Window |
| ------------------------- | ---------------------------------- | -------------- |
| **GLM-5.1** `recommended` | $0.95 / $3.15                      | \~200k tokens  |
| **GLM-5**                 | $0.72 / $2.30                      | \~131k tokens  |
| **GLM-4.5**               | $0.60 / $2.20                      | \~128k tokens  |
| **GLM-4.5-Air**           | lower tier, optimized for routing  | \~128k tokens  |

Standard endpoint: `https://api.z.ai/api/paas/v4/` (OpenAI-compatible).

## Creating an API Key

<Warning>A Z.AI account is required to create an API key.</Warning>

<Tabs>
  <Tab title="Coding Plan subscriber">
    1. Sign in at [z.ai](https://z.ai).
    2. Purchase a **GLM Coding Plan** tier at [z.ai/subscribe](https://z.ai/subscribe).
    3. Open the key management page for your subscription and create a Coding Plan key.
    4. Copy the key — you will not be able to see it again.

    <Note>
      Coding Plan keys are tied to the `/api/coding/paas/v4` endpoint. They **will return 401** if sent against the standard `/api/paas/v4/` endpoint.
    </Note>
  </Tab>

  <Tab title="Developer API (pay-per-token)">
    1. Sign in at [z.ai](https://z.ai).
    2. Open the **API Keys** section at [z.ai/manage-apikey/apikey-list](https://z.ai/manage-apikey/apikey-list).
    3. Click **Create API Key**, give it a descriptive name (e.g. `kodus-prod`), and copy the key.

    <Note>
      Developer API keys are tied to the `/api/paas/v4/` endpoint.
    </Note>
  </Tab>
</Tabs>

## Configure Z.AI in Kodus

The primary flow is BYOK on Kodus Cloud — the curated **GLM 5.1** card handles the endpoint swap for you. Self-hosted users who prefer fixing the provider at the process level can use environment variables instead.

### Option 1 — BYOK on Kodus Cloud (recommended)

<Steps>
  <Step title="Open BYOK and pick GLM 5.1">
    Go to [app.kodus.io/organization/byok](https://app.kodus.io/organization/byok) and click the **GLM 5.1** card in the Main model section.
  </Step>

  <Step title="Select your plan">
    The card expands with a **Plan** selector. Pick:

    * **Developer API** — if your key is from [z.ai/manage-apikey](https://z.ai/manage-apikey/apikey-list)
    * **Coding Plan** — if your key is from a [GLM Coding Plan subscription](https://z.ai/subscribe)

    The base URL and "Get a key" link update automatically to match your plan.
  </Step>

  <Step title="Paste your API key">
    Just the key — nothing else to configure. For Coding Plan users, Kodus pre-fills `maxConcurrentRequests=1` in Advanced settings, which matches Lite/Pro tier limits. Bump this up to 30 if you're on Max.
  </Step>

  <Step title="Test & save">
    Click **Test & save**. Kodus probes the endpoint with a cheap metadata call and persists the config on success. 401 means the key doesn't match the selected plan's endpoint; 404 means the base URL is wrong.
  </Step>
</Steps>

### Tuning reasoning (optional)

The curated GLM 5.1 card pre-fills **Thinking: Medium**, which for OpenAI-compatible providers emits `thinking: { type: "enabled" }`. That's fine for most workloads. Two cases to override:

* **Force a specific token budget** — switch **Thinking** to **Custom** under Advanced settings and paste:

  ```json theme={null}
  {
    "thinking": { "type": "enabled", "budget_tokens": 20000 }
  }
  ```

* **Disable thinking** — for fastest/cheapest reviews on small PRs:

  ```json theme={null}
  {
    "thinking": { "type": "disabled" }
  }
  ```

<Note>
  No namespace wrapping needed — Kodus auto-wraps under `openaiCompatible` (the active provider) before sending. See the [main BYOK doc → Custom JSON override](/how_to_use/en/byok#custom-json-override) for details.
</Note>

### Tuning concurrency

* **Coding Plan Lite / Pro**: keep the pre-filled `maxConcurrentRequests=1`. Going higher returns `429 Too much concurrency`.
* **Coding Plan Max**: raise to `5` first, up to `30` if you don't see 429s. Max tier allows up to 30 concurrent.
* **Developer API**: start empty (no cap). Drop to `5` if you see rate-limit errors, then tune up.

<Note>
  Configure GLM 5.1 as your **Main** model and keep an OpenAI or Anthropic key as **Fallback** so that reviews keep running when your Coding Plan 5-hour window is exhausted. Kodus fails over automatically.
</Note>

### Option 2 — Manual configuration

If you need a GLM variant not in the curated catalog (e.g. GLM-5 or GLM-4.5), click **Configure manually** at the bottom of the catalog and fill:

| Field                       | Value                                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Provider**                | `OpenAI Compatible`                                                                                      |
| **Base URL**                | `https://api.z.ai/api/coding/paas/v4` (Coding Plan)<br />`https://api.z.ai/api/paas/v4/` (Developer API) |
| **Model**                   | `glm-5.1`, `glm-5`, `glm-5-turbo`, `glm-4.5`, `glm-4.5-air`                                              |
| **API Key**                 | your Z.AI key (matching the base URL above)                                                              |
| **Max Concurrent Requests** | `1` on Lite/Pro Coding Plan; up to `30` on Max; leave empty on Developer API                             |

### Option 3 — Self-hosted (environment variables)

If you run Kodus in Fixed Mode (single global provider, no per-org BYOK), configure Z.AI in the `.env` of your API + worker containers:

```env theme={null}
# Z.AI configuration (Fixed Mode)
API_LLM_PROVIDER_MODEL="glm-5.1"                                  # any GLM model you have access to
API_OPENAI_FORCE_BASE_URL="https://api.z.ai/api/coding/paas/v4"   # use /api/paas/v4/ for pay-per-token
API_OPEN_AI_API_KEY="your-z-ai-api-key"
```

<Note>
  This path is only needed for self-hosted Kodus installs that deliberately disable BYOK. If BYOK is enabled on your self-hosted instance, prefer **Option 1** — the curated card handles the endpoint logic for you.
</Note>

Restart the API and worker containers after editing `.env`, then verify the integration:

```bash theme={null}
docker-compose logs api worker | grep -iE "z\.ai|glm"
```

For the full self-hosted setup (domains, security keys, database, webhooks, reverse proxy), follow the [generic VM deployment guide](https://docs.kodus.io/docs/how_to_deploy/en/deploy_kodus/generic_vm) and only swap the LLM block for the one above.

## Choosing between the Coding Plan and pay-per-token

* Pick the **Coding Plan** when you have a predictable team of reviewers and want a flat monthly cost. The 5-hour and weekly quotas translate to roughly 15–30× the subscription fee in equivalent API spend.
* Pick **pay-per-token** when your traffic is bursty, when you need occasional access to the largest context windows, or when you want cost to scale linearly with PR volume.
* **Pair them**: use the Coding Plan as Main and a Developer API key (or an entirely different provider) as Fallback to cover bursts that exhaust your subscription window.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 after Test — key doesn't match endpoint">
    * Coding Plan keys only work on `/api/coding/paas/v4`. Developer API keys only work on `/api/paas/v4/`.
    * In the curated card, confirm the **Plan** selector matches the key type.
    * In manual mode, confirm the Base URL matches the key origin.
  </Accordion>

  <Accordion title="'Too much concurrency' at review time">
    * Lite and Pro Coding Plan tiers typically allow only **1 concurrent request**. Kodus pre-fills this for you; raise it only on Max.
    * Lower **Max concurrent requests** in Advanced settings if you're still hitting 429s.
  </Accordion>

  <Accordion title="Quota exhausted on the Coding Plan">
    * Quotas are enforced on a **5-hour rolling window** and a **weekly window**. Hitting one of them returns HTTP 429.
    * Check remaining quota in the Z.AI console.
    * Options: wait for the next window, upgrade to a higher tier, or have a Developer API key configured as Fallback to cover the gap.
  </Accordion>

  <Accordion title="Model not found">
    * Verify the model ID matches Z.AI's catalog (`glm-5.1`, `glm-5-turbo`, `glm-5`, `glm-4.5`, `glm-4.5-air`).
    * The Coding Plan currently covers only the GLM family — non-GLM model names will be rejected.
  </Accordion>

  <Accordion title="Connection errors (timeout, DNS)">
    * Confirm your server can reach `api.z.ai`.
    * Check the API and worker logs for the exact upstream error.
    * If you are in a region with restricted outbound traffic, route requests through a reverse proxy your infra allows.
  </Accordion>
</AccordionGroup>

## Related

* [GLM Coding Plan (pricing)](https://z.ai/subscribe)
* [Z.AI developer documentation](https://docs.z.ai/devpack/overview)
* [BYOK overview](/how_to_use/en/byok)


# How to validate business rules before merging
Source: https://docs.kodus.io/knowledge_base/en/how-to-validate-business-rules-before-merging

Catch missing requirements, forgotten edge cases, and logic gaps in your pull request before code reaches production.

Code reviews typically focus on code quality — security, performance, style. But they often miss the question: **does this code actually do what the business asked for?** Business Logic Validation bridges that gap.

## What it checks

Kodus compares your PR diff against the task requirements and identifies:

* **Missing implementations** — acceptance criteria not covered in the code
* **Partial implementations** — requirements only partially addressed
* **Scope mismatches** — when the PR is working in a different area than the task describes
* **Edge cases** — business scenarios mentioned in the task but not handled

## How to use it

### Automatic (default)

With `business_logic: true` in your review options (enabled by default), Kodus automatically validates business rules during every PR review when a task management plugin is connected.

### On-demand

Comment on any PR with a link or inline spec:

```
@kody -v business-logic https://kodustech.atlassian.net/browse/KC-1292
```

```
@kody -v business-logic
Orders above $500 must issue cashback credits.
Discount codes cannot be combined with loyalty rewards.
Free shipping applies only to domestic orders.
```

## Supported task sources

Connect via [Plugins](/how_to_use/en/code_review/plugins) to fetch task context automatically:

| Source          | How to reference                              |
| --------------- | --------------------------------------------- |
| **Jira**        | Paste the Jira issue URL                      |
| **Linear**      | Paste the Linear issue URL                    |
| **Notion**      | Paste the Notion page URL                     |
| **ClickUp**     | Paste the ClickUp task URL                    |
| **Google Docs** | Paste the document URL                        |
| **Slack**       | Paste a Slack message permalink               |
| **Inline**      | Write requirements directly in the PR comment |

## Understanding the output

Each finding has a severity:

* **MUST\_FIX** — a required business rule is missing or contradicted
* **SUGGESTION** — an edge case or robustness point is not covered
* **INFO** — observation that doesn't block compliance

Every finding includes the **exact quote** from the task that establishes the requirement, ensuring nothing is invented.

## Tips

* Tasks with explicit acceptance criteria get the most thorough validation
* After fixing issues, rerun the command to confirm compliance
* If the PR scope doesn't match the task, Kody flags a scope mismatch instead of speculating

For details, see [Business Logic Validation](/how_to_use/en/code_review/business_logic_validation).


# How to validate if a PR implements a Jira ticket
Source: https://docs.kodus.io/knowledge_base/en/how-to-validate-pr-against-jira-ticket

Use Kodus to compare your pull request against Jira acceptance criteria and catch missing requirements before merging.

You wrote the code, but did it actually implement everything the Jira ticket asked for? Business Logic Validation compares your PR diff against the task requirements and flags anything missing, incomplete, or misaligned.

## How it works

1. **Connect the Jira plugin** in your workspace's [Plugins](/how_to_use/en/code_review/plugins) page
2. Comment on your PR:

```
@kody -v business-logic https://kodustech.atlassian.net/browse/KC-1292
```

3. Kody fetches the Jira ticket (title, description, acceptance criteria), reads the PR diff, and compares them

## What you get

Kody produces a structured report with:

* **Status** — Issues Found or Compliant
* **Findings** with severity levels:
  * **MUST\_FIX** — a required business rule is not implemented
  * **SUGGESTION** — an edge case or robustness point is not covered
  * **INFO** — useful observation that doesn't block compliance
* **Requirement tracing** — each finding quotes the exact requirement from the Jira ticket
* **Requirements Verified** — what was correctly implemented, with file/line references

## Automatic validation

With `business_logic: true` in your review options (enabled by default), Kody automatically validates against linked tasks during every PR review — no manual command needed.

## Tips for best results

* Add **acceptance criteria** to your Jira tickets — tasks with explicit criteria get criterion-by-criterion validation
* If the PR scope doesn't match the ticket, Kody detects the **scope mismatch** instead of producing misleading findings
* You can re-run the validation after addressing findings to confirm compliance

For details, see [Business Logic Validation](/how_to_use/en/code_review/business_logic_validation).


# How to validate Linear issues against pull requests
Source: https://docs.kodus.io/knowledge_base/en/how-to-validate-pr-against-linear-issue

Ensure your pull request implements what the Linear issue describes by using AI-powered business logic validation.

Linear issues often contain detailed requirements, acceptance criteria, and scope definitions. Kodus can compare your PR against the Linear issue to catch gaps before merging.

## How it works

1. **Connect the Linear plugin** in your workspace's [Plugins](/how_to_use/en/code_review/plugins) page
2. Comment on your PR:

```
@kody -v business-logic https://linear.app/your-team/issue/TEAM-123
```

3. Kody fetches the Linear issue context, reads the PR diff, and produces a gap analysis

## What you get

* **Findings** with severity: MUST\_FIX, SUGGESTION, or INFO
* **Requirement tracing** — each finding quotes the exact text from the Linear issue
* **Scope mismatch detection** — if the PR is working in a different domain than the issue
* **Requirements Verified** — what was correctly implemented

## Automatic validation

When `business_logic: true` is enabled (default), Kody automatically retrieves task context from Linear during every PR review if the plugin is connected.

## Tips

* Write clear acceptance criteria in your Linear issues for the most thorough validation
* You can also paste requirements inline if you prefer not to link the issue:

```
@kody -v business-logic Orders above $500 must issue cashback credits.
Discount codes cannot be combined with loyalty rewards.
```

For details, see [Business Logic Validation](/how_to_use/en/code_review/business_logic_validation).


# Knowledge Base
Source: https://docs.kodus.io/knowledge_base/en/introduction

Answers to common questions about AI code review, coding standards enforcement, business logic validation, and more.

## Code Review

<CardGroup>
  <Card title="How to enforce coding standards in pull requests" href="/knowledge_base/en/how-to-enforce-coding-standards-in-pull-requests">
    Automatically enforce your team's coding conventions on every PR using custom rules.
  </Card>

  <Card title="How to automate code review on GitHub, GitLab, and Bitbucket" href="/knowledge_base/en/how-to-automate-code-review">
    Set up AI-powered code review that runs automatically on every pull request.
  </Card>

  <Card title="How to create custom code review rules" href="/knowledge_base/en/how-to-create-custom-code-review-rules">
    Define rules tailored to your team's architecture, patterns, and preferences.
  </Card>

  <Card title="How to reduce code review noise and false positives" href="/knowledge_base/en/how-to-reduce-code-review-noise">
    Fine-tune suggestion limits, severity filters, and ignored paths to keep reviews focused.
  </Card>

  <Card title="What is the difference between Review Rules and Memories" href="/knowledge_base/en/difference-between-review-rules-and-memories">
    Understand when to use each type of Kody Rule for the best results.
  </Card>

  <Card title="How to teach AI your team's coding conventions" href="/knowledge_base/en/how-to-teach-ai-your-team-conventions">
    Use Memories to make Kody learn your coding preferences through natural conversation.
  </Card>
</CardGroup>

## Business Logic Validation

<CardGroup>
  <Card title="How to validate if a PR implements a Jira ticket" href="/knowledge_base/en/how-to-validate-pr-against-jira-ticket">
    Compare your pull request against Jira acceptance criteria before merging.
  </Card>

  <Card title="How to validate Linear issues against pull requests" href="/knowledge_base/en/how-to-validate-pr-against-linear-issue">
    Ensure your PR implements what the Linear issue describes.
  </Card>

  <Card title="How to check code against Google Docs specs" href="/knowledge_base/en/how-to-check-code-against-google-docs">
    Validate implementation against specifications written in Google Docs.
  </Card>

  <Card title="How to validate business rules before merging" href="/knowledge_base/en/how-to-validate-business-rules-before-merging">
    Catch missing requirements, edge cases, and logic gaps before code reaches production.
  </Card>
</CardGroup>

## Rules & Automation

<CardGroup>
  <Card title="How to import rules from Cursor, Copilot, or Claude" href="/knowledge_base/en/how-to-import-rules-from-ide-tools">
    Sync your existing AI coding tool rules into your code review workflow.
  </Card>

  <Card title="How to generate code review rules automatically" href="/knowledge_base/en/how-to-generate-rules-automatically">
    Let AI analyze your review history and suggest rules based on your team's patterns.
  </Card>

  <Card title="How to share coding standards across repositories" href="/knowledge_base/en/how-to-share-standards-across-repositories">
    Use rule inheritance and organization-level rules to maintain consistency.
  </Card>

  <Card title="How to review PRs with project-specific context" href="/knowledge_base/en/how-to-review-prs-with-project-context">
    Give Kody access to your project docs, handbooks, and architecture guides.
  </Card>
</CardGroup>

## Setup & Integrations

<CardGroup>
  <Card title="How to set up AI code review on GitHub" href="/knowledge_base/en/how-to-set-up-ai-code-review-on-github">
    Install and configure Kodus for GitHub repositories in minutes.
  </Card>

  <Card title="How to set up AI code review on GitLab" href="/knowledge_base/en/how-to-set-up-ai-code-review-on-gitlab">
    Install and configure Kodus for GitLab projects.
  </Card>

  <Card title="How to set up AI code review on Azure DevOps" href="/knowledge_base/en/how-to-set-up-ai-code-review-on-azure-devops">
    Install and configure Kodus for Azure DevOps repositories.
  </Card>

  <Card title="How to connect Jira to your code review tool" href="/knowledge_base/en/how-to-connect-jira-to-code-review">
    Link Jira to enable automatic task context in your code reviews.
  </Card>

  <Card title="How to connect Linear to your code review tool" href="/knowledge_base/en/how-to-connect-linear-to-code-review">
    Link Linear to enable automatic task context in your code reviews.
  </Card>

  <Card title="Can I use my own LLM provider for code review" href="/knowledge_base/en/can-i-use-my-own-llm-provider">
    Bring your own API key and choose your preferred LLM provider.
  </Card>

  <Card title="How to self-host an AI code review tool" href="/knowledge_base/en/how-to-self-host-ai-code-review">
    Deploy Kodus on your own infrastructure with full data control.
  </Card>
</CardGroup>

## LLM Providers

<CardGroup>
  <Card title="How to use Novita AI with Kodus" href="/knowledge_base/en/how-to-use-novita-with-kodus">
    Configure Novita's serverless GPU platform as your LLM provider.
  </Card>

  <Card title="How to use Groq with Kodus" href="/knowledge_base/en/how-to-use-groq-with-kodus">
    Configure Groq's ultra-fast inference as your LLM provider.
  </Card>

  <Card title="How to use Together AI with Kodus" href="/knowledge_base/en/how-to-use-together-ai-with-kodus">
    Configure Together AI's open-source models as your LLM provider.
  </Card>

  <Card title="How to use Fireworks AI with Kodus" href="/knowledge_base/en/how-to-use-fireworks-with-kodus">
    Configure Fireworks AI's fast inference as your LLM provider.
  </Card>
</CardGroup>

## Troubleshooting

<CardGroup>
  <Card title="Why is my AI code review not triggering" href="/knowledge_base/en/why-is-ai-code-review-not-triggering">
    Common reasons and fixes when reviews don't start automatically.
  </Card>

  <Card title="How to fix webhook issues with GitHub or GitLab" href="/knowledge_base/en/how-to-fix-webhook-issues">
    Debug and resolve webhook connectivity problems.
  </Card>

  <Card title="Why are my code reviews paused" href="/knowledge_base/en/why-are-code-reviews-paused">
    Understand auto-pause behavior and how to resume reviews.
  </Card>
</CardGroup>


# Why are my code reviews paused
Source: https://docs.kodus.io/knowledge_base/en/why-are-code-reviews-paused

Understand Kodus auto-pause behavior and how to resume automated code reviews.

If Kodus stopped reviewing your PRs after working fine before, it's likely due to the **auto-pause** feature.

## What is auto-pause

Auto-pause prevents review spam during active development. When Kodus detects rapid consecutive pushes (default: 3 pushes in 15 minutes), it pauses reviews until the activity settles.

This is a feature, not a bug — it avoids flooding PRs with multiple reviews while you're still actively pushing changes.

## How to resume

* **Wait** for the cooldown period to pass, then push again
* **Comment** `@kody start-review` on the PR to trigger a review immediately
* **Change cadence** to "Automatic" if you always want reviews on every push

## Changing the behavior

Go to **Code Review Settings** → **General** → **Review Cadence**:

| Mode           | Behavior                                           |
| -------------- | -------------------------------------------------- |
| **Automatic**  | Reviews every push — no pausing                    |
| **Auto-pause** | Pauses during rapid pushes (default)               |
| **Manual**     | Only reviews when you comment `@kody start-review` |

For details, see [General Configuration](/how_to_use/en/code_review/configs/general).


# Why is my AI code review not triggering
Source: https://docs.kodus.io/knowledge_base/en/why-is-ai-code-review-not-triggering

Common reasons and fixes when Kodus doesn't automatically review your pull requests.

If Kodus isn't reviewing your PRs, check these common causes:

## 1. Automated review is disabled

Verify that automated reviews are enabled:

* Go to **Code Review Settings** → **General**
* Check that **Automated Review** is turned on
* Or verify in `kodus-config.yml`:

```yaml theme={null}
automatedReviewActive: true
```

## 2. Webhook is not configured

Kodus needs webhooks to know when a PR is opened or updated:

* Go to your Git provider's webhook settings
* Verify the Kodus webhook URL is registered and active
* Check for failed delivery attempts

## 3. PR title matches an ignored keyword

If the PR title contains an ignored keyword, Kodus skips the review:

```yaml theme={null}
ignoredTitleKeywords:
  - "release"
  - "WIP"
```

Check your `ignoredTitleKeywords` setting.

## 4. Base branch is not monitored

By default, Kodus reviews PRs targeting the default branch. If your PR targets a different branch, add it to `baseBranches`:

```yaml theme={null}
baseBranches:
  - develop
  - staging
```

## 5. Review cadence is set to manual

If review cadence is set to **Manual**, Kodus only reviews when you comment `@kody start-review`.

## 6. Auto-pause is active

If you've pushed multiple times quickly, auto-pause may have kicked in. Wait for the cooldown period or comment `@kody start-review` to trigger manually.

## Still not working?

Try commenting `@kody start-review` on the PR to trigger a manual review. If that doesn't work, check the [Troubleshooting guide](/how_to_use/en/code_review/troubleshooting).


# Changelog
Source: https://docs.kodus.io/changelog/index

Latest Kodus updates and improvements.

<div>
  <div>
    <div aria-label="Changelog filters">
      <p>Filters</p>

      <div>
        <label>
          <input type="checkbox" />

          <span>Security</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Cockpit</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>BYOK</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>AI Engine</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Self-hosted</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>GIT Provider</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Performance</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>UX & Interface</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Notifications</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Kody Rules</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>MCP</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Billing & Licenses</span>
        </label>
      </div>
    </div>
  </div>

  <div>
    <div>
      <span>July 13, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>New Token Usage Experience</div>
          <p>The Token Usage page has been redesigned to provide a more complete view of consumption.</p>
          <p>It is now easier to track costs by area, model, and review activity, as well as filter the data and drill down into more specific analyses. This helps teams better understand where tokens are being used and how they can optimize costs.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Automatic Detector Backfill for Existing Rules</div>
          <p>Organizations that created Kody Rules before this release can also benefit from the new architecture. We created an automated process that analyzes existing rules and, whenever possible, generates mechanical detectors for them.</p>
          <p>The process is incremental, safe, and does not interfere with the normal execution of rules. When a rule cannot be converted into a detector, it continues to work through the traditional semantic review flow.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>More Accurate and Predictable Kody Rules</div>
          <p>We restructured how Kody applies custom rules during code reviews. Instead of relying solely on a more open-ended agent analysis, rules are now evaluated deterministically by file and PR scope.</p>
          <p>In practice, this improves rule coverage in large PRs, reduces cases where an applicable rule is overlooked, and makes Kody Rules behave more consistently across different models.</p>
          <p>We also introduced mechanical detectors for certain rules. When a rule can safely be converted into an objective check, Kody can apply it without making an LLM call, reducing costs and improving predictability.</p>
        </div>

        <div>
          <div>Code Review Engine Improvements</div>
          <p>This release includes a major upgrade to the review agent runtime. We migrated important parts of the execution flow to a new agent harness foundation, making the system more modular, observable, and ready for future improvements.</p>
          <p>We also improved the engine used to search for evidence in the codebase, with a focus on finding more relevant cross-file references and increasing the quality of generated suggestions.</p>
        </div>

        <div>
          <div>Cleaner Review Comments</div>
          <p>We adjusted the format of Kody's review comments to prevent internal reasoning structures from appearing in the output and to make suggestions more natural, concise, and easier to understand.</p>
          <p>We also fixed issues involving aliases and internal prompt references following recent refactors.</p>
        </div>

        <div>
          <div>Improved BYOK Support</div>
          <p>We improved BYOK support across different parts of the product, including configuration, model fallback, and per-model cost calculations.</p>
          <p>We also introduced a clearer experience for viewing BYOK settings and understanding how each model affects token consumption.</p>
        </div>

        <div>
          <div>More Accurate Cost Tracking and Telemetry</div>
          <p>We improved the observability of LLM calls to ensure token usage is attributed correctly, especially within the new Kody Rules and agent workflows.</p>
          <p>This increases the accuracy of usage reports and prevents undercounting in more complex review scenarios.</p>
        </div>

        <div>
          <div>MCP Manager and Plugin Improvements</div>
          <p>We improved tenant isolation for MCP connections, enhanced connection sorting and testing, and removed legacy integrations that had already been deprecated.</p>
          <p>These changes increase the reliability of the plugins and integrations experience.</p>
        </div>

        <div>
          <div>Improvements for Self-Hosted Environments</div>
          <p>We applied fixes to Dockerfiles, provisioning scripts, and local configuration to make self-hosted environments more stable.</p>
          <p>We also fixed an issue involving pnpm on macOS and adjusted the API hostname configuration used during provisioning.</p>
        </div>

        <div>
          <div>More Stable Observability</div>
          <p>We fixed excessive memory consumption in the Mongo observability exporter and improved logging behavior across different environments.</p>
          <p>We also removed outdated references to the previous internal framework, simplifying the observability codebase.</p>
        </div>

        <div>
          <div>New Quality Tests and Validations</div>
          <p>We added new end-to-end scenarios and evaluations to validate Kody Rules, model recall, suggestion adherence, and prompt regressions.</p>
          <p>These validations help ensure that changes to models, prompts, or the underlying architecture do not reduce review quality.</p>
        </div>

        <div>
          <div>Updated Documentation</div>
          <p>We updated the documentation for BYOK, custom messages, and focused reviews. We also revised the README and added new pages explaining how to guide Kody during a review.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Safer Rule Execution:</strong> we added protections against potentially unsafe regex patterns in Kody Rules detectors. This prevents malformed or computationally expensive rules from affecting review performance. We also fixed cases where outdated detectors could remain associated with a rule after an edit changed the rule's intended behavior.</p>
          </div>

          <div>
            <p><strong>License and Billing Improvements:</strong> we fixed issues involving trial creation, the listing of inactive users or users removed from the Git organization, and active seat counts. These changes make the license page more consistent and reduce discrepancies between the organization's actual users and the users displayed in billing.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>July 6, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Steer a review with focus</div>
          <p>You can now ask Kody to pay special attention to something specific during a review, without changing any configuration.</p>
          <p>In a PR, use <code>@kody review \<directive></code>. In the CLI, use <code>kodus review --focus</code>.</p>
          <p>Examples:</p>

          <ul>
            <li><code>@kody review focus on security</code></li>
            <li><code>@kody review focus on performance</code></li>
            <li><code>kodus review --focus "edge cases"</code></li>
          </ul>

          <p>This is especially useful for larger PRs or sensitive changes, where you want the review to go deeper on a specific area, such as security, performance, edge cases, a business rule, or a team standard.</p>
          <p>Focus works as a priority, not a filter. Kody pays closer attention to the context you provide, but still reports other concrete issues it finds in the diff.</p>
          <p>Learn more in the <a href="https://docs.kodus.io/how_to_use/en/code_review/review_directive">Steer a Review (Focus)</a> documentation.</p>
        </div>

        <div>
          <div>Consolidate LLM prompts into a single comment</div>
          <p>We added an option to generate a single PR comment containing all prompts and suggestions, so an external agent or AI tool can apply the fixes in one pass.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Select all repositories at once</div>
          <p>In the add repositories modal, we added <strong>select all</strong> and <strong>clear selection</strong> buttons. For teams connecting dozens of repositories, this removes the need to select each one manually and significantly reduces setup time.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Cost breakdown by model (BYOK)</div>
          <p>Teams using Bring Your Own Key now have a detailed view of LLM usage by model on the costs screen. Instead of seeing only the total amount, you can identify exactly which providers and models are driving most of the usage and make clearer decisions about what to keep, replace, or limit.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Review agent consolidation</div>
          <p>We reorganized the code review agents to run on a unified infrastructure. Previously, parts of the flow were spread across different places, which could lead to duplicated suggestions and inconsistent behavior. With this consolidation, the pipeline is more predictable, easier to maintain, and less likely to repeat suggestions in the same PR.</p>
        </div>

        <div>
          <div>Content guard for deduplication</div>
          <p>We improved the deduplication algorithm so distinct bugs are not grouped as if they were the same issue. The content guard now better considers the actual content of each suggestion, reducing false-positive deduplication and making sure separate issues continue to be reported individually.</p>
        </div>

        <div>
          <div>Prose findings recovery + Gemini support</div>
          <p>We fixed unstable behavior in prose finding generation and restored strict mode for Gemini. We also updated the Anthropic SDK, keeping compatibility with newer models and improving response stability.</p>
        </div>

        <div>
          <div>RBAC documentation</div>
          <p>We updated the permissions documentation, including the <code>OrganizationSettings</code> scope and the restriction that only the organization Owner can configure BYOK. This makes it clearer who can do what inside the workspace.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Review comments with broken formatting:</strong> fixed cases where Kody comments appeared with unexpected formatting in pull requests.</p>
          </div>

          <div>
            <p><strong>Retry errors with BYOK providers:</strong> added preventive adjustments to avoid retry failures when a BYOK provider returns an empty response body.</p>
          </div>

          <div>
            <p><strong>Sandbox tool errors:</strong> the agent now handles errors better when running tools in the sandbox environment, without breaking the review.</p>
          </div>

          <div>
            <p><strong>Normalized user IDs:</strong> standardized how author, reviewer, and assignee IDs are handled, preventing PRs from breaking because of type differences, such as string vs. number.</p>
          </div>

          <div>
            <p><strong>@kody conversation crashing on JSON wrapped in prose:</strong> fixed a crash that happened when Kody responded to mentions and the output came back as text containing embedded JSON.</p>
          </div>

          <div>
            <p><strong>IDE sync config now respects approval settings:</strong> IDE rule synchronization now respects the approval configuration.</p>
          </div>

          <div>
            <p><strong>Rules with multiple directories:</strong> adjusted Kody Rules validation to correctly handle rules that apply to multiple path groups.</p>
          </div>

          <div>
            <p><strong>Automatic code review config creation:</strong> when a repository did not have a code review configuration, creating a Kody Rule could fail silently. The configuration is now created automatically.</p>
          </div>

          <div>
            <p><strong>Diff re-review in the agent:</strong> improved how the agent detects diffs from new commits during re-reviews.</p>
          </div>

          <div>
            <p><strong>MCP Manager OAuth disconnect:</strong> fixed an issue with disconnecting OAuth credentials in MCP Manager that could cause inconsistent behavior.</p>
          </div>

          <div>
            <p><strong>MCP Manager production build:</strong> the MCP Manager production build now correctly passes the GitHub token.</p>
          </div>

          <div>
            <p><strong>Orphaned users in the license list:</strong> users removed from the GitHub organization now appear correctly in the license list.</p>
          </div>

          <div>
            <p><strong>Skipped review email:</strong> the notification email sent when a review is skipped now includes the author's name/email and no longer breaks when the user does not have a license.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 29, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Validated review engine</div>
          <p>We updated Kody's review pipeline to improve analysis accuracy and reduce cases where important issues could slip through unnoticed.</p>
          <p>The engine now identifies problematic patterns more effectively, better understands changes that span multiple files, and can review code regions with more flexibility when the context is not fully obvious.</p>
          <p>We also optimized processing and reduced the average cost per review by around 30%.</p>
        </div>

        <div>
          <div>Shareable dashboard views</div>
          <p>Filters applied in Cockpit are now saved in the URL, including time range, repositories, severity, and status.</p>
          <p>This means you can copy the link and share it with your team on Slack, for example. Anyone who opens the URL will see Cockpit with the same filters applied, without having to manually recreate the view.</p>
          <p>This makes it easier to share specific analyses, such as what changed over the past week or an increase in security suggestions in a repository.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Unified Kody Rules lifecycle</div>
          <p>We unified the Kody Rules flow into a single lifecycle, regardless of where the rule was created: the library, manual creation, or inheritance from the organization to the repository.</p>
          <p>With this change, activating, editing, disabling, and approving rules now follow the same path inside the product. We also migrated older rules to the new format and centralized the control of rules pending approval.</p>
          <p>This makes the system more consistent, reduces unexpected states, and ensures that an active rule is actually applied in Kody reviews.</p>
        </div>

        <div>
          <div>Migrate away from Composio</div>
          <p>We removed the dependency on Composio as an external MCP broker and moved to our own implementation for GitHub Issues, now integrated with Kodus Issues.</p>
          <p>This reduces an external point of failure, improves call reliability, and gives us more control over authentication, rate limits, and retries.</p>
          <p>As part of the migration, we also removed low-usage integrations that depended on Composio, such as ClickUp and CloudId.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Inheritance toggle</div>
          <p>When you enable or disable rule inheritance from the organization to a repository, the UI now shows the new state immediately, without waiting for the API response.</p>
          <p>If the call fails, for example because of a connection issue, the state is automatically reverted and we show an error toast. Before, users would click, wait, and not get clear feedback about what had happened.</p>
          <p>We also improved the rules cache update. Now we only invalidate the rules affected by that inheritance change, avoiding unnecessary reloads for rules that did not change.</p>
        </div>

        <div>
          <div>Kody Rules Origin</div>
          <p>We added an explicit origin to all Kody Rules: <code>LIBRARY</code>, <code>MANUAL</code>, <code>INHERITED</code>, and <code>SUGGESTED</code>.</p>
          <p>This fixes an issue where some rule creation scenarios could fail silently because the backend expected an origin value that the frontend was not sending.</p>
          <p>Now the contract between frontend and backend is clearer, and the rule origin is validated before reaching the creation flow.</p>
        </div>

        <div>
          <div>Atlassian Rovo</div>
          <p>Rovo is an Atlassian AI agent that generates code and edits files automatically. When it creates commits, it includes specific metadata, such as message prefixes and custom headers.</p>
          <p>Previously, our review engine identified those commits as human-written code and could suggest changes on them.</p>
          <p>Now we detect Rovo commits and skip those changes both in the code review logic and in the MCP business-rule validation preflight.</p>
        </div>

        <div>
          <div>MCP OAuth callback</div>
          <p>We fixed the OAuth flow for connecting MCPs, such as GitHub and Jira.</p>
          <p>Previously, users who had already completed onboarding could be blocked when trying to add a new MCP. Now the callback works at any time, as long as the state parameter is valid.</p>
        </div>

        <div>
          <div>Pending rules section</div>
          <p>Pending rules, which need approval before entering the review pipeline, now have a dedicated section with improved UX.</p>
          <p>The section shows a status badge, who suggested the rule, when it was suggested, and inline actions to approve or reject it.</p>
          <p>Previously, these rules appeared mixed together with active rules, which made it easy to miss that something needed attention.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>GitHub Integration GitHub App post-onboarding:</strong> we fixed an issue where some GitHub integration pages returned a 404 after the user completed onboarding. This affected routes such as <code>/github/integration</code> and <code>/github/organization-name</code> when the GitHub App installation state was not updated correctly. We also adjusted the redirect after installation and added route validations to make the integration flow more reliable across different states.</p>
          </div>

          <div>
            <p><strong>Severity slicer colors:</strong> the severity control for low, medium, high, and critical used inconsistent colors. In some places, red meant critical; in others, it meant high. We standardized it to a semantic scale: gray for low, yellow for medium, orange for high, and red for critical. This affects Cockpit filters, suggestion badges, and notification settings.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 22, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Forgejo support is now on par with GitHub & GitLab</div>
          <p>Review comments, commit statuses, force-push detection, and webhook coverage now work consistently for Forgejo repositories. If you self-host with Forgejo, Kody behaves just like on any other major platform.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Faster PR closing for large repos</div>
          <p>Eliminated duplicate API calls when syncing Kody Rules from changed files. PRs with many files now close noticeably faster.</p>
        </div>

        <div>
          <div>Cleaner settings UI</div>
          <p>Platform settings that don't apply to your current Git provider, such as GitHub-specific options when you're on GitLab, are now hidden automatically. Less clutter, fewer misconfigurations.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Reconnecting a Git provider after disconnecting:</strong> previously, disconnecting a provider left stale integration configs behind, causing reconnects to fail. Now stale rows are properly cleaned up.</p>
          </div>

          <div>
            <p><strong>Kody conversation replies with empty responses:</strong> resolved an issue where Kody occasionally replied with blank content in PR comment threads when using Claude Sonnet.</p>
          </div>

          <div>
            <p><strong>NaN deduplication indices:</strong> added three-layer protection against NaN values appearing in suggestion deduplication indices, preventing rare but confusing duplicate suggestions.</p>
          </div>

          <div>
            <p><strong>Forgejo prompt field always empty:</strong> the formatPromptForLLM function was reading a non-existent field on Forgejo PRs, causing the prompt section to be blank. Now it reads the correct field.</p>
          </div>

          <div>
            <p><strong>Self-hosted AST graph reliability:</strong> the kodus-graph CLI was installed but not available to the runtime user in self-hosted worker images. Fixed PATH and install order so graph indexing works out of the box.</p>
          </div>

          <div>
            <p><strong>Orphaned agent trace records:</strong> prevented a race condition in chunked review mode that could leave orphaned <code>IN\_PROGRESS</code> trace records in the database.</p>
          </div>

          <div>
            <p><strong>Platform settings not scoped to Git tool:</strong> settings incompatible with your current Git provider were still visible. Now they're properly filtered based on the connected tool.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 15, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Operational metrics in Cockpit</div>
          <p>Track the health of your review pipeline in real time. Throughput, queue, and processing time metrics are now available in Cockpit.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Redesigned Kodus Review tab</div>
          <p>The review tab has been redesigned with a cleaner interface and more direct actions. You can now analyze and act on suggestions without leaving the PR screen.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Backend on pnpm</div>
          <p>We migrated the backend from Yarn 1 to pnpm. This makes builds faster, improves lockfile consistency, and reduces cache issues across environments.</p>
        </div>

        <div>
          <div>Token usage screen</div>
          <p>The token usage screen has been redesigned to make consumption by organization and period easier to understand. It is now simpler to track usage and see how tokens are being consumed over time.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Self-hosted analytics:</strong> we fixed the analytics integration for self-hosted deployments. Usage metrics now appear correctly in the dashboard.</p>
          </div>

          <div>
            <p><strong>Issue cache:</strong> the issue count in the sidebar could sometimes become outdated. The cache is now invalidated correctly after changes.</p>
          </div>

          <div>
            <p><strong>GitHub rate limit:</strong> we fixed a rate limit issue in cloud E2E tests. We now use round-robin across multiple bot accounts to better distribute requests.</p>
          </div>

          <div>
            <p><strong>Notification routing:</strong> we fixed the behavior of targeted notifications when combined with audience settings. Notifications now reach the right people without duplicates.</p>
          </div>

          <div>
            <p><strong>Centralized config sync:</strong> we fixed issues in the centralized sync of Kody Rules configurations across repositories. Sync now correctly handles multiple scopes, stale configurations, and merge-triggered updates.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 8, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Moonshot Kimi support for BYOK</div>
          <p>We added support for Moonshot as a provider, compatible with the Anthropic API.</p>
          <p>You can now use the Kimi Coding Plan model in BYOK setups. To configure it, set the <code>API\_MOONSHOT\_API\_KEY</code> key and select the model in the organization preferences.</p>
          <p>See the <a href="https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus">Moonshot (Kimi)</a> documentation for more setup details.</p>
        </div>

        <div>
          <div>Monthly token usage control</div>
          <p>Organizations can now set monthly token consumption limits per model.</p>
          <p>Usage is shown in real time in the interface, with a progress bar. When usage reaches 80% of the limit, the team receives an email alert. If the limit is reached, additional reviews can be blocked automatically.</p>

          <video>
            <source type="video/mp4" />
          </video>

          <p>See the <a href="https://docs.kodus.io/how_to_use/en/spend-limit">Monthly Spend Limit</a> documentation for more setup details.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>More resilient review agent</div>
          <p>The review engine now handles empty or malformed LLM responses better.</p>
          <p>This reduces loops in edge cases and helps ensure valid suggestions continue to be delivered even when the provider returns an unexpected response.</p>
        </div>

        <div>
          <div>Telemetry for self-hosted environments</div>
          <p>On-premise installations now automatically report health metrics, such as heartbeat, and usage data.</p>
          <p>The goal is to make diagnosis and support easier without exposing sensitive customer data.</p>
        </div>

        <div>
          <div>Faster Kody Rules</div>
          <p>We improved the loading and synchronization of custom rules.</p>
          <p>We also fixed the count of orphaned rules and made partial updates safer against race conditions.</p>
        </div>

        <div>
          <div>GitLab compatibility improvements</div>

          <ul>
            <li>Support for GitLab 13.x in comment webhooks</li>
            <li>Diff fallback for versions earlier than 15.7</li>
            <li>Fixes for discussion threads and replies scoped by discussionId</li>
            <li>Self-hosted development environment documentation</li>
          </ul>
        </div>
      </div>

      <div>
        <div>Fixes</div>

        <div>
          <div>
            <p><strong>GitHub:</strong> suspended users no longer appear in the member list for license assignment.</p>
          </div>

          <div>
            <p><strong>Update Connection:</strong> integration reauthentication now correctly clears the previous configuration.</p>
          </div>

          <div>
            <p><strong>Integration reset:</strong> Kody Rules linked to the repo/directory are now removed automatically.</p>
          </div>

          <div>
            <p><strong>Release Freeze:</strong> eligibility notifications only appear when the freeze is active.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>
</div>

<div>
  <Update label="July 13, 2026 - New Token Usage Experience">
    The Token Usage page has been redesigned to provide a more complete view of consumption.

    It is now easier to track costs by area, model, and review activity, as well as filter the data and drill down into more specific analyses. This helps teams better understand where tokens are being used and how they can optimize costs.

    Video: [https://kodus.io/wp-content/uploads/2026/07/new-experience-token-usage.mp4](https://kodus.io/wp-content/uploads/2026/07/new-experience-token-usage.mp4)
  </Update>

  <Update label="July 13, 2026 - Automatic Detector Backfill for Existing Rules">
    Organizations that created Kody Rules before this release can also benefit from the new architecture. We created an automated process that analyzes existing rules and, whenever possible, generates mechanical detectors for them.

    The process is incremental, safe, and does not interfere with the normal execution of rules. When a rule cannot be converted into a detector, it continues to work through the traditional semantic review flow.
  </Update>

  <Update label="July 13, 2026 - More Accurate and Predictable Kody Rules">
    We restructured how Kody applies custom rules during code reviews. Instead of relying solely on a more open-ended agent analysis, rules are now evaluated deterministically by file and PR scope.

    In practice, this improves rule coverage in large PRs, reduces cases where an applicable rule is overlooked, and makes Kody Rules behave more consistently across different models.

    We also introduced mechanical detectors for certain rules. When a rule can safely be converted into an objective check, Kody can apply it without making an LLM call, reducing costs and improving predictability.
  </Update>

  <Update label="July 13, 2026 - Code Review Engine Improvements">
    This release includes a major upgrade to the review agent runtime. We migrated important parts of the execution flow to a new agent harness foundation, making the system more modular, observable, and ready for future improvements.

    We also improved the engine used to search for evidence in the codebase, with a focus on finding more relevant cross-file references and increasing the quality of generated suggestions.
  </Update>

  <Update label="July 13, 2026 - Cleaner Review Comments">
    We adjusted the format of Kody's review comments to prevent internal reasoning structures from appearing in the output and to make suggestions more natural, concise, and easier to understand.

    We also fixed issues involving aliases and internal prompt references following recent refactors.
  </Update>

  <Update label="July 13, 2026 - Improved BYOK Support">
    We improved BYOK support across different parts of the product, including configuration, model fallback, and per-model cost calculations.

    We also introduced a clearer experience for viewing BYOK settings and understanding how each model affects token consumption.
  </Update>

  <Update label="July 13, 2026 - More Accurate Cost Tracking and Telemetry">
    We improved the observability of LLM calls to ensure token usage is attributed correctly, especially within the new Kody Rules and agent workflows.

    This increases the accuracy of usage reports and prevents undercounting in more complex review scenarios.
  </Update>

  <Update label="July 13, 2026 - MCP Manager and Plugin Improvements">
    We improved tenant isolation for MCP connections, enhanced connection sorting and testing, and removed legacy integrations that had already been deprecated.

    These changes increase the reliability of the plugins and integrations experience.
  </Update>

  <Update label="July 13, 2026 - Improvements for Self-Hosted Environments">
    We applied fixes to Dockerfiles, provisioning scripts, and local configuration to make self-hosted environments more stable.

    We also fixed an issue involving pnpm on macOS and adjusted the API hostname configuration used during provisioning.
  </Update>

  <Update label="July 13, 2026 - More Stable Observability">
    We fixed excessive memory consumption in the Mongo observability exporter and improved logging behavior across different environments.

    We also removed outdated references to the previous internal framework, simplifying the observability codebase.
  </Update>

  <Update label="July 13, 2026 - New Quality Tests and Validations">
    We added new end-to-end scenarios and evaluations to validate Kody Rules, model recall, suggestion adherence, and prompt regressions.

    These validations help ensure that changes to models, prompts, or the underlying architecture do not reduce review quality.
  </Update>

  <Update label="July 13, 2026 - Updated Documentation">
    We updated the documentation for BYOK, custom messages, and focused reviews. We also revised the README and added new pages explaining how to guide Kody during a review.
  </Update>

  <Update label="July 13, 2026 - Safer Rule Execution">
    We added protections against potentially unsafe regex patterns in Kody Rules detectors. This prevents malformed or computationally expensive rules from affecting review performance. We also fixed cases where outdated detectors could remain associated with a rule after an edit changed the rule's intended behavior.
  </Update>

  <Update label="July 13, 2026 - License and Billing Improvements">
    We fixed issues involving trial creation, the listing of inactive users or users removed from the Git organization, and active seat counts. These changes make the license page more consistent and reduce discrepancies between the organization's actual users and the users displayed in billing.
  </Update>

  <Update label="July 6, 2026 - Steer a review with focus">
    You can now ask Kody to pay special attention to something specific during a review, without changing any configuration.

    In a PR, use @kody review \<directive>. In the CLI, use kodus review --focus.

    Examples: @kody review focus on security. @kody review focus on performance. Or in the CLI: kodus review --focus "edge cases".

    This is especially useful for larger PRs or sensitive changes, where you want the review to go deeper on a specific area, such as security, performance, edge cases, a business rule, or a team standard.

    Focus works as a priority, not a filter. Kody pays closer attention to the context you provide, but still reports other concrete issues it finds in the diff.

    Learn more in the Steer a Review Focus documentation: [https://docs.kodus.io/how\_to\_use/en/code\_review/review\_directive](https://docs.kodus.io/how_to_use/en/code_review/review_directive)
  </Update>

  <Update label="July 6, 2026 - Consolidate LLM prompts into a single comment">
    We added an option to generate a single PR comment containing all prompts and suggestions, so an external agent or AI tool can apply the fixes in one pass.

    Video: [https://kodus.io/wp-content/uploads/2026/07/agent-prompt.mp4](https://kodus.io/wp-content/uploads/2026/07/agent-prompt.mp4)
  </Update>

  <Update label="July 6, 2026 - Select all repositories at once">
    In the add repositories modal, we added select all and clear selection buttons. For teams connecting dozens of repositories, this removes the need to select each one manually and significantly reduces setup time.

    Video: [https://kodus.io/wp-content/uploads/2026/07/add-repo-qa.mp4](https://kodus.io/wp-content/uploads/2026/07/add-repo-qa.mp4)
  </Update>

  <Update label="July 6, 2026 - Cost breakdown by model (BYOK)">
    Teams using Bring Your Own Key now have a detailed view of LLM usage by model on the costs screen. Instead of seeing only the total amount, you can identify exactly which providers and models are driving most of the usage and make clearer decisions about what to keep, replace, or limit.

    Video: [https://kodus.io/wp-content/uploads/2026/07/resumo-de-custos-por-modelo.mp4](https://kodus.io/wp-content/uploads/2026/07/resumo-de-custos-por-modelo.mp4)
  </Update>

  <Update label="July 6, 2026 - Review agent consolidation">
    We reorganized the code review agents to run on a unified infrastructure. Previously, parts of the flow were spread across different places, which could lead to duplicated suggestions and inconsistent behavior. With this consolidation, the pipeline is more predictable, easier to maintain, and less likely to repeat suggestions in the same PR.
  </Update>

  <Update label="July 6, 2026 - Content guard for deduplication">
    We improved the deduplication algorithm so distinct bugs are not grouped as if they were the same issue. The content guard now better considers the actual content of each suggestion, reducing false-positive deduplication and making sure separate issues continue to be reported individually.
  </Update>

  <Update label="July 6, 2026 - Prose findings recovery + Gemini support">
    We fixed unstable behavior in prose finding generation and restored strict mode for Gemini. We also updated the Anthropic SDK, keeping compatibility with newer models and improving response stability.
  </Update>

  <Update label="July 6, 2026 - RBAC documentation">
    We updated the permissions documentation, including the OrganizationSettings scope and the restriction that only the organization Owner can configure BYOK. This makes it clearer who can do what inside the workspace.
  </Update>

  <Update label="July 6, 2026 - Review comments with broken formatting">
    Fixed cases where Kody comments appeared with unexpected formatting in pull requests.
  </Update>

  <Update label="July 6, 2026 - Retry errors with BYOK providers">
    Added preventive adjustments to avoid retry failures when a BYOK provider returns an empty response body.
  </Update>

  <Update label="July 6, 2026 - Sandbox tool errors">
    The agent now handles errors better when running tools in the sandbox environment, without breaking the review.
  </Update>

  <Update label="July 6, 2026 - Normalized user IDs">
    Standardized how author, reviewer, and assignee IDs are handled, preventing PRs from breaking because of type differences, such as string vs. number.
  </Update>

  <Update label="July 6, 2026 - @kody conversation crashing on JSON wrapped in prose">
    Fixed a crash that happened when Kody responded to mentions and the output came back as text containing embedded JSON.
  </Update>

  <Update label="July 6, 2026 - IDE sync config now respects approval settings">
    IDE rule synchronization now respects the approval configuration.
  </Update>

  <Update label="July 6, 2026 - Rules with multiple directories">
    Adjusted Kody Rules validation to correctly handle rules that apply to multiple path groups.
  </Update>

  <Update label="July 6, 2026 - Automatic code review config creation">
    When a repository did not have a code review configuration, creating a Kody Rule could fail silently. The configuration is now created automatically.
  </Update>

  <Update label="July 6, 2026 - Diff re-review in the agent">
    Improved how the agent detects diffs from new commits during re-reviews.
  </Update>

  <Update label="July 6, 2026 - MCP Manager OAuth disconnect">
    Fixed an issue with disconnecting OAuth credentials in MCP Manager that could cause inconsistent behavior.
  </Update>

  <Update label="July 6, 2026 - MCP Manager production build">
    The MCP Manager production build now correctly passes the GitHub token.
  </Update>

  <Update label="July 6, 2026 - Orphaned users in the license list">
    Users removed from the GitHub organization now appear correctly in the license list.
  </Update>

  <Update label="July 6, 2026 - Skipped review email">
    The notification email sent when a review is skipped now includes the author's name/email and no longer breaks when the user does not have a license.
  </Update>

  <Update label="June 29, 2026 - Validated review engine">
    We updated Kody's review pipeline to improve analysis accuracy and reduce cases where important issues could slip through unnoticed.

    The engine now identifies problematic patterns more effectively, better understands changes that span multiple files, and can review code regions with more flexibility when the context is not fully obvious.

    We also optimized processing and reduced the average cost per review by around 30%.
  </Update>

  <Update label="June 29, 2026 - Shareable dashboard views">
    Filters applied in Cockpit are now saved in the URL, including time range, repositories, severity, and status.

    This means you can copy the link and share it with your team on Slack, for example. Anyone who opens the URL will see Cockpit with the same filters applied, without having to manually recreate the view.

    This makes it easier to share specific analyses, such as what changed over the past week or an increase in security suggestions in a repository.

    Video: [https://kodus.io/wp-content/uploads/2026/06/kodus-copy-url.mp4](https://kodus.io/wp-content/uploads/2026/06/kodus-copy-url.mp4)
  </Update>

  <Update label="June 29, 2026 - Unified Kody Rules lifecycle">
    We unified the Kody Rules flow into a single lifecycle, regardless of where the rule was created: the library, manual creation, or inheritance from the organization to the repository.

    With this change, activating, editing, disabling, and approving rules now follow the same path inside the product. We also migrated older rules to the new format and centralized the control of rules pending approval.

    This makes the system more consistent, reduces unexpected states, and ensures that an active rule is actually applied in Kody reviews.
  </Update>

  <Update label="June 29, 2026 - Migrate away from Composio">
    We removed the dependency on Composio as an external MCP broker and moved to our own implementation for GitHub Issues, now integrated with Kodus Issues.

    This reduces an external point of failure, improves call reliability, and gives us more control over authentication, rate limits, and retries.

    As part of the migration, we also removed low-usage integrations that depended on Composio, such as ClickUp and CloudId.
  </Update>

  <Update label="June 29, 2026 - Inheritance toggle">
    When you enable or disable rule inheritance from the organization to a repository, the UI now shows the new state immediately, without waiting for the API response.

    If the call fails, for example because of a connection issue, the state is automatically reverted and we show an error toast. Before, users would click, wait, and not get clear feedback about what had happened.

    We also improved the rules cache update. Now we only invalidate the rules affected by that inheritance change, avoiding unnecessary reloads for rules that did not change.
  </Update>

  <Update label="June 29, 2026 - Kody Rules Origin">
    We added an explicit origin to all Kody Rules: LIBRARY, MANUAL, INHERITED, and SUGGESTED.

    This fixes an issue where some rule creation scenarios could fail silently because the backend expected an origin value that the frontend was not sending.

    Now the contract between frontend and backend is clearer, and the rule origin is validated before reaching the creation flow.
  </Update>

  <Update label="June 29, 2026 - Atlassian Rovo">
    Rovo is an Atlassian AI agent that generates code and edits files automatically. When it creates commits, it includes specific metadata, such as message prefixes and custom headers.

    Previously, our review engine identified those commits as human-written code and could suggest changes on them.

    Now we detect Rovo commits and skip those changes both in the code review logic and in the MCP business-rule validation preflight.
  </Update>

  <Update label="June 29, 2026 - MCP OAuth callback">
    We fixed the OAuth flow for connecting MCPs, such as GitHub and Jira.

    Previously, users who had already completed onboarding could be blocked when trying to add a new MCP. Now the callback works at any time, as long as the state parameter is valid.
  </Update>

  <Update label="June 29, 2026 - Pending rules section">
    Pending rules, which need approval before entering the review pipeline, now have a dedicated section with improved UX.

    The section shows a status badge, who suggested the rule, when it was suggested, and inline actions to approve or reject it.

    Previously, these rules appeared mixed together with active rules, which made it easy to miss that something needed attention.
  </Update>

  <Update label="June 29, 2026 - GitHub Integration GitHub App post-onboarding">
    We fixed an issue where some GitHub integration pages returned a 404 after the user completed onboarding. This affected routes such as /github/integration and /github/organization-name when the GitHub App installation state was not updated correctly. We also adjusted the redirect after installation and added route validations to make the integration flow more reliable across different states.
  </Update>

  <Update label="June 29, 2026 - Severity slicer colors">
    The severity control for low, medium, high, and critical used inconsistent colors. In some places, red meant critical; in others, it meant high. We standardized it to a semantic scale: gray for low, yellow for medium, orange for high, and red for critical. This affects Cockpit filters, suggestion badges, and notification settings.
  </Update>

  <Update label="June 22, 2026 - Forgejo support is now on par with GitHub & GitLab">
    Review comments, commit statuses, force-push detection, and webhook coverage now work consistently for Forgejo repositories. If you self-host with Forgejo, Kody behaves just like on any other major platform.
  </Update>

  <Update label="June 22, 2026 - Faster PR closing for large repos">
    Eliminated duplicate API calls when syncing Kody Rules from changed files. PRs with many files now close noticeably faster.
  </Update>

  <Update label="June 22, 2026 - Cleaner settings UI">
    Platform settings that don't apply to your current Git provider, such as GitHub-specific options when you're on GitLab, are now hidden automatically. Less clutter, fewer misconfigurations.
  </Update>

  <Update label="June 22, 2026 - Reconnecting a Git provider after disconnecting">
    Previously, disconnecting a provider left stale integration configs behind, causing reconnects to fail. Now stale rows are properly cleaned up.
  </Update>

  <Update label="June 22, 2026 - Kody conversation replies with empty responses">
    Resolved an issue where Kody occasionally replied with blank content in PR comment threads when using Claude Sonnet.
  </Update>

  <Update label="June 22, 2026 - NaN deduplication indices">
    Added three-layer protection against NaN values appearing in suggestion deduplication indices, preventing rare but confusing duplicate suggestions.
  </Update>

  <Update label="June 22, 2026 - Forgejo prompt field always empty">
    The formatPromptForLLM function was reading a non-existent field on Forgejo PRs, causing the prompt section to be blank. Now it reads the correct field.
  </Update>

  <Update label="June 22, 2026 - Self-hosted AST graph reliability">
    The kodus-graph CLI was installed but not available to the runtime user in self-hosted worker images. Fixed PATH and install order so graph indexing works out of the box.
  </Update>

  <Update label="June 22, 2026 - Orphaned agent trace records">
    Prevented a race condition in chunked review mode that could leave orphaned IN\_PROGRESS trace records in the database.
  </Update>

  <Update label="June 22, 2026 - Platform settings not scoped to Git tool">
    Settings incompatible with your current Git provider were still visible. Now they're properly filtered based on the connected tool.
  </Update>

  <Update label="June 15, 2026 - Operational metrics in Cockpit">
    Track the health of your review pipeline in real time. Throughput, queue, and processing time metrics are now available in Cockpit.

    Video: [https://kodus.io/wp-content/uploads/2026/06/cockpit.mp4](https://kodus.io/wp-content/uploads/2026/06/cockpit.mp4)
  </Update>

  <Update label="June 15, 2026 - Redesigned Kodus Review tab">
    The review tab has been redesigned with a cleaner interface and more direct actions. You can now analyze and act on suggestions without leaving the PR screen.

    Video: [https://kodus.io/wp-content/uploads/2026/06/kody-review-tab.mp4](https://kodus.io/wp-content/uploads/2026/06/kody-review-tab.mp4)
  </Update>

  <Update label="June 15, 2026 - Backend on pnpm">
    We migrated the backend from Yarn 1 to pnpm. This makes builds faster, improves lockfile consistency, and reduces cache issues across environments.
  </Update>

  <Update label="June 15, 2026 - Token usage screen">
    The token usage screen has been redesigned to make consumption by organization and period easier to understand. It is now simpler to track usage and see how tokens are being consumed over time.

    Video: [https://kodus.io/wp-content/uploads/2026/06/token\_usage.mp4](https://kodus.io/wp-content/uploads/2026/06/token_usage.mp4)
  </Update>

  <Update label="June 15, 2026 - Self-hosted analytics">
    We fixed the analytics integration for self-hosted deployments. Usage metrics now appear correctly in the dashboard.
  </Update>

  <Update label="June 15, 2026 - Issue cache">
    The issue count in the sidebar could sometimes become outdated. The cache is now invalidated correctly after changes.
  </Update>

  <Update label="June 15, 2026 - GitHub rate limit">
    We fixed a rate limit issue in cloud E2E tests. We now use round-robin across multiple bot accounts to better distribute requests.
  </Update>

  <Update label="June 15, 2026 - Notification routing">
    We fixed the behavior of targeted notifications when combined with audience settings. Notifications now reach the right people without duplicates.
  </Update>

  <Update label="June 15, 2026 - Centralized config sync">
    We fixed issues in the centralized sync of Kody Rules configurations across repositories. Sync now correctly handles multiple scopes, stale configurations, and merge-triggered updates.
  </Update>

  <Update label="June 8, 2026 - Moonshot Kimi support for BYOK">
    We added support for Moonshot as a provider, compatible with the Anthropic API.

    You can now use the Kimi Coding Plan model in BYOK setups. To configure it, set the API\_MOONSHOT\_API\_KEY key and select the model in the organization preferences.

    See the Moonshot Kimi documentation for more setup details: [https://docs.kodus.io/knowledge\_base/en/how-to-use-moonshot-with-kodus](https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus)
  </Update>

  <Update label="June 8, 2026 - Monthly token usage control">
    Organizations can now set monthly token consumption limits per model.

    Usage is shown in real time in the interface, with a progress bar. When usage reaches 80% of the limit, the team receives an email alert. If the limit is reached, additional reviews can be blocked automatically.

    Video: [https://kodus.io/wp-content/uploads/2026/06/token-usage.mov](https://kodus.io/wp-content/uploads/2026/06/token-usage.mov)

    See the Monthly Spend Limit documentation for more setup details: [https://docs.kodus.io/how\_to\_use/en/spend-limit](https://docs.kodus.io/how_to_use/en/spend-limit)
  </Update>

  <Update label="June 8, 2026 - More resilient review agent">
    The review engine now handles empty or malformed LLM responses better. This reduces loops in edge cases and helps ensure valid suggestions continue to be delivered even when the provider returns an unexpected response.
  </Update>

  <Update label="June 8, 2026 - Telemetry for self-hosted environments">
    On-premise installations now automatically report health metrics, such as heartbeat, and usage data. The goal is to make diagnosis and support easier without exposing sensitive customer data.
  </Update>

  <Update label="June 8, 2026 - Faster Kody Rules">
    We improved the loading and synchronization of custom rules. We also fixed the count of orphaned rules and made partial updates safer against race conditions.
  </Update>

  <Update label="June 8, 2026 - GitLab compatibility improvements">
    Support for GitLab 13.x in comment webhooks.

    Diff fallback for versions earlier than 15.7.

    Fixes for discussion threads and replies scoped by discussionId.

    Self-hosted development environment documentation.
  </Update>

  <Update label="June 8, 2026 - GitHub member list fix">
    Suspended users no longer appear in the member list for license assignment.
  </Update>

  <Update label="June 8, 2026 - Update Connection fix">
    Integration reauthentication now correctly clears the previous configuration.
  </Update>

  <Update label="June 8, 2026 - Integration reset fix">
    Kody Rules linked to the repo or directory are now removed automatically.
  </Update>

  <Update label="June 8, 2026 - Release Freeze fix">
    Eligibility notifications only appear when the freeze is active.
  </Update>
</div>


# PR review for compliance (SOC2, HIPAA)
Source: https://docs.kodus.io/cookbook/en/compliance-review-pipeline

Configure Kody Rules and Memories to enforce audit trail, data handling, and access control requirements.

## Why compliance needs automated review

Compliance frameworks like SOC2, HIPAA, and GDPR require specific coding practices around data handling, access control, and audit logging. Manual reviews catch some violations, but they're inconsistent — especially when the reviewer isn't a security specialist.

This cookbook sets up rules that enforce compliance requirements on every PR.

## Step 1 — Define your compliance Memories

Start by teaching Kody the high-level compliance principles:

```
@kody remember: we are SOC2 compliant. All data access must be logged
with who accessed what, when, and from where.
```

```
@kody remember: PII (personally identifiable information) must never
appear in logs, error messages, or API responses. PII includes:
name, email, phone, address, SSN, date of birth, IP address.
```

```
@kody remember: all data at rest must be encrypted. Database fields
containing PII must use application-level encryption.
```

```
@kody remember: access control follows least privilege principle.
New endpoints default to authenticated + authorized, never public.
```

## Step 2 — Create audit trail rules

### Audit logging rule

```
Name: Data mutations must have audit logging
Scope: File
Paths: src/services/**/*.ts, src/repositories/**/*.ts
Severity: Critical
Instructions:
  If fileDiff contains create, update, or delete operations
  on user data or sensitive records, verify that an audit log
  entry is created. Look for calls to auditService.log(),
  AuditLogger, or @Audited decorator.
  Reference @file:src/shared/audit/audit.service.ts for
  the approved audit patterns.
```

### Data retention rule

```
Name: Soft delete required for user data
Scope: File
Paths: src/**/*.ts
Severity: Critical
Instructions:
  Flag any hard delete (DELETE FROM, .delete(), .destroy())
  on tables/collections that contain user data.
  User data must use soft delete (deletedAt timestamp)
  for compliance with data retention policies.
```

## Step 3 — Create data handling rules

### PII exposure prevention

```
Name: No PII in logs or error responses
Scope: File
Paths: src/**/*.ts
Severity: Critical
Instructions:
  Check fileDiff for logging statements (logger.*, console.*)
  and error response builders that might include PII fields:
  email, name, phone, address, ssn, dateOfBirth, ipAddress.
  These must be redacted or excluded before logging/responding.
```

### Encryption requirement

```
Name: PII fields must use encryption helpers
Scope: File
Paths: src/entities/**/*.ts, src/models/**/*.ts
Severity: Critical
Instructions:
  If fileDiff adds or modifies entity/model fields that contain
  PII (see list above), verify they use the @Encrypted decorator
  or encryptionService helper. Reference
  @file:src/shared/encryption/encryption.service.ts.
```

## Step 4 — Create access control rules

```
Name: New endpoints must have auth guards
Scope: Pull Request
Severity: Critical
Instructions:
  Check pr_files_diff for new route definitions or controller
  methods. Every new endpoint must include:
  1. Authentication guard (@UseGuards(AuthGuard))
  2. Authorization decorator (@Roles or @Permissions)
  3. Rate limiting (@Throttle or equivalent)
  If any endpoint is intentionally public, it must have
  an explicit @Public() decorator with a code comment
  explaining why.
```

## Step 5 — Add a PR-level compliance check

```
Name: Compliance impact assessment
Scope: Pull Request
Severity: High
Instructions:
  If pr_files_diff touches any file in src/entities/,
  src/models/, or database migrations, check whether:
  1. New fields handling PII are documented
  2. Data flow changes are noted in pr_description
  3. Privacy impact is considered
  If the PR adds new data collection, flag it for
  privacy review.
```

## Step 6 — Configure for enforcement

1. Enable **Request Changes** so compliance violations block merge
2. Set all compliance rules to **Critical** severity
3. Use rule inheritance to apply compliance rules across all repos in the organization

## Checklist

* [ ] Compliance Memories teach the high-level principles
* [ ] Audit logging rule covers all data mutation paths
* [ ] PII exposure rule covers logs and error responses
* [ ] Encryption rule covers entity/model definitions
* [ ] Access control rule covers all new endpoints
* [ ] Request Changes enabled for critical findings
* [ ] Rules are set at organization level for consistency
* [ ] A test PR verified the rules fire correctly

For more on configuring rules, see [Kody Rules](/how_to_use/en/code_review/configs/kody_rules).


# Install custom MCP plugins
Source: https://docs.kodus.io/cookbook/en/custom-plugin-install

Step-by-step instructions for connecting any custom Model Context Protocol plugin to Kodus.

## Why custom plugins matter

Custom MCP plugins let your team ground Kody on internal systems—knowledge bases, incident dashboards, policy engines, you name it. Once installed, every Kody interaction can call those tools with live data, so reviewers stop copying screenshots or stale snippets into pull requests.

This guide shows the opinionated flow we recommend for any custom plugin, whether it is a simple read-only endpoint (like the Kodus Docs MCP) or a more advanced pipeline with authentication.

<Callout icon="globe">
  Kodus supports **remote MCP servers only**—that means the plugin must be reachable from Kodus' infrastructure.
</Callout>

***

## Prepare your plugin info

Gather these details before opening the Plugins catalog:

| Field                  | Why it matters                                                                           |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| **Public URL**         | Endpoint where the MCP manifest is hosted (e.g., `https://acme-internal-tools.com/mcp`). |
| **Protocol**           | MCP implementation type (HTTP or SSE).                                                   |
| **Hosting**            | Must be a remote server accessible from Kodus (no localhost or desktop MCP endpoints).   |
| **Authentication**     | Whether the plugin requires API keys, OAuth, or is open to your workspace IPs.           |
| **Description / Logo** | Helps other engineers understand what the plugin does when browsing the catalog.         |

Looking for remote MCP servers to try out?

* [Smithery.ai](https://smithery.ai/) curates deployable MCP services plus an easy launcher you can point at your own infra.
* [Awesome Remote MCP Servers](https://github.com/sylviangth/awesome-remote-mcp-servers) lists community-maintained endpoints spanning docs search, security scanners, and workflow bots.

## Install the plugin in Kodus

<iframe title="YouTube video player" />

1. Go to **Code Review Settings → Plugins** (beta) inside your Kodus workspace.

2. Click **Add Plugin**.

3. Fill in the form:

   ```text theme={null}
   Plugin Name: Descriptive label (e.g., "Security Runbooks MCP")
   Description: What data/actions it exposes
   Logo URL: Optional, but helpful for recognition
   URL: https://your-domain.com/mcp
   Protocol: HTTP or SSE
   Authorization / Headers: Add if your MCP host requires them (e.g., API key, OAuth, etc.) (optional)
   ```

4. Hit **Create Plugin**. Once it appears in the list, it is instantly available to the entire workspace.

<Warning>
  Custom plugins run with the same permissions as the workspace. Only install endpoints your organization trusts and monitors.
</Warning>

## Verify the connection

1. Open any pull request where Kody is enabled.

2. Mention `@kody` and include a question that forces the plugin to respond.

   ```
   @kody can you fetch the deployment checklist from our MCP and confirm whether feature flags are required?
   ```

3. In the drawer, check the **Plugins** section. You should see a call to your new plugin. If it fails, expand the error to inspect the status code or validation message.

<Info>
  The Kodus Docs MCP (`https://docs.kodus.io/mcp`) is a quick sanity test—you can install it first to ensure your workspace can reach external hosts.
</Info>

***

## Quick checklist

* [ ] Plugin manifest is hosted and reachable.
* [ ] Auth model (if any) is documented and tested.
* [ ] Plugin is installed via **Add Custom Plugin** with the right URL + headers.
* [ ] A sample PR proved Kody can call the plugin.
* [ ] Owners know how to monitor and update the integration.


# Turn your best practices doc into review guardrails
Source: https://docs.kodus.io/cookbook/en/guide-handbook-guardrails

Convert your engineering handbook into living Kody Rules with optional MCP plugins.

## Why this guide matters

Every engineering team has a “best practices” doc somewhere. The problem is that IDE suggestions don’t read it, reviewers forget the nuances, and the document slowly loses authority. This guide shows how to turn your handbook into active guardrails so Kody enforces those rules automatically and cites the relevant section whenever code drifts.

We’ll focus on two building blocks:

* [Kody Rules](/how_to_use/en/code_review/configs/kody_rules) – encode each policy bullet as deterministic file-level or PR-level checks.
* [Custom plugins](/cookbook/en/custom-plugin-install) – fetch standards from remote MCP servers when the source of truth lives outside Git.

Follow the flow and any repo can evolve from “handbook PDF” to “living policy pack.”

## Pre-flight checklist

* You have permission to edit **Code Review Settings → Kody Rules**.
* The policy pack lives in the repo (e.g., `docs/engineering-standards.md`). If yours sits in another path, adjust accordingly. If it lives in Notion, Confluence, or Google Docs, plan to expose it through a remote MCP endpoint.
* You know which topics should be evaluated at the file level (controllers, configs) versus PR level (feature flags, rollout narratives, architecture).

<Callout icon="layers">
  Keep the handbook under version control. Every edit should go through PRs with owners who sign off. That discipline keeps rules grounded in reality.
</Callout>

## Phase 1 – Shape a rule-friendly policy pack

1. Create or reuse a markdown file such as `docs/engineering-standards.md`. The only requirement: Kody must be able to reference it via `@file:...`.
2. Organize content into short, checkable bullets:

```md theme={null}
# Engineering Standards

## Error handling
- Never swallow errors.
- Do not log PII or secrets.
- External requests must have a timeout and retry policy.

## Architecture
- No direct cross-module imports from `domain/*` into `web/*`.
- New endpoints must include tracing fields (e.g., requestId) and structured logs.
- Feature flags are mandatory for risky changes.
```

3. Add metadata like `[Owner: Backend Platform]` or `[Risk: High]` to help route violations.

<Info>
  If the source of truth stays outside Git, adopt the same structure but publish it through a remote MCP server so rules can call `@MCP:policy_pack.getSection(...)`.
</Info>

<Tip>
  Make each bullet atomic. When a rule fires, there should be zero debate about what needs to change.
</Tip>

## Phase 2 – Point every rule at the real document

Rules can read files and remote MCP payloads. Reference the actual handbook instead of pasting snippets in each instruction.

```text theme={null}
Use @file:docs/engineering-standards.md (Architecture section) as the policy source.
Only flag code that clearly violates those bullets. If the section is missing, say so.
```

* Swap in other file paths for domain-specific packs (e.g., `@file:docs/mobile.md`).
* Need only a slice of the file? Append line anchors—`@file:docs/engineering-standards.md#L40-L72`—so the rule consumes just that section.
* When the policy comes from Notion/Confluence/etc., replace the file reference with `@MCP:policy_pack.getSection({"id":"security"})`.
* Combine both when the rule needs static templates plus dynamic data (e.g., `@file` for log format + `@MCP:piiRegistry.list()` for the current sensitive fields).

<Callout icon="link">
  One reference keeps everything in sync. Update the handbook once and every rule enforces the latest version.
</Callout>

## Phase 3 – Translate sections into Kody Rules

Open **Code Review Settings → Kody Rules** and map each policy section to the appropriate scope.

| Policy section    | Rule type  | Scope example                     | Severity |
| ----------------- | ---------- | --------------------------------- | -------- |
| Error handling    | File-level | `backend/**/*.ts`                 | High     |
| Architecture      | PR-level   | All files via `pr_files_diff`     | Critical |
| Logging & tracing | File-level | `web/apps/**/controllers/**/*.ts` | Medium   |
| Security / PII    | File + MCP | `**/*` with PII list fetch        | Critical |

### File-level example

```
Name: Enforce tracing fields on new endpoints
Scope: File
Paths: web/apps/**/controllers/**/*.ts
Severity: High
Instructions:
  Compare fileDiff with Architecture → New endpoints in @file:docs/engineering-standards.md.
  Flag handlers that lack requestId tracing AND structured log statements.
  Quote the diff chunk that violates the policy.
```

### PR-level example

```
Name: Require feature flags for risky changes
Scope: Pull Request
Severity: Critical
Instructions:
  Scan pr_files_diff for routes/services/domain files that add major functionality.
  If no feature flag file is touched, cite “Architecture → Feature flags are mandatory” and request the rollout plan.
```

Need fresh data to evaluate the rule? Call MCP inside the instructions:

```
Use @MCP:policy_pack.getSection({"id":"security"}) to fetch the latest restricted fields.
```

<Info>
  Rules already understand variables (`fileDiff`, `pr_files_diff`, etc.), file references, and MCP invocations. See the full matrix in the [Kody Rules guide](/how_to_use/en/code_review/configs/kody_rules).
</Info>

## Phase 4 – Mirror external standards via MCP (optional)

Sometimes the handbook (or part of it) must stay in Notion, Confluence, Google Docs, or another system. You can still feed it into Kody:

1. Build or adopt a remote MCP endpoint that exposes `listSections()` and `getSection(id)`.
2. Install it via **Add Custom Plugin**. Follow the [custom plugin guide](/cookbook/en/custom-plugin-install) for the exact flow.
3. Replace `@file` references with `@MCP:policy_pack.getSection({"id":"architecture"})`.
4. Cache responses on the MCP server so multiple rules share the payload per review.

Now Kody enforces the same standards regardless of where the document lives.

## Phase 5 – Test, observe, and keep it alive

<AccordionGroup>
  <Accordion title="Seed a verification PR">
    Create a throwaway PR that violates each section. Mention @kody and ensure the inline + PR-level comments cite the right bullets.
  </Accordion>

  <Accordion title="Tune noise and severity">
    During rollout, watch how often each rule fires. Tighten file globs, add exclusions, or adjust severity until the signal meets expectations.
  </Accordion>

  <Accordion title="Update docs and rules together">
    Whenever the handbook changes, update the markdown (or MCP payload) and the related rules in the same PR so reviewers can validate the entire pipeline.
  </Accordion>
</AccordionGroup>

## Quick checklist

* [ ] `docs/engineering-standards.md` (or MCP equivalent) exists with scannable, tagged bullets.
* [ ] Every rule references the policy pack via `@file` or `@MCP`, ensuring it reads the latest text.
* [ ] File-level and PR-level Kody Rules cover your critical sections.
* [ ] Optional MCP plugin mirrors off-repo standards when needed.
* [ ] A dry-run PR confirmed the inline comments and PR summary before broad rollout.


# Kodus for monorepos
Source: https://docs.kodus.io/cookbook/en/kodus-for-monorepos

Configure directory-level rules, path-specific overrides, and rule inheritance to get precise code reviews in a monorepo.

## The challenge

In a monorepo, different packages have different standards. Your React frontend cares about component patterns, your NestJS backend cares about dependency injection, and your shared libs care about API stability. A one-size-fits-all review doesn't work.

## Strategy overview

Kodus supports three config levels that map naturally to a monorepo:

| Level            | Applies to         | Example                                |
| ---------------- | ------------------ | -------------------------------------- |
| **Organization** | All repos          | "Never commit `.env` files"            |
| **Repository**   | The monorepo       | "Use conventional commits"             |
| **Directory**    | A specific package | "React components must use PascalCase" |

## Step 1 — Map your packages

Identify the distinct areas in your monorepo and their review needs:

```
monorepo/
├── apps/
│   ├── web/          → React rules, component patterns
│   ├── api/          → NestJS rules, architecture boundaries
│   └── mobile/       → React Native rules
├── libs/
│   ├── shared/       → API stability, breaking change detection
│   └── ui/           → Design system compliance
└── infra/            → Terraform/IaC rules
```

## Step 2 — Create directory-level configs

Go to **Code Review Settings** → **Repository** → click on a directory to configure it.

Each directory can have its own:

* **Kody Rules** (file-level and PR-level)
* **Review options** (which analysis types to enable)
* **Suggestion control** (severity filters, max suggestions)
* **Ignored paths**

## Step 3 — Write targeted rules

### Frontend rules (scope: `apps/web/`)

```
Name: React components must use design system tokens
Scope: File
Paths: apps/web/src/components/**/*.tsx
Severity: High
Instructions:
  Check fileDiff for hardcoded colors, spacing, or font sizes.
  Components must import tokens from @file:libs/ui/src/tokens.ts.
  Flag any hex color, pixel value, or font-size not from the token file.
```

### Backend rules (scope: `apps/api/`)

```
Name: Domain layer must not import from infrastructure
Scope: File
Paths: apps/api/src/domain/**/*.ts
Severity: Critical
Instructions:
  Check fileDiff for any import from "../infrastructure",
  "../../infrastructure", or any path containing "/infrastructure/".
  Domain modules must only depend on other domain modules
  and shared interfaces.
```

### Shared library rules (scope: `libs/shared/`)

```
Name: Public API changes require changeset
Scope: Pull Request
Severity: High
Instructions:
  If pr_files_diff modifies any file in libs/shared/src/index.ts
  or adds/removes exports, check that a changeset file exists
  in the .changeset/ directory. If missing, flag it as a
  potential breaking change without documentation.
```

## Step 4 — Use Memories for cross-cutting conventions

Some conventions apply everywhere. Teach them as Memories:

```
@kody remember: in this monorepo, all packages use ESM imports.
CommonJS require() is not allowed anywhere.
```

```
@kody remember: shared libs must maintain backward compatibility.
Any breaking change requires a major version bump and a changeset.
```

## Step 5 — Configure suggestion control per directory

High-traffic packages might need stricter limits:

* **apps/web/** — max 5 suggestions, medium severity filter (frontend moves fast)
* **libs/shared/** — max 15 suggestions, low severity filter (stability matters)
* **infra/** — max 3 suggestions, high severity filter (fewer but critical)

## Step 6 — Ignore generated paths

Add monorepo-specific ignores to avoid noise:

```yaml theme={null}
ignorePaths:
  - "**/node_modules/**"
  - "**/dist/**"
  - "**/build/**"
  - "**/*.generated.ts"
  - "**/prisma/migrations/**"
  - "**/coverage/**"
```

## Tips

* Start with 2-3 rules per directory and expand based on what your team actually flags in reviews
* Use rule inheritance — org-level rules cover security, repo-level covers conventions, directory-level covers architecture
* If a rule fires too often in one package but is valid elsewhere, exclude that directory from the rule rather than weakening it

For more on directory configs, see [Directory-Level Configuration](/how_to_use/en/code_review/configs/directory_level). For rule inheritance, see [Rules Inheritance](/how_to_use/en/code_review/configs/rules_inheritance).


# Kodus + sprint workflow
Source: https://docs.kodus.io/cookbook/en/kodus-sprint-workflow

Integrate business logic validation into your sprint cycle so every PR is validated against task requirements before merge.

## The gap in most sprint workflows

Teams track requirements in Jira, Linear, or Notion. Developers implement them in PRs. But nobody systematically checks whether the PR actually covers all the acceptance criteria — until QA finds gaps in staging.

This cookbook closes that loop by validating PRs against task requirements automatically.

## The workflow

```
Task created (Jira/Linear/Notion)
    ↓
Developer implements → Opens PR
    ↓
Kodus automatically:
  1. Fetches task context from the linked tool
  2. Compares PR diff against acceptance criteria
  3. Reports missing/partial implementations
    ↓
Developer addresses findings → Re-validates
    ↓
Merge with confidence
```

## Step 1 — Connect your task management tool

Go to **Settings** → **Plugins** and connect your tool:

* **Jira** — for teams using Atlassian
* **Linear** — for teams using Linear
* **Notion** — for teams using Notion as a task tracker
* **ClickUp** — for teams using ClickUp

Once connected, Kodus can automatically fetch task context during reviews.

## Step 2 — Enable business logic validation

It's enabled by default, but verify:

```yaml theme={null}
reviewOptions:
  business_logic: true
```

## Step 3 — Write good acceptance criteria

The quality of validation depends entirely on the quality of your task descriptions. Kodus classifies task context as:

| Quality      | What it means                             | What to do                                       |
| ------------ | ----------------------------------------- | ------------------------------------------------ |
| **Complete** | Title + description + acceptance criteria | Best results — criterion-by-criterion validation |
| **Partial**  | Title + description, no criteria          | Decent results — behavior-based analysis         |
| **Minimal**  | Just a title                              | Poor results — only obvious gaps flagged         |

**Template for Jira/Linear tasks:**

```
## Description
Brief context about what needs to change and why.

## Acceptance Criteria
1. Users with role "admin" can delete any comment
2. Users can only edit their own comments within 24 hours
3. Deleted comments show "[removed]" placeholder
4. Audit log records who deleted what and when
5. API returns 403 for unauthorized delete attempts
```

## Step 4 — Use on-demand validation during development

Before marking a PR as ready, developers can self-check:

```
@kody -v business-logic https://kodustech.atlassian.net/browse/KC-1292
```

This catches gaps early, before the reviewer even looks at the PR.

## Step 5 — Teach sprint conventions as Memories

```
@kody remember: every PR must be linked to a Jira ticket.
PRs without a linked ticket should be flagged.
```

```
@kody remember: acceptance criteria marked as "out of scope"
in the ticket should not be flagged as missing.
```

## Step 6 — Create a PR requirement rule

```
Name: PR must reference a task
Scope: Pull Request
Severity: Medium
Instructions:
  Check pr_description and pr_title for a task reference
  (e.g., KC-1234, TEAM-456, or a URL to Jira/Linear/Notion).
  If no task reference is found, flag it and ask the developer
  to link the relevant task for business logic validation.
```

## The result

After setup, every PR in your sprint gets:

1. **Code quality review** — security, performance, style (standard Kodus)
2. **Business logic validation** — are all acceptance criteria implemented?
3. **Scope mismatch detection** — is this PR even working on the right task?

QA finds fewer gaps, sprint demos go smoother, and "I thought that was done" becomes rare.

## Tips

* Encourage the team to write numbered acceptance criteria — they get the best validation
* Use on-demand validation during development, not just at review time
* If a PR intentionally doesn't cover all criteria (phased delivery), note it in the PR description so Kody can account for it

For details, see [Business Logic Validation](/how_to_use/en/code_review/business_logic_validation).


# Security-first review pipeline
Source: https://docs.kodus.io/cookbook/en/security-first-review-pipeline

Set up Kody Rules focused on OWASP top 10, secrets detection, and secure coding patterns.

## Why a security-focused pipeline

Generic code review catches style and bugs. But security vulnerabilities — SQL injection, hardcoded secrets, insecure auth patterns — need dedicated rules that treat findings as critical blockers.

This cookbook sets up a security-first layer on top of your existing review.

## Step 1 — Enable security analysis

Make sure security analysis is enabled:

```yaml theme={null}
reviewOptions:
  security: true
```

This gives you Kodus' built-in security checks. The rules below add your team's specific security policies on top.

## Step 2 — Create OWASP-focused rules

### SQL injection prevention

```
Name: No raw SQL queries
Scope: File
Paths: **/*.ts, **/*.js, **/*.py
Severity: Critical
Instructions:
  Flag any use of string concatenation or template literals
  to build SQL queries. Look for patterns like:
  - `query("SELECT ... " + variable)`
  - `query(\`SELECT ... ${variable}\`)`
  - `execute(f"SELECT ... {variable}")`
  Must use parameterized queries or an ORM instead.
```

### Hardcoded secrets detection

```
Name: No hardcoded secrets or credentials
Scope: File
Paths: **/*
Severity: Critical
Instructions:
  Flag any string that looks like an API key, password,
  token, or secret in fileDiff. Patterns to catch:
  - Variables named *_KEY, *_SECRET, *_TOKEN, *_PASSWORD
    assigned to string literals
  - Strings matching patterns like "sk_live_", "ghp_",
    "AKIA", "Bearer " followed by a long string
  - Connection strings with embedded passwords
  Secrets must come from environment variables or a vault.
```

### Authentication bypass

```
Name: Auth middleware must not be skipped
Scope: Pull Request
Severity: Critical
Instructions:
  Check pr_files_diff for any route or controller that
  handles user data without auth middleware. Look for:
  - New routes without @UseGuards, @Authenticated,
    or equivalent decorators
  - Middleware bypass patterns like skipAuth: true
  - Public endpoints that access user-specific data
  Reference @file:src/shared/auth/guards/ for the
  approved auth patterns.
```

### XSS prevention

```
Name: No dangerouslySetInnerHTML without sanitization
Scope: File
Paths: **/*.tsx, **/*.jsx
Severity: Critical
Instructions:
  Flag any use of dangerouslySetInnerHTML in fileDiff.
  If used, verify the input is sanitized with DOMPurify
  or an equivalent library. Unsanitized HTML injection
  is a critical XSS vulnerability.
```

## Step 3 — Teach security Memories

Create persistent conventions that apply everywhere:

```
@kody remember: all user input must be validated and sanitized
before use. Never trust client-side data.
```

```
@kody remember: all API endpoints that handle sensitive data
must use HTTPS only and include rate limiting.
```

```
@kody remember: error messages must never expose stack traces,
internal paths, or database details to the client.
```

## Step 4 — Configure for zero tolerance

For security rules, you want critical findings to block:

1. Enable **Request Changes** in PR Workflow settings so Kody requests changes when critical issues are found
2. Set security rules to **Critical** severity so they always surface above any severity filter
3. Do NOT set a low `maxSuggestions` limit — security findings should never be suppressed

## Step 5 — Add a dependency audit rule (optional)

If you use MCP plugins, you can check dependencies:

```
Name: No known vulnerable dependencies
Scope: Pull Request
Severity: Critical
Instructions:
  If pr_files_diff modifies package.json, requirements.txt,
  or any dependency file, use @MCP to check for known
  vulnerabilities in the added or updated packages.
  Flag any dependency with known critical CVEs.
```

## Checklist

* [ ] Security analysis enabled in reviewOptions
* [ ] SQL injection rule covers all DB-interacting code
* [ ] Secrets detection rule covers all file types
* [ ] Auth bypass rule references your actual auth patterns
* [ ] XSS rule covers all frontend component files
* [ ] Security Memories teach general secure coding principles
* [ ] Request Changes enabled for critical findings
* [ ] A test PR confirmed rules fire correctly

For more on configuring rules, see [Kody Rules](/how_to_use/en/code_review/configs/kody_rules).


# Onboarding a new team
Source: https://docs.kodus.io/cookbook/en/team-onboarding

Step-by-step guide to set up Kodus for a new team — from connecting repos to teaching your first conventions.

## Overview

Getting a new team up and running with Kodus takes about 30 minutes. This guide walks through the complete setup so your team gets value from the first PR.

## Step 1 — Create and configure the workspace

1. Sign up at [kodus.io](https://kodus.io) or access your self-hosted instance
2. Create a new workspace for your team
3. Connect your Git provider (GitHub, GitLab, Bitbucket, or Azure DevOps)
4. Select the repositories to monitor

## Step 2 — Set the review baseline

Start with sensible defaults before customizing:

```yaml theme={null}
# kodus-config.yml — drop this in each repo root
reviewOptions:
  security: true
  code_style: true
  kody_rules: true
  refactoring: true
  error_handling: true
  maintainability: true
  potential_issues: true
  performance_and_optimization: true
  business_logic: true

suggestionControl:
  groupingMode: full
  limitationType: pr
  maxSuggestions: 9
  severityLevelFilter: medium

automatedReviewActive: true
```

This gives you automated reviews with a reasonable suggestion limit. Adjust after a week based on feedback.

## Step 3 — Import existing rules from IDE tools

If your team already uses Cursor, Copilot, or Claude rules:

1. Go to **Code Review Settings** → **Kody Rules**
2. Kodus detects `.cursorrules`, `.github/copilot-instructions.md`, and `.claude` files
3. Import the ones that make sense for code review

This avoids having to rewrite rules from scratch.

## Step 4 — Teach your top 5 conventions

Don't try to encode everything on day one. Start with the 5 conventions your team argues about most:

```
@kody remember: we use camelCase for variables and PascalCase for types.
```

```
@kody remember: all API responses use the standard envelope format
{ data, error, meta }.
```

```
@kody remember: we prefer composition over inheritance.
Use interfaces and dependency injection.
```

```
@kody remember: every public function must have JSDoc with
@param and @returns descriptions.
```

```
@kody remember: database queries go through the repository layer only.
No direct DB access from services or controllers.
```

These become Memories that apply immediately to all reviews.

## Step 5 — Create 2-3 critical rules

Add rules for things that must never happen:

```
Name: No console.log in production code
Scope: File
Paths: src/**/*.ts
Severity: High
Instructions: Flag any console.log, console.warn, or console.error
in fileDiff. Use the project logger instead.
Exclude test files (*.spec.ts, *.test.ts).
```

```
Name: No hardcoded API URLs
Scope: File
Paths: src/**/*.ts
Severity: Critical
Instructions: Flag any hardcoded URL (http:// or https://)
in fileDiff that looks like an API endpoint.
URLs must come from environment variables or config files.
```

## Step 6 — Connect task management (optional but recommended)

Connect Jira, Linear, Notion, or ClickUp in **Settings** → **Plugins** to enable business logic validation. This lets Kodus check if PRs implement what the tasks describe.

## Step 7 — Run a pilot PR

Open a test PR and verify:

* [ ] Kodus comments appear on the PR
* [ ] Suggestions are relevant and at the right severity
* [ ] Your custom rules fire when they should
* [ ] Memories are reflected in the review context

## Step 8 — Gather feedback after one week

After a week of reviews, check in with the team:

* Are there too many suggestions? → Raise `severityLevelFilter` or lower `maxSuggestions`
* Are rules too noisy? → Narrow the file paths or add exclusions
* Missing important patterns? → Add new rules or Memories
* Want auto-generated rules? → Click **Generate Kody Rules** to get suggestions from review history

## Tips

* Don't overload with rules on day one — start small and grow
* Let the team teach Kody naturally through conversation before formalizing as rules
* Use `@kody start-review` for the first few PRs so the team sees Kodus in action
* Enable LLM-generated memories approval if you want to review what Kody learns

For the full setup guide, see [Quickstart](/how_to_use/en/quickstart).


# Fireworks AI - Fast Inference Platform
Source: https://docs.kodus.io/knowledge_base/en/how-to-use-fireworks-with-kodus

Learn how to use Fireworks AI's models with Kodus

## How Fireworks AI works

Fireworks AI is the fastest inference platform for generative AI, designed to build and run magical AI applications in seconds. The platform provides serverless access to popular open-source models like DeepSeek, Llama, Qwen, and Mistral with optimized speed, high throughput, and minimal latency. Built for developers who need reliable, blazing-fast AI infrastructure without GPU management complexity.

## Recommended Models

We recommend good coding models with competitive pricing and high context windows.

<Info>
  For the most updated information, please visit [Fireworks AI's pricing page](https://fireworks.ai/pricing).
</Info>

| Model                              | Pricing (1M tokens) | Context Window |
| ---------------------------------- | ------------------- | -------------- |
| **Llama 4 Maverick** `recommended` | $0.22/$0.88         | \~131k tokens  |
| **Llama 4 Scout**                  | $0.15/$0.60         | \~131k tokens  |
| **DeepSeek V3**                    | \$0.90              | \~128k tokens  |
| **Qwen3 235B**                     | $0.22/$0.88         | \~131k tokens  |

## Creating API Key

<Warning>Fireworks AI Account is required to create API Key.</Warning>

Go directly to [Fireworks AI Console](https://app.fireworks.ai) to create a new API Key.

Or, follow these steps:

1. Visit [app.fireworks.ai](https://app.fireworks.ai) and create an account or sign in
2. Once logged in, navigate to the **API Keys** page in your account settings
3. Click **"Create API Key"** button
4. Give your key a descriptive name (e.g., 'Kodus' or any name you prefer)
5. Click **"Create"** to generate the key
6. Copy the API key immediately and save it somewhere secure - you won't be able to see it again

<Info>
  New accounts come with \$1 in free credits to get started with your projects.
</Info>

## How to use

<Snippet />

### Configure Fireworks AI in Environment File

Edit your `.env` file and configure the core settings. For **LLM Integration**, use Fireworks AI in Fixed Mode:

```env theme={null}
# Core System Settings (update with your domains)
WEB_HOSTNAME_API="kodus-api.yourdomain.com"    
WEB_PORT_API=443                               
NEXTAUTH_URL="https://kodus-web.yourdomain.com"

# Security Keys (generate with openssl commands above)
WEB_NEXTAUTH_SECRET="your-generated-secret"
API_CRYPTO_KEY="your-generated-hex-key"
API_JWT_SECRET="your-generated-secret"
API_JWT_REFRESH_SECRET="your-generated-secret"

# Database Configuration
API_PG_DB_PASSWORD="your-secure-db-password"
API_MG_DB_PASSWORD="your-secure-db-password"

# Fireworks AI Configuration (Fixed Mode) 
API_LLM_PROVIDER_MODEL="accounts/fireworks/models/llama4-maverick-instruct-basic"  # Choose your preferred model
API_OPENAI_FORCE_BASE_URL="https://api.fireworks.ai/inference/v1"                  # Fireworks AI API URL  
API_OPEN_AI_API_KEY="your-fireworks-api-key"                                       # Your Fireworks AI API Key

# Git Provider Webhooks (choose your provider)
API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"
# or API_GITLAB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/gitlab/webhook"
# or GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/bitbucket/webhook"
```

<Note>
  Webhook URLs must reach the Webhooks service (port 3332). Use a dedicated webhooks domain or route `/.../webhook` to port 3332 in your reverse proxy.
</Note>

<Info>
  **Fixed Mode is ideal for Fireworks AI** because it provides OpenAI-compatible APIs with blazing-fast inference speeds and access to cutting-edge open-source models with zero setup time.
</Info>

<Snippet />

### Set Up Reverse Proxy (For Production)

For webhooks and external access, configure Nginx:

```nginx theme={null}
# Web App (port 3000)
server {
    listen 80;
    server_name kodus-web.yourdomain.com;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# API (port 3001)  
server {
    listen 80;
    server_name kodus-api.yourdomain.com;
    location ~ ^/(github|gitlab|bitbucket|azure-repos)/webhook {
        proxy_pass http://localhost:3332;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### Verify Fireworks AI Integration

In addition to the basic installation verification, confirm that Fireworks AI is working:

```bash theme={null}
# Verify Fireworks AI API connection specifically
docker-compose logs api worker | grep -i fireworks
```

<Tip>
  For detailed information about SSL setup, monitoring, and advanced configurations, see our [complete deployment guide](https://docs.kodus.io/docs/how_to_deploy/en/deploy_kodus/generic_vm).
</Tip>

### Troubleshooting

<AccordionGroup>
  <Accordion title="API Key Issues">
    * Verify your API key is correct and active in [Fireworks AI Console](https://app.fireworks.ai)
    * Check if you have sufficient credits in your Fireworks AI account
    * Ensure there are no extra spaces in your `.env` file
    * New accounts receive \$1 in free credits to get started
  </Accordion>

  <Accordion title="Model Not Found">
    * Check if the model name is correctly spelled in your configuration
    * Verify the model is available in Fireworks AI's current model library
    * Try with a different model from our recommended list
    * Check the [Fireworks AI models documentation](https://docs.fireworks.ai/getting-started/recommended-open-models)
  </Accordion>

  <Accordion title="Connection Errors">
    * Verify your server has internet access to reach `api.fireworks.ai`
    * Check if there are any firewall restrictions
    * Review the API/worker logs for detailed error messages
    * Ensure you're using the correct API endpoint
  </Accordion>

  <Accordion title="Performance Issues">
    * Fireworks AI provides industry-leading speeds with minimal latency
    * Check your network connectivity for optimal performance
    * Consider using dedicated deployments for enterprise workloads
    * Monitor your usage patterns to optimize API calls
  </Accordion>

  <Accordion title="Rate Limiting">
    * Fireworks AI provides high rate limits on serverless infrastructure
    * Check your current usage in the Fireworks AI dashboard
    * Consider upgrading to dedicated deployments for higher throughput
    * Contact Fireworks AI support for enterprise rate limit adjustments
  </Accordion>
</AccordionGroup>


# Groq Cloud - Ultra-Fast Inference
Source: https://docs.kodus.io/knowledge_base/en/how-to-use-groq-with-kodus

Learn how to use Groq's models with Kodus

## How Groq works

Groq Cloud provides fast LLM inference with OpenAI-compatible APIs. Built for speed and simplicity, Groq offers ultra-fast inference for popular models like Llama, Deepseek, and more. The platform is designed to be simple to integrate and easy to scale, making it perfect for production applications.

## Recommended Models

We recommend good coding models with high context windows and fast inference.

<Info>
  For the most updated information, please visit [Groq's models page](https://console.groq.com/docs/models).
</Info>

| Model                                     | Context Window | Speed      |
| ----------------------------------------- | -------------- | ---------- |
| **Llama 3.3 70B Versatile** `recommended` | \~128k tokens  | Ultra Fast |
| **Deepseek R1 Distill Llama 70B**         | \~128k tokens  | Ultra Fast |
| **Llama 3.1 70B Versatile**               | \~128k tokens  | Ultra Fast |

## Creating API Key

<Warning>Groq Cloud Account is required to create API Key.</Warning>

Go directly to [Groq's API Keys page](https://console.groq.com/keys) to create a new API Key.

Or, follow these steps:

1. Go to [Groq Console](https://console.groq.com)
2. Sign in or create your account
3. Navigate to "API Keys" in the top navigation
4. Click on "Create API Key" button
5. Give it a name like 'Kodus' or any descriptive name
6. Copy the API Key and save it somewhere safe

<Info>
  Only team owners or users with the developer role may create or manage API keys in Groq.
</Info>

## How to use

<Snippet />

### Configure Groq in Environment File

Edit your `.env` file and configure the core settings. For **LLM Integration**, use Groq in Fixed Mode:

```env theme={null}
# Core System Settings (update with your domains)
WEB_HOSTNAME_API="kodus-api.yourdomain.com"    
WEB_PORT_API=443                               
NEXTAUTH_URL="https://kodus-web.yourdomain.com"

# Security Keys (generate with openssl commands above)
WEB_NEXTAUTH_SECRET="your-generated-secret"
API_CRYPTO_KEY="your-generated-hex-key"
API_JWT_SECRET="your-generated-secret"
API_JWT_REFRESH_SECRET="your-generated-secret"

# Database Configuration
API_PG_DB_PASSWORD="your-secure-db-password"
API_MG_DB_PASSWORD="your-secure-db-password"

# Groq Configuration (Fixed Mode) 
API_LLM_PROVIDER_MODEL="llama-3.3-70b-versatile"             # Choose your preferred model
API_OPENAI_FORCE_BASE_URL="https://api.groq.com/openai/v1"   # Groq API URL
API_OPEN_AI_API_KEY="your-groq-api-key"                      # Your Groq API Key

# Git Provider Webhooks (choose your provider)
API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"
# or API_GITLAB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/gitlab/webhook"
# or GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/bitbucket/webhook"
```

<Note>
  Webhook URLs must reach the Webhooks service (port 3332). Use a dedicated webhooks domain or route `/.../webhook` to port 3332 in your reverse proxy.
</Note>

<Info>
  **Fixed Mode is ideal for Groq** because it provides OpenAI-compatible APIs with ultra-fast inference. This gives you the best performance with simple configuration.
</Info>

<Snippet />

### Set Up Reverse Proxy (For Production)

For webhooks and external access, configure Nginx:

```nginx theme={null}
# Web App (port 3000)
server {
    listen 80;
    server_name kodus-web.yourdomain.com;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# API (port 3001)  
server {
    listen 80;
    server_name kodus-api.yourdomain.com;
    location ~ ^/(github|gitlab|bitbucket|azure-repos)/webhook {
        proxy_pass http://localhost:3332;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### Verify Groq Integration

In addition to the basic installation verification, confirm that Groq is working:

```bash theme={null}
# Verify Groq API connection specifically
docker-compose logs api worker | grep -i groq
```

<Tip>
  For detailed information about SSL setup, monitoring, and advanced configurations, see our [complete deployment guide](https://docs.kodus.io/docs/how_to_deploy/en/deploy_kodus/generic_vm).
</Tip>

### Troubleshooting

<AccordionGroup>
  <Accordion title="API Key Issues">
    * Verify your API key is correct and active in [Groq Console](https://console.groq.com/keys)
    * Check if you have sufficient credits or quota in your Groq account
    * Ensure there are no extra spaces in your `.env` file
  </Accordion>

  <Accordion title="Model Not Found">
    * Check if the model name is correctly spelled in your configuration
    * Verify the model is available in Groq's current model list
    * Try with a different model from our recommended list
  </Accordion>

  <Accordion title="Connection Errors">
    * Verify your server has internet access to reach `api.groq.com`
    * Check if there are any firewall restrictions
    * Review the API/worker logs for detailed error messages
  </Accordion>

  <Accordion title="Rate Limiting">
    * Groq has rate limits based on your plan
    * Check the [Groq rate limits documentation](https://console.groq.com/docs/rate-limits)
    * Consider upgrading your plan for higher limits
  </Accordion>
</AccordionGroup>


# Novita AI - Serverless GPU Platform
Source: https://docs.kodus.io/knowledge_base/en/how-to-use-novita-with-kodus

Learn how to use Novita's models with Kodus

## How Novita works

Novita is a serverless infrastructure platform for AI, designed to scale open-source models with low latency and reduced cost. It supports hundreds of production-ready models — including Llama, Mistral, Claude, and Stable Diffusion — and provides optimized APIs, on-demand GPUs, and custom model deployments without any DevOps overhead.

## Recommended Models

We recommend good coding models with +100k context window.

<Info>
  To more updated information, please visit [Novita's website](https://novita.ai/models/llm).
</Info>

| Model                              | Pricing     | Context Window |
| ---------------------------------- | ----------- | -------------- |
| **Deepseek v3 0324** `recommended` | \$0.33/1.3  | \~128k tokens  |
| **Deepseek R1 0528**               | \$0.7/2.5   | \~128k tokens  |
| **Llama 4 Maverick Instruct**      | \$0.17/0.85 | \~100k tokens  |

## Creating API Key

<Warning>Novita Account is required to create API Key.</Warning>

Go directly to [Novita's API Keys page](https://novita.ai/settings/key-management) to create a new API Key.

Or, follow these steps:

1. Go to your Novita console
2. Click on the "Manage API Keys" button or go to your profile picture and click API Keys
3. Click on "Add New Key" and fill with 'Kodus' or any name you want
4. Click on "Confirm"
5. Copy the API Key and save it somewhere safe

<Snippet />

### Configure Novita in Environment File

Edit your `.env` file and configure the core settings. For **LLM Integration**, use Novita in Fixed Mode:

```env theme={null}
# Core System Settings (update with your domains)
WEB_HOSTNAME_API="kodus-api.yourdomain.com"    
WEB_PORT_API=443                               
NEXTAUTH_URL="https://kodus-web.yourdomain.com"

# Security Keys (generate with openssl commands above)
WEB_NEXTAUTH_SECRET="your-generated-secret"
API_CRYPTO_KEY="your-generated-hex-key"
API_JWT_SECRET="your-generated-secret"
API_JWT_REFRESH_SECRET="your-generated-secret"

# Database Configuration
API_PG_DB_PASSWORD="your-secure-db-password"
API_MG_DB_PASSWORD="your-secure-db-password"

# Novita Configuration (Fixed Mode) 
API_LLM_PROVIDER_MODEL="deepseek-v3-0324"                    # Choose your preferred model
API_OPENAI_FORCE_BASE_URL="https://api.novita.ai/v3/openai"  # Novita API URL
API_OPEN_AI_API_KEY="your-novita-api-key"                    # Your Novita API Key

# Git Provider Webhooks (choose your provider)
API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"
# or API_GITLAB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/gitlab/webhook"
# or GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/bitbucket/webhook"
```

<Note>
  Webhook URLs must reach the Webhooks service (port 3332). Use a dedicated webhooks domain or route `/.../webhook` to port 3332 in your reverse proxy.
</Note>

<Info>
  **Fixed Mode is ideal for Novita** because it provides OpenAI-compatible APIs and requires only one API key. This simplifies your setup significantly.
</Info>

<Snippet />

### 6. Set Up Reverse Proxy (For Production)

For webhooks and external access, configure Nginx:

```nginx theme={null}
# Web App (port 3000)
server {
    listen 80;
    server_name kodus-web.yourdomain.com;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# API (port 3001)  
server {
    listen 80;
    server_name kodus-api.yourdomain.com;
    location ~ ^/(github|gitlab|bitbucket|azure-repos)/webhook {
        proxy_pass http://localhost:3332;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### Verify Novita Integration

In addition to the basic installation verification, confirm that Novita is working:

```bash theme={null}
# Verify Novita API connection specifically
docker-compose logs api worker | grep -i novita
```

<Tip>
  For detailed information about SSL setup, monitoring, and advanced configurations, see our [complete deployment guide](https://docs.kodus.io/docs/how_to_deploy/en/deploy_kodus/generic_vm).
</Tip>

### Troubleshooting

<AccordionGroup>
  <Accordion title="API Key Issues">
    * Verify your API key is correct and active in [Novita's console](https://novita.ai/settings/key-management)
    * Check if you have sufficient credits in your Novita account
    * Ensure there are no extra spaces in your `.env` file
  </Accordion>

  <Accordion title="Model Not Found">
    * Check if the model name is correctly spelled in your configuration
    * Verify the model is available in your Novita plan
    * Try with a different model from our recommended list
  </Accordion>

  <Accordion title="Connection Errors">
    * Verify your server has internet access to reach `api.novita.ai`
    * Check if there are any firewall restrictions
    * Review the API/worker logs for detailed error messages
  </Accordion>
</AccordionGroup>


# Together AI - Open Source Models
Source: https://docs.kodus.io/knowledge_base/en/how-to-use-together-ai-with-kodus

Learn how to use Together AI's models with Kodus

## How Together AI works

Together AI makes it easy to run leading open-source models using only a few lines of code. The platform provides fast inference, OpenAI-compatible APIs, and access to cutting-edge models like Llama 4, DeepSeek, and more. Built for developers who need reliable, scalable AI infrastructure without the complexity.

## Recommended Models

We recommend good coding models with high context windows and competitive pricing.

<Info>
  For the most updated information, please visit [Together AI's pricing page](https://www.together.ai/pricing).
</Info>

| Model                              | Pricing (1M tokens) | Context Window |
| ---------------------------------- | ------------------- | -------------- |
| **Llama 4 Maverick** `recommended` | $0.27/$0.85         | \~128k tokens  |
| **DeepSeek-V3**                    | \$1.25              | \~128k tokens  |
| **Llama 3.1 70B Turbo**            | \$0.88              | \~128k tokens  |
| **Qwen 2.5 72B**                   | \$1.20              | \~128k tokens  |

## Creating API Key

<Warning>Together AI Account is required to create API Key.</Warning>

Go directly to [Together AI Console](https://api.together.ai) to create a new API Key.

Or, follow these steps:

1. Create an account at [api.together.ai](https://api.together.ai) or log in if you have one already
2. In the main dashboard, scroll down to the "Manage Account" section
3. In the "API Keys" card, click on "Manage Keys" button
4. Click on "Add Key" button
5. Give it a name like 'Kodus' or any descriptive name
6. Copy your API key, and you're ready to go!

<Info>
  New accounts come with \$1 credit to get started for free.
</Info>

## How to use

<Snippet />

### Configure Together AI in Environment File

Edit your `.env` file and configure the core settings. For **LLM Integration**, use Together AI in Fixed Mode:

```env theme={null}
# Core System Settings (update with your domains)
WEB_HOSTNAME_API="kodus-api.yourdomain.com"    
WEB_PORT_API=443                               
NEXTAUTH_URL="https://kodus-web.yourdomain.com"

# Security Keys (generate with openssl commands above)
WEB_NEXTAUTH_SECRET="your-generated-secret"
API_CRYPTO_KEY="your-generated-hex-key"
API_JWT_SECRET="your-generated-secret"
API_JWT_REFRESH_SECRET="your-generated-secret"

# Database Configuration
API_PG_DB_PASSWORD="your-secure-db-password"
API_MG_DB_PASSWORD="your-secure-db-password"

# Together AI Configuration (Fixed Mode) 
API_LLM_PROVIDER_MODEL="meta-llama/Meta-Llama-4-Maverick-Instruct"  # Choose your preferred model
API_OPENAI_FORCE_BASE_URL="https://api.together.xyz/v1"             # Together AI API URL  
API_OPEN_AI_API_KEY="your-together-api-key"                         # Your Together AI API Key

# Git Provider Webhooks (choose your provider)
API_GITHUB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/github/webhook"
# or API_GITLAB_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/gitlab/webhook"
# or GLOBAL_BITBUCKET_CODE_MANAGEMENT_WEBHOOK="https://kodus-api.yourdomain.com/bitbucket/webhook"
```

<Note>
  Webhook URLs must reach the Webhooks service (port 3332). Use a dedicated webhooks domain or route `/.../webhook` to port 3332 in your reverse proxy.
</Note>

<Info>
  **Fixed Mode is ideal for Together AI** because it provides OpenAI-compatible APIs with competitive pricing and access to cutting-edge open-source models.
</Info>

<Snippet />

### Set Up Reverse Proxy (For Production)

For webhooks and external access, configure Nginx:

```nginx theme={null}
# Web App (port 3000)
server {
    listen 80;
    server_name kodus-web.yourdomain.com;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# API (port 3001)  
server {
    listen 80;
    server_name kodus-api.yourdomain.com;
    location ~ ^/(github|gitlab|bitbucket|azure-repos)/webhook {
        proxy_pass http://localhost:3332;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://localhost:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### Verify Together AI Integration

In addition to the basic installation verification, confirm that Together AI is working:

```bash theme={null}
# Verify Together AI API connection specifically
docker-compose logs api worker | grep -i together
```

<Tip>
  For detailed information about SSL setup, monitoring, and advanced configurations, see our [complete deployment guide](https://docs.kodus.io/docs/how_to_deploy/en/deploy_kodus/generic_vm).
</Tip>

### Troubleshooting

<AccordionGroup>
  <Accordion title="API Key Issues">
    * Verify your API key is correct and active in [Together AI Console](https://api.together.ai)
    * Check if you have sufficient credits in your Together AI account
    * Ensure there are no extra spaces in your `.env` file
    * New accounts receive \$1 in free credits
  </Accordion>

  <Accordion title="Model Not Found">
    * Check if the model name is correctly spelled in your configuration
    * Verify the model is available in Together AI's current model library
    * Try with a different model from our recommended list
    * Check the [Together AI models documentation](https://docs.together.ai/docs/serverless-models)
  </Accordion>

  <Accordion title="Connection Errors">
    * Verify your server has internet access to reach `api.together.xyz`
    * Check if there are any firewall restrictions
    * Review the API/worker logs for detailed error messages
    * Ensure you're using the correct API endpoint
  </Accordion>

  <Accordion title="Rate Limiting">
    * Together AI provides generous rate limits (up to 6000 requests/min for LLMs)
    * Check your current usage in the Together AI dashboard
    * Consider upgrading to a higher tier for increased limits
    * Monitor your usage patterns to optimize API calls
  </Accordion>
</AccordionGroup>


# Changelog
Source: https://docs.kodus.io/changelog/index

Latest Kodus updates and improvements.

<div>
  <div>
    <div aria-label="Changelog filters">
      <p>Filters</p>

      <div>
        <label>
          <input type="checkbox" />

          <span>Security</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Cockpit</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>BYOK</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>AI Engine</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Self-hosted</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>GIT Provider</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Performance</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>UX & Interface</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Notifications</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Kody Rules</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>MCP</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Billing & Licenses</span>
        </label>
      </div>
    </div>
  </div>

  <div>
    <div>
      <span>July 13, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>New Token Usage Experience</div>
          <p>The Token Usage page has been redesigned to provide a more complete view of consumption.</p>
          <p>It is now easier to track costs by area, model, and review activity, as well as filter the data and drill down into more specific analyses. This helps teams better understand where tokens are being used and how they can optimize costs.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Automatic Detector Backfill for Existing Rules</div>
          <p>Organizations that created Kody Rules before this release can also benefit from the new architecture. We created an automated process that analyzes existing rules and, whenever possible, generates mechanical detectors for them.</p>
          <p>The process is incremental, safe, and does not interfere with the normal execution of rules. When a rule cannot be converted into a detector, it continues to work through the traditional semantic review flow.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>More Accurate and Predictable Kody Rules</div>
          <p>We restructured how Kody applies custom rules during code reviews. Instead of relying solely on a more open-ended agent analysis, rules are now evaluated deterministically by file and PR scope.</p>
          <p>In practice, this improves rule coverage in large PRs, reduces cases where an applicable rule is overlooked, and makes Kody Rules behave more consistently across different models.</p>
          <p>We also introduced mechanical detectors for certain rules. When a rule can safely be converted into an objective check, Kody can apply it without making an LLM call, reducing costs and improving predictability.</p>
        </div>

        <div>
          <div>Code Review Engine Improvements</div>
          <p>This release includes a major upgrade to the review agent runtime. We migrated important parts of the execution flow to a new agent harness foundation, making the system more modular, observable, and ready for future improvements.</p>
          <p>We also improved the engine used to search for evidence in the codebase, with a focus on finding more relevant cross-file references and increasing the quality of generated suggestions.</p>
        </div>

        <div>
          <div>Cleaner Review Comments</div>
          <p>We adjusted the format of Kody's review comments to prevent internal reasoning structures from appearing in the output and to make suggestions more natural, concise, and easier to understand.</p>
          <p>We also fixed issues involving aliases and internal prompt references following recent refactors.</p>
        </div>

        <div>
          <div>Improved BYOK Support</div>
          <p>We improved BYOK support across different parts of the product, including configuration, model fallback, and per-model cost calculations.</p>
          <p>We also introduced a clearer experience for viewing BYOK settings and understanding how each model affects token consumption.</p>
        </div>

        <div>
          <div>More Accurate Cost Tracking and Telemetry</div>
          <p>We improved the observability of LLM calls to ensure token usage is attributed correctly, especially within the new Kody Rules and agent workflows.</p>
          <p>This increases the accuracy of usage reports and prevents undercounting in more complex review scenarios.</p>
        </div>

        <div>
          <div>MCP Manager and Plugin Improvements</div>
          <p>We improved tenant isolation for MCP connections, enhanced connection sorting and testing, and removed legacy integrations that had already been deprecated.</p>
          <p>These changes increase the reliability of the plugins and integrations experience.</p>
        </div>

        <div>
          <div>Improvements for Self-Hosted Environments</div>
          <p>We applied fixes to Dockerfiles, provisioning scripts, and local configuration to make self-hosted environments more stable.</p>
          <p>We also fixed an issue involving pnpm on macOS and adjusted the API hostname configuration used during provisioning.</p>
        </div>

        <div>
          <div>More Stable Observability</div>
          <p>We fixed excessive memory consumption in the Mongo observability exporter and improved logging behavior across different environments.</p>
          <p>We also removed outdated references to the previous internal framework, simplifying the observability codebase.</p>
        </div>

        <div>
          <div>New Quality Tests and Validations</div>
          <p>We added new end-to-end scenarios and evaluations to validate Kody Rules, model recall, suggestion adherence, and prompt regressions.</p>
          <p>These validations help ensure that changes to models, prompts, or the underlying architecture do not reduce review quality.</p>
        </div>

        <div>
          <div>Updated Documentation</div>
          <p>We updated the documentation for BYOK, custom messages, and focused reviews. We also revised the README and added new pages explaining how to guide Kody during a review.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Safer Rule Execution:</strong> we added protections against potentially unsafe regex patterns in Kody Rules detectors. This prevents malformed or computationally expensive rules from affecting review performance. We also fixed cases where outdated detectors could remain associated with a rule after an edit changed the rule's intended behavior.</p>
          </div>

          <div>
            <p><strong>License and Billing Improvements:</strong> we fixed issues involving trial creation, the listing of inactive users or users removed from the Git organization, and active seat counts. These changes make the license page more consistent and reduce discrepancies between the organization's actual users and the users displayed in billing.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>July 6, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Steer a review with focus</div>
          <p>You can now ask Kody to pay special attention to something specific during a review, without changing any configuration.</p>
          <p>In a PR, use <code>@kody review \<directive></code>. In the CLI, use <code>kodus review --focus</code>.</p>
          <p>Examples:</p>

          <ul>
            <li><code>@kody review focus on security</code></li>
            <li><code>@kody review focus on performance</code></li>
            <li><code>kodus review --focus "edge cases"</code></li>
          </ul>

          <p>This is especially useful for larger PRs or sensitive changes, where you want the review to go deeper on a specific area, such as security, performance, edge cases, a business rule, or a team standard.</p>
          <p>Focus works as a priority, not a filter. Kody pays closer attention to the context you provide, but still reports other concrete issues it finds in the diff.</p>
          <p>Learn more in the <a href="https://docs.kodus.io/how_to_use/en/code_review/review_directive">Steer a Review (Focus)</a> documentation.</p>
        </div>

        <div>
          <div>Consolidate LLM prompts into a single comment</div>
          <p>We added an option to generate a single PR comment containing all prompts and suggestions, so an external agent or AI tool can apply the fixes in one pass.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Select all repositories at once</div>
          <p>In the add repositories modal, we added <strong>select all</strong> and <strong>clear selection</strong> buttons. For teams connecting dozens of repositories, this removes the need to select each one manually and significantly reduces setup time.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Cost breakdown by model (BYOK)</div>
          <p>Teams using Bring Your Own Key now have a detailed view of LLM usage by model on the costs screen. Instead of seeing only the total amount, you can identify exactly which providers and models are driving most of the usage and make clearer decisions about what to keep, replace, or limit.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Review agent consolidation</div>
          <p>We reorganized the code review agents to run on a unified infrastructure. Previously, parts of the flow were spread across different places, which could lead to duplicated suggestions and inconsistent behavior. With this consolidation, the pipeline is more predictable, easier to maintain, and less likely to repeat suggestions in the same PR.</p>
        </div>

        <div>
          <div>Content guard for deduplication</div>
          <p>We improved the deduplication algorithm so distinct bugs are not grouped as if they were the same issue. The content guard now better considers the actual content of each suggestion, reducing false-positive deduplication and making sure separate issues continue to be reported individually.</p>
        </div>

        <div>
          <div>Prose findings recovery + Gemini support</div>
          <p>We fixed unstable behavior in prose finding generation and restored strict mode for Gemini. We also updated the Anthropic SDK, keeping compatibility with newer models and improving response stability.</p>
        </div>

        <div>
          <div>RBAC documentation</div>
          <p>We updated the permissions documentation, including the <code>OrganizationSettings</code> scope and the restriction that only the organization Owner can configure BYOK. This makes it clearer who can do what inside the workspace.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Review comments with broken formatting:</strong> fixed cases where Kody comments appeared with unexpected formatting in pull requests.</p>
          </div>

          <div>
            <p><strong>Retry errors with BYOK providers:</strong> added preventive adjustments to avoid retry failures when a BYOK provider returns an empty response body.</p>
          </div>

          <div>
            <p><strong>Sandbox tool errors:</strong> the agent now handles errors better when running tools in the sandbox environment, without breaking the review.</p>
          </div>

          <div>
            <p><strong>Normalized user IDs:</strong> standardized how author, reviewer, and assignee IDs are handled, preventing PRs from breaking because of type differences, such as string vs. number.</p>
          </div>

          <div>
            <p><strong>@kody conversation crashing on JSON wrapped in prose:</strong> fixed a crash that happened when Kody responded to mentions and the output came back as text containing embedded JSON.</p>
          </div>

          <div>
            <p><strong>IDE sync config now respects approval settings:</strong> IDE rule synchronization now respects the approval configuration.</p>
          </div>

          <div>
            <p><strong>Rules with multiple directories:</strong> adjusted Kody Rules validation to correctly handle rules that apply to multiple path groups.</p>
          </div>

          <div>
            <p><strong>Automatic code review config creation:</strong> when a repository did not have a code review configuration, creating a Kody Rule could fail silently. The configuration is now created automatically.</p>
          </div>

          <div>
            <p><strong>Diff re-review in the agent:</strong> improved how the agent detects diffs from new commits during re-reviews.</p>
          </div>

          <div>
            <p><strong>MCP Manager OAuth disconnect:</strong> fixed an issue with disconnecting OAuth credentials in MCP Manager that could cause inconsistent behavior.</p>
          </div>

          <div>
            <p><strong>MCP Manager production build:</strong> the MCP Manager production build now correctly passes the GitHub token.</p>
          </div>

          <div>
            <p><strong>Orphaned users in the license list:</strong> users removed from the GitHub organization now appear correctly in the license list.</p>
          </div>

          <div>
            <p><strong>Skipped review email:</strong> the notification email sent when a review is skipped now includes the author's name/email and no longer breaks when the user does not have a license.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 29, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Validated review engine</div>
          <p>We updated Kody's review pipeline to improve analysis accuracy and reduce cases where important issues could slip through unnoticed.</p>
          <p>The engine now identifies problematic patterns more effectively, better understands changes that span multiple files, and can review code regions with more flexibility when the context is not fully obvious.</p>
          <p>We also optimized processing and reduced the average cost per review by around 30%.</p>
        </div>

        <div>
          <div>Shareable dashboard views</div>
          <p>Filters applied in Cockpit are now saved in the URL, including time range, repositories, severity, and status.</p>
          <p>This means you can copy the link and share it with your team on Slack, for example. Anyone who opens the URL will see Cockpit with the same filters applied, without having to manually recreate the view.</p>
          <p>This makes it easier to share specific analyses, such as what changed over the past week or an increase in security suggestions in a repository.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Unified Kody Rules lifecycle</div>
          <p>We unified the Kody Rules flow into a single lifecycle, regardless of where the rule was created: the library, manual creation, or inheritance from the organization to the repository.</p>
          <p>With this change, activating, editing, disabling, and approving rules now follow the same path inside the product. We also migrated older rules to the new format and centralized the control of rules pending approval.</p>
          <p>This makes the system more consistent, reduces unexpected states, and ensures that an active rule is actually applied in Kody reviews.</p>
        </div>

        <div>
          <div>Migrate away from Composio</div>
          <p>We removed the dependency on Composio as an external MCP broker and moved to our own implementation for GitHub Issues, now integrated with Kodus Issues.</p>
          <p>This reduces an external point of failure, improves call reliability, and gives us more control over authentication, rate limits, and retries.</p>
          <p>As part of the migration, we also removed low-usage integrations that depended on Composio, such as ClickUp and CloudId.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Inheritance toggle</div>
          <p>When you enable or disable rule inheritance from the organization to a repository, the UI now shows the new state immediately, without waiting for the API response.</p>
          <p>If the call fails, for example because of a connection issue, the state is automatically reverted and we show an error toast. Before, users would click, wait, and not get clear feedback about what had happened.</p>
          <p>We also improved the rules cache update. Now we only invalidate the rules affected by that inheritance change, avoiding unnecessary reloads for rules that did not change.</p>
        </div>

        <div>
          <div>Kody Rules Origin</div>
          <p>We added an explicit origin to all Kody Rules: <code>LIBRARY</code>, <code>MANUAL</code>, <code>INHERITED</code>, and <code>SUGGESTED</code>.</p>
          <p>This fixes an issue where some rule creation scenarios could fail silently because the backend expected an origin value that the frontend was not sending.</p>
          <p>Now the contract between frontend and backend is clearer, and the rule origin is validated before reaching the creation flow.</p>
        </div>

        <div>
          <div>Atlassian Rovo</div>
          <p>Rovo is an Atlassian AI agent that generates code and edits files automatically. When it creates commits, it includes specific metadata, such as message prefixes and custom headers.</p>
          <p>Previously, our review engine identified those commits as human-written code and could suggest changes on them.</p>
          <p>Now we detect Rovo commits and skip those changes both in the code review logic and in the MCP business-rule validation preflight.</p>
        </div>

        <div>
          <div>MCP OAuth callback</div>
          <p>We fixed the OAuth flow for connecting MCPs, such as GitHub and Jira.</p>
          <p>Previously, users who had already completed onboarding could be blocked when trying to add a new MCP. Now the callback works at any time, as long as the state parameter is valid.</p>
        </div>

        <div>
          <div>Pending rules section</div>
          <p>Pending rules, which need approval before entering the review pipeline, now have a dedicated section with improved UX.</p>
          <p>The section shows a status badge, who suggested the rule, when it was suggested, and inline actions to approve or reject it.</p>
          <p>Previously, these rules appeared mixed together with active rules, which made it easy to miss that something needed attention.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>GitHub Integration GitHub App post-onboarding:</strong> we fixed an issue where some GitHub integration pages returned a 404 after the user completed onboarding. This affected routes such as <code>/github/integration</code> and <code>/github/organization-name</code> when the GitHub App installation state was not updated correctly. We also adjusted the redirect after installation and added route validations to make the integration flow more reliable across different states.</p>
          </div>

          <div>
            <p><strong>Severity slicer colors:</strong> the severity control for low, medium, high, and critical used inconsistent colors. In some places, red meant critical; in others, it meant high. We standardized it to a semantic scale: gray for low, yellow for medium, orange for high, and red for critical. This affects Cockpit filters, suggestion badges, and notification settings.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 22, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Forgejo support is now on par with GitHub & GitLab</div>
          <p>Review comments, commit statuses, force-push detection, and webhook coverage now work consistently for Forgejo repositories. If you self-host with Forgejo, Kody behaves just like on any other major platform.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Faster PR closing for large repos</div>
          <p>Eliminated duplicate API calls when syncing Kody Rules from changed files. PRs with many files now close noticeably faster.</p>
        </div>

        <div>
          <div>Cleaner settings UI</div>
          <p>Platform settings that don't apply to your current Git provider, such as GitHub-specific options when you're on GitLab, are now hidden automatically. Less clutter, fewer misconfigurations.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Reconnecting a Git provider after disconnecting:</strong> previously, disconnecting a provider left stale integration configs behind, causing reconnects to fail. Now stale rows are properly cleaned up.</p>
          </div>

          <div>
            <p><strong>Kody conversation replies with empty responses:</strong> resolved an issue where Kody occasionally replied with blank content in PR comment threads when using Claude Sonnet.</p>
          </div>

          <div>
            <p><strong>NaN deduplication indices:</strong> added three-layer protection against NaN values appearing in suggestion deduplication indices, preventing rare but confusing duplicate suggestions.</p>
          </div>

          <div>
            <p><strong>Forgejo prompt field always empty:</strong> the formatPromptForLLM function was reading a non-existent field on Forgejo PRs, causing the prompt section to be blank. Now it reads the correct field.</p>
          </div>

          <div>
            <p><strong>Self-hosted AST graph reliability:</strong> the kodus-graph CLI was installed but not available to the runtime user in self-hosted worker images. Fixed PATH and install order so graph indexing works out of the box.</p>
          </div>

          <div>
            <p><strong>Orphaned agent trace records:</strong> prevented a race condition in chunked review mode that could leave orphaned <code>IN\_PROGRESS</code> trace records in the database.</p>
          </div>

          <div>
            <p><strong>Platform settings not scoped to Git tool:</strong> settings incompatible with your current Git provider were still visible. Now they're properly filtered based on the connected tool.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 15, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Operational metrics in Cockpit</div>
          <p>Track the health of your review pipeline in real time. Throughput, queue, and processing time metrics are now available in Cockpit.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Redesigned Kodus Review tab</div>
          <p>The review tab has been redesigned with a cleaner interface and more direct actions. You can now analyze and act on suggestions without leaving the PR screen.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Backend on pnpm</div>
          <p>We migrated the backend from Yarn 1 to pnpm. This makes builds faster, improves lockfile consistency, and reduces cache issues across environments.</p>
        </div>

        <div>
          <div>Token usage screen</div>
          <p>The token usage screen has been redesigned to make consumption by organization and period easier to understand. It is now simpler to track usage and see how tokens are being consumed over time.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Self-hosted analytics:</strong> we fixed the analytics integration for self-hosted deployments. Usage metrics now appear correctly in the dashboard.</p>
          </div>

          <div>
            <p><strong>Issue cache:</strong> the issue count in the sidebar could sometimes become outdated. The cache is now invalidated correctly after changes.</p>
          </div>

          <div>
            <p><strong>GitHub rate limit:</strong> we fixed a rate limit issue in cloud E2E tests. We now use round-robin across multiple bot accounts to better distribute requests.</p>
          </div>

          <div>
            <p><strong>Notification routing:</strong> we fixed the behavior of targeted notifications when combined with audience settings. Notifications now reach the right people without duplicates.</p>
          </div>

          <div>
            <p><strong>Centralized config sync:</strong> we fixed issues in the centralized sync of Kody Rules configurations across repositories. Sync now correctly handles multiple scopes, stale configurations, and merge-triggered updates.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 8, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Moonshot Kimi support for BYOK</div>
          <p>We added support for Moonshot as a provider, compatible with the Anthropic API.</p>
          <p>You can now use the Kimi Coding Plan model in BYOK setups. To configure it, set the <code>API\_MOONSHOT\_API\_KEY</code> key and select the model in the organization preferences.</p>
          <p>See the <a href="https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus">Moonshot (Kimi)</a> documentation for more setup details.</p>
        </div>

        <div>
          <div>Monthly token usage control</div>
          <p>Organizations can now set monthly token consumption limits per model.</p>
          <p>Usage is shown in real time in the interface, with a progress bar. When usage reaches 80% of the limit, the team receives an email alert. If the limit is reached, additional reviews can be blocked automatically.</p>

          <video>
            <source type="video/mp4" />
          </video>

          <p>See the <a href="https://docs.kodus.io/how_to_use/en/spend-limit">Monthly Spend Limit</a> documentation for more setup details.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>More resilient review agent</div>
          <p>The review engine now handles empty or malformed LLM responses better.</p>
          <p>This reduces loops in edge cases and helps ensure valid suggestions continue to be delivered even when the provider returns an unexpected response.</p>
        </div>

        <div>
          <div>Telemetry for self-hosted environments</div>
          <p>On-premise installations now automatically report health metrics, such as heartbeat, and usage data.</p>
          <p>The goal is to make diagnosis and support easier without exposing sensitive customer data.</p>
        </div>

        <div>
          <div>Faster Kody Rules</div>
          <p>We improved the loading and synchronization of custom rules.</p>
          <p>We also fixed the count of orphaned rules and made partial updates safer against race conditions.</p>
        </div>

        <div>
          <div>GitLab compatibility improvements</div>

          <ul>
            <li>Support for GitLab 13.x in comment webhooks</li>
            <li>Diff fallback for versions earlier than 15.7</li>
            <li>Fixes for discussion threads and replies scoped by discussionId</li>
            <li>Self-hosted development environment documentation</li>
          </ul>
        </div>
      </div>

      <div>
        <div>Fixes</div>

        <div>
          <div>
            <p><strong>GitHub:</strong> suspended users no longer appear in the member list for license assignment.</p>
          </div>

          <div>
            <p><strong>Update Connection:</strong> integration reauthentication now correctly clears the previous configuration.</p>
          </div>

          <div>
            <p><strong>Integration reset:</strong> Kody Rules linked to the repo/directory are now removed automatically.</p>
          </div>

          <div>
            <p><strong>Release Freeze:</strong> eligibility notifications only appear when the freeze is active.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>
</div>

<div>
  <Update label="July 13, 2026 - New Token Usage Experience">
    The Token Usage page has been redesigned to provide a more complete view of consumption.

    It is now easier to track costs by area, model, and review activity, as well as filter the data and drill down into more specific analyses. This helps teams better understand where tokens are being used and how they can optimize costs.

    Video: [https://kodus.io/wp-content/uploads/2026/07/new-experience-token-usage.mp4](https://kodus.io/wp-content/uploads/2026/07/new-experience-token-usage.mp4)
  </Update>

  <Update label="July 13, 2026 - Automatic Detector Backfill for Existing Rules">
    Organizations that created Kody Rules before this release can also benefit from the new architecture. We created an automated process that analyzes existing rules and, whenever possible, generates mechanical detectors for them.

    The process is incremental, safe, and does not interfere with the normal execution of rules. When a rule cannot be converted into a detector, it continues to work through the traditional semantic review flow.
  </Update>

  <Update label="July 13, 2026 - More Accurate and Predictable Kody Rules">
    We restructured how Kody applies custom rules during code reviews. Instead of relying solely on a more open-ended agent analysis, rules are now evaluated deterministically by file and PR scope.

    In practice, this improves rule coverage in large PRs, reduces cases where an applicable rule is overlooked, and makes Kody Rules behave more consistently across different models.

    We also introduced mechanical detectors for certain rules. When a rule can safely be converted into an objective check, Kody can apply it without making an LLM call, reducing costs and improving predictability.
  </Update>

  <Update label="July 13, 2026 - Code Review Engine Improvements">
    This release includes a major upgrade to the review agent runtime. We migrated important parts of the execution flow to a new agent harness foundation, making the system more modular, observable, and ready for future improvements.

    We also improved the engine used to search for evidence in the codebase, with a focus on finding more relevant cross-file references and increasing the quality of generated suggestions.
  </Update>

  <Update label="July 13, 2026 - Cleaner Review Comments">
    We adjusted the format of Kody's review comments to prevent internal reasoning structures from appearing in the output and to make suggestions more natural, concise, and easier to understand.

    We also fixed issues involving aliases and internal prompt references following recent refactors.
  </Update>

  <Update label="July 13, 2026 - Improved BYOK Support">
    We improved BYOK support across different parts of the product, including configuration, model fallback, and per-model cost calculations.

    We also introduced a clearer experience for viewing BYOK settings and understanding how each model affects token consumption.
  </Update>

  <Update label="July 13, 2026 - More Accurate Cost Tracking and Telemetry">
    We improved the observability of LLM calls to ensure token usage is attributed correctly, especially within the new Kody Rules and agent workflows.

    This increases the accuracy of usage reports and prevents undercounting in more complex review scenarios.
  </Update>

  <Update label="July 13, 2026 - MCP Manager and Plugin Improvements">
    We improved tenant isolation for MCP connections, enhanced connection sorting and testing, and removed legacy integrations that had already been deprecated.

    These changes increase the reliability of the plugins and integrations experience.
  </Update>

  <Update label="July 13, 2026 - Improvements for Self-Hosted Environments">
    We applied fixes to Dockerfiles, provisioning scripts, and local configuration to make self-hosted environments more stable.

    We also fixed an issue involving pnpm on macOS and adjusted the API hostname configuration used during provisioning.
  </Update>

  <Update label="July 13, 2026 - More Stable Observability">
    We fixed excessive memory consumption in the Mongo observability exporter and improved logging behavior across different environments.

    We also removed outdated references to the previous internal framework, simplifying the observability codebase.
  </Update>

  <Update label="July 13, 2026 - New Quality Tests and Validations">
    We added new end-to-end scenarios and evaluations to validate Kody Rules, model recall, suggestion adherence, and prompt regressions.

    These validations help ensure that changes to models, prompts, or the underlying architecture do not reduce review quality.
  </Update>

  <Update label="July 13, 2026 - Updated Documentation">
    We updated the documentation for BYOK, custom messages, and focused reviews. We also revised the README and added new pages explaining how to guide Kody during a review.
  </Update>

  <Update label="July 13, 2026 - Safer Rule Execution">
    We added protections against potentially unsafe regex patterns in Kody Rules detectors. This prevents malformed or computationally expensive rules from affecting review performance. We also fixed cases where outdated detectors could remain associated with a rule after an edit changed the rule's intended behavior.
  </Update>

  <Update label="July 13, 2026 - License and Billing Improvements">
    We fixed issues involving trial creation, the listing of inactive users or users removed from the Git organization, and active seat counts. These changes make the license page more consistent and reduce discrepancies between the organization's actual users and the users displayed in billing.
  </Update>

  <Update label="July 6, 2026 - Steer a review with focus">
    You can now ask Kody to pay special attention to something specific during a review, without changing any configuration.

    In a PR, use @kody review \<directive>. In the CLI, use kodus review --focus.

    Examples: @kody review focus on security. @kody review focus on performance. Or in the CLI: kodus review --focus "edge cases".

    This is especially useful for larger PRs or sensitive changes, where you want the review to go deeper on a specific area, such as security, performance, edge cases, a business rule, or a team standard.

    Focus works as a priority, not a filter. Kody pays closer attention to the context you provide, but still reports other concrete issues it finds in the diff.

    Learn more in the Steer a Review Focus documentation: [https://docs.kodus.io/how\_to\_use/en/code\_review/review\_directive](https://docs.kodus.io/how_to_use/en/code_review/review_directive)
  </Update>

  <Update label="July 6, 2026 - Consolidate LLM prompts into a single comment">
    We added an option to generate a single PR comment containing all prompts and suggestions, so an external agent or AI tool can apply the fixes in one pass.

    Video: [https://kodus.io/wp-content/uploads/2026/07/agent-prompt.mp4](https://kodus.io/wp-content/uploads/2026/07/agent-prompt.mp4)
  </Update>

  <Update label="July 6, 2026 - Select all repositories at once">
    In the add repositories modal, we added select all and clear selection buttons. For teams connecting dozens of repositories, this removes the need to select each one manually and significantly reduces setup time.

    Video: [https://kodus.io/wp-content/uploads/2026/07/add-repo-qa.mp4](https://kodus.io/wp-content/uploads/2026/07/add-repo-qa.mp4)
  </Update>

  <Update label="July 6, 2026 - Cost breakdown by model (BYOK)">
    Teams using Bring Your Own Key now have a detailed view of LLM usage by model on the costs screen. Instead of seeing only the total amount, you can identify exactly which providers and models are driving most of the usage and make clearer decisions about what to keep, replace, or limit.

    Video: [https://kodus.io/wp-content/uploads/2026/07/resumo-de-custos-por-modelo.mp4](https://kodus.io/wp-content/uploads/2026/07/resumo-de-custos-por-modelo.mp4)
  </Update>

  <Update label="July 6, 2026 - Review agent consolidation">
    We reorganized the code review agents to run on a unified infrastructure. Previously, parts of the flow were spread across different places, which could lead to duplicated suggestions and inconsistent behavior. With this consolidation, the pipeline is more predictable, easier to maintain, and less likely to repeat suggestions in the same PR.
  </Update>

  <Update label="July 6, 2026 - Content guard for deduplication">
    We improved the deduplication algorithm so distinct bugs are not grouped as if they were the same issue. The content guard now better considers the actual content of each suggestion, reducing false-positive deduplication and making sure separate issues continue to be reported individually.
  </Update>

  <Update label="July 6, 2026 - Prose findings recovery + Gemini support">
    We fixed unstable behavior in prose finding generation and restored strict mode for Gemini. We also updated the Anthropic SDK, keeping compatibility with newer models and improving response stability.
  </Update>

  <Update label="July 6, 2026 - RBAC documentation">
    We updated the permissions documentation, including the OrganizationSettings scope and the restriction that only the organization Owner can configure BYOK. This makes it clearer who can do what inside the workspace.
  </Update>

  <Update label="July 6, 2026 - Review comments with broken formatting">
    Fixed cases where Kody comments appeared with unexpected formatting in pull requests.
  </Update>

  <Update label="July 6, 2026 - Retry errors with BYOK providers">
    Added preventive adjustments to avoid retry failures when a BYOK provider returns an empty response body.
  </Update>

  <Update label="July 6, 2026 - Sandbox tool errors">
    The agent now handles errors better when running tools in the sandbox environment, without breaking the review.
  </Update>

  <Update label="July 6, 2026 - Normalized user IDs">
    Standardized how author, reviewer, and assignee IDs are handled, preventing PRs from breaking because of type differences, such as string vs. number.
  </Update>

  <Update label="July 6, 2026 - @kody conversation crashing on JSON wrapped in prose">
    Fixed a crash that happened when Kody responded to mentions and the output came back as text containing embedded JSON.
  </Update>

  <Update label="July 6, 2026 - IDE sync config now respects approval settings">
    IDE rule synchronization now respects the approval configuration.
  </Update>

  <Update label="July 6, 2026 - Rules with multiple directories">
    Adjusted Kody Rules validation to correctly handle rules that apply to multiple path groups.
  </Update>

  <Update label="July 6, 2026 - Automatic code review config creation">
    When a repository did not have a code review configuration, creating a Kody Rule could fail silently. The configuration is now created automatically.
  </Update>

  <Update label="July 6, 2026 - Diff re-review in the agent">
    Improved how the agent detects diffs from new commits during re-reviews.
  </Update>

  <Update label="July 6, 2026 - MCP Manager OAuth disconnect">
    Fixed an issue with disconnecting OAuth credentials in MCP Manager that could cause inconsistent behavior.
  </Update>

  <Update label="July 6, 2026 - MCP Manager production build">
    The MCP Manager production build now correctly passes the GitHub token.
  </Update>

  <Update label="July 6, 2026 - Orphaned users in the license list">
    Users removed from the GitHub organization now appear correctly in the license list.
  </Update>

  <Update label="July 6, 2026 - Skipped review email">
    The notification email sent when a review is skipped now includes the author's name/email and no longer breaks when the user does not have a license.
  </Update>

  <Update label="June 29, 2026 - Validated review engine">
    We updated Kody's review pipeline to improve analysis accuracy and reduce cases where important issues could slip through unnoticed.

    The engine now identifies problematic patterns more effectively, better understands changes that span multiple files, and can review code regions with more flexibility when the context is not fully obvious.

    We also optimized processing and reduced the average cost per review by around 30%.
  </Update>

  <Update label="June 29, 2026 - Shareable dashboard views">
    Filters applied in Cockpit are now saved in the URL, including time range, repositories, severity, and status.

    This means you can copy the link and share it with your team on Slack, for example. Anyone who opens the URL will see Cockpit with the same filters applied, without having to manually recreate the view.

    This makes it easier to share specific analyses, such as what changed over the past week or an increase in security suggestions in a repository.

    Video: [https://kodus.io/wp-content/uploads/2026/06/kodus-copy-url.mp4](https://kodus.io/wp-content/uploads/2026/06/kodus-copy-url.mp4)
  </Update>

  <Update label="June 29, 2026 - Unified Kody Rules lifecycle">
    We unified the Kody Rules flow into a single lifecycle, regardless of where the rule was created: the library, manual creation, or inheritance from the organization to the repository.

    With this change, activating, editing, disabling, and approving rules now follow the same path inside the product. We also migrated older rules to the new format and centralized the control of rules pending approval.

    This makes the system more consistent, reduces unexpected states, and ensures that an active rule is actually applied in Kody reviews.
  </Update>

  <Update label="June 29, 2026 - Migrate away from Composio">
    We removed the dependency on Composio as an external MCP broker and moved to our own implementation for GitHub Issues, now integrated with Kodus Issues.

    This reduces an external point of failure, improves call reliability, and gives us more control over authentication, rate limits, and retries.

    As part of the migration, we also removed low-usage integrations that depended on Composio, such as ClickUp and CloudId.
  </Update>

  <Update label="June 29, 2026 - Inheritance toggle">
    When you enable or disable rule inheritance from the organization to a repository, the UI now shows the new state immediately, without waiting for the API response.

    If the call fails, for example because of a connection issue, the state is automatically reverted and we show an error toast. Before, users would click, wait, and not get clear feedback about what had happened.

    We also improved the rules cache update. Now we only invalidate the rules affected by that inheritance change, avoiding unnecessary reloads for rules that did not change.
  </Update>

  <Update label="June 29, 2026 - Kody Rules Origin">
    We added an explicit origin to all Kody Rules: LIBRARY, MANUAL, INHERITED, and SUGGESTED.

    This fixes an issue where some rule creation scenarios could fail silently because the backend expected an origin value that the frontend was not sending.

    Now the contract between frontend and backend is clearer, and the rule origin is validated before reaching the creation flow.
  </Update>

  <Update label="June 29, 2026 - Atlassian Rovo">
    Rovo is an Atlassian AI agent that generates code and edits files automatically. When it creates commits, it includes specific metadata, such as message prefixes and custom headers.

    Previously, our review engine identified those commits as human-written code and could suggest changes on them.

    Now we detect Rovo commits and skip those changes both in the code review logic and in the MCP business-rule validation preflight.
  </Update>

  <Update label="June 29, 2026 - MCP OAuth callback">
    We fixed the OAuth flow for connecting MCPs, such as GitHub and Jira.

    Previously, users who had already completed onboarding could be blocked when trying to add a new MCP. Now the callback works at any time, as long as the state parameter is valid.
  </Update>

  <Update label="June 29, 2026 - Pending rules section">
    Pending rules, which need approval before entering the review pipeline, now have a dedicated section with improved UX.

    The section shows a status badge, who suggested the rule, when it was suggested, and inline actions to approve or reject it.

    Previously, these rules appeared mixed together with active rules, which made it easy to miss that something needed attention.
  </Update>

  <Update label="June 29, 2026 - GitHub Integration GitHub App post-onboarding">
    We fixed an issue where some GitHub integration pages returned a 404 after the user completed onboarding. This affected routes such as /github/integration and /github/organization-name when the GitHub App installation state was not updated correctly. We also adjusted the redirect after installation and added route validations to make the integration flow more reliable across different states.
  </Update>

  <Update label="June 29, 2026 - Severity slicer colors">
    The severity control for low, medium, high, and critical used inconsistent colors. In some places, red meant critical; in others, it meant high. We standardized it to a semantic scale: gray for low, yellow for medium, orange for high, and red for critical. This affects Cockpit filters, suggestion badges, and notification settings.
  </Update>

  <Update label="June 22, 2026 - Forgejo support is now on par with GitHub & GitLab">
    Review comments, commit statuses, force-push detection, and webhook coverage now work consistently for Forgejo repositories. If you self-host with Forgejo, Kody behaves just like on any other major platform.
  </Update>

  <Update label="June 22, 2026 - Faster PR closing for large repos">
    Eliminated duplicate API calls when syncing Kody Rules from changed files. PRs with many files now close noticeably faster.
  </Update>

  <Update label="June 22, 2026 - Cleaner settings UI">
    Platform settings that don't apply to your current Git provider, such as GitHub-specific options when you're on GitLab, are now hidden automatically. Less clutter, fewer misconfigurations.
  </Update>

  <Update label="June 22, 2026 - Reconnecting a Git provider after disconnecting">
    Previously, disconnecting a provider left stale integration configs behind, causing reconnects to fail. Now stale rows are properly cleaned up.
  </Update>

  <Update label="June 22, 2026 - Kody conversation replies with empty responses">
    Resolved an issue where Kody occasionally replied with blank content in PR comment threads when using Claude Sonnet.
  </Update>

  <Update label="June 22, 2026 - NaN deduplication indices">
    Added three-layer protection against NaN values appearing in suggestion deduplication indices, preventing rare but confusing duplicate suggestions.
  </Update>

  <Update label="June 22, 2026 - Forgejo prompt field always empty">
    The formatPromptForLLM function was reading a non-existent field on Forgejo PRs, causing the prompt section to be blank. Now it reads the correct field.
  </Update>

  <Update label="June 22, 2026 - Self-hosted AST graph reliability">
    The kodus-graph CLI was installed but not available to the runtime user in self-hosted worker images. Fixed PATH and install order so graph indexing works out of the box.
  </Update>

  <Update label="June 22, 2026 - Orphaned agent trace records">
    Prevented a race condition in chunked review mode that could leave orphaned IN\_PROGRESS trace records in the database.
  </Update>

  <Update label="June 22, 2026 - Platform settings not scoped to Git tool">
    Settings incompatible with your current Git provider were still visible. Now they're properly filtered based on the connected tool.
  </Update>

  <Update label="June 15, 2026 - Operational metrics in Cockpit">
    Track the health of your review pipeline in real time. Throughput, queue, and processing time metrics are now available in Cockpit.

    Video: [https://kodus.io/wp-content/uploads/2026/06/cockpit.mp4](https://kodus.io/wp-content/uploads/2026/06/cockpit.mp4)
  </Update>

  <Update label="June 15, 2026 - Redesigned Kodus Review tab">
    The review tab has been redesigned with a cleaner interface and more direct actions. You can now analyze and act on suggestions without leaving the PR screen.

    Video: [https://kodus.io/wp-content/uploads/2026/06/kody-review-tab.mp4](https://kodus.io/wp-content/uploads/2026/06/kody-review-tab.mp4)
  </Update>

  <Update label="June 15, 2026 - Backend on pnpm">
    We migrated the backend from Yarn 1 to pnpm. This makes builds faster, improves lockfile consistency, and reduces cache issues across environments.
  </Update>

  <Update label="June 15, 2026 - Token usage screen">
    The token usage screen has been redesigned to make consumption by organization and period easier to understand. It is now simpler to track usage and see how tokens are being consumed over time.

    Video: [https://kodus.io/wp-content/uploads/2026/06/token\_usage.mp4](https://kodus.io/wp-content/uploads/2026/06/token_usage.mp4)
  </Update>

  <Update label="June 15, 2026 - Self-hosted analytics">
    We fixed the analytics integration for self-hosted deployments. Usage metrics now appear correctly in the dashboard.
  </Update>

  <Update label="June 15, 2026 - Issue cache">
    The issue count in the sidebar could sometimes become outdated. The cache is now invalidated correctly after changes.
  </Update>

  <Update label="June 15, 2026 - GitHub rate limit">
    We fixed a rate limit issue in cloud E2E tests. We now use round-robin across multiple bot accounts to better distribute requests.
  </Update>

  <Update label="June 15, 2026 - Notification routing">
    We fixed the behavior of targeted notifications when combined with audience settings. Notifications now reach the right people without duplicates.
  </Update>

  <Update label="June 15, 2026 - Centralized config sync">
    We fixed issues in the centralized sync of Kody Rules configurations across repositories. Sync now correctly handles multiple scopes, stale configurations, and merge-triggered updates.
  </Update>

  <Update label="June 8, 2026 - Moonshot Kimi support for BYOK">
    We added support for Moonshot as a provider, compatible with the Anthropic API.

    You can now use the Kimi Coding Plan model in BYOK setups. To configure it, set the API\_MOONSHOT\_API\_KEY key and select the model in the organization preferences.

    See the Moonshot Kimi documentation for more setup details: [https://docs.kodus.io/knowledge\_base/en/how-to-use-moonshot-with-kodus](https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus)
  </Update>

  <Update label="June 8, 2026 - Monthly token usage control">
    Organizations can now set monthly token consumption limits per model.

    Usage is shown in real time in the interface, with a progress bar. When usage reaches 80% of the limit, the team receives an email alert. If the limit is reached, additional reviews can be blocked automatically.

    Video: [https://kodus.io/wp-content/uploads/2026/06/token-usage.mov](https://kodus.io/wp-content/uploads/2026/06/token-usage.mov)

    See the Monthly Spend Limit documentation for more setup details: [https://docs.kodus.io/how\_to\_use/en/spend-limit](https://docs.kodus.io/how_to_use/en/spend-limit)
  </Update>

  <Update label="June 8, 2026 - More resilient review agent">
    The review engine now handles empty or malformed LLM responses better. This reduces loops in edge cases and helps ensure valid suggestions continue to be delivered even when the provider returns an unexpected response.
  </Update>

  <Update label="June 8, 2026 - Telemetry for self-hosted environments">
    On-premise installations now automatically report health metrics, such as heartbeat, and usage data. The goal is to make diagnosis and support easier without exposing sensitive customer data.
  </Update>

  <Update label="June 8, 2026 - Faster Kody Rules">
    We improved the loading and synchronization of custom rules. We also fixed the count of orphaned rules and made partial updates safer against race conditions.
  </Update>

  <Update label="June 8, 2026 - GitLab compatibility improvements">
    Support for GitLab 13.x in comment webhooks.

    Diff fallback for versions earlier than 15.7.

    Fixes for discussion threads and replies scoped by discussionId.

    Self-hosted development environment documentation.
  </Update>

  <Update label="June 8, 2026 - GitHub member list fix">
    Suspended users no longer appear in the member list for license assignment.
  </Update>

  <Update label="June 8, 2026 - Update Connection fix">
    Integration reauthentication now correctly clears the previous configuration.
  </Update>

  <Update label="June 8, 2026 - Integration reset fix">
    Kody Rules linked to the repo or directory are now removed automatically.
  </Update>

  <Update label="June 8, 2026 - Release Freeze fix">
    Eligibility notifications only appear when the freeze is active.
  </Update>
</div>


# Changelog
Source: https://docs.kodus.io/changelog/index

Latest Kodus updates and improvements.

<div>
  <div>
    <div aria-label="Changelog filters">
      <p>Filters</p>

      <div>
        <label>
          <input type="checkbox" />

          <span>Security</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Cockpit</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>BYOK</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>AI Engine</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Self-hosted</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>GIT Provider</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Performance</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>UX & Interface</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Notifications</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Kody Rules</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>MCP</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Billing & Licenses</span>
        </label>
      </div>
    </div>
  </div>

  <div>
    <div>
      <span>July 13, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>New Token Usage Experience</div>
          <p>The Token Usage page has been redesigned to provide a more complete view of consumption.</p>
          <p>It is now easier to track costs by area, model, and review activity, as well as filter the data and drill down into more specific analyses. This helps teams better understand where tokens are being used and how they can optimize costs.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Automatic Detector Backfill for Existing Rules</div>
          <p>Organizations that created Kody Rules before this release can also benefit from the new architecture. We created an automated process that analyzes existing rules and, whenever possible, generates mechanical detectors for them.</p>
          <p>The process is incremental, safe, and does not interfere with the normal execution of rules. When a rule cannot be converted into a detector, it continues to work through the traditional semantic review flow.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>More Accurate and Predictable Kody Rules</div>
          <p>We restructured how Kody applies custom rules during code reviews. Instead of relying solely on a more open-ended agent analysis, rules are now evaluated deterministically by file and PR scope.</p>
          <p>In practice, this improves rule coverage in large PRs, reduces cases where an applicable rule is overlooked, and makes Kody Rules behave more consistently across different models.</p>
          <p>We also introduced mechanical detectors for certain rules. When a rule can safely be converted into an objective check, Kody can apply it without making an LLM call, reducing costs and improving predictability.</p>
        </div>

        <div>
          <div>Code Review Engine Improvements</div>
          <p>This release includes a major upgrade to the review agent runtime. We migrated important parts of the execution flow to a new agent harness foundation, making the system more modular, observable, and ready for future improvements.</p>
          <p>We also improved the engine used to search for evidence in the codebase, with a focus on finding more relevant cross-file references and increasing the quality of generated suggestions.</p>
        </div>

        <div>
          <div>Cleaner Review Comments</div>
          <p>We adjusted the format of Kody's review comments to prevent internal reasoning structures from appearing in the output and to make suggestions more natural, concise, and easier to understand.</p>
          <p>We also fixed issues involving aliases and internal prompt references following recent refactors.</p>
        </div>

        <div>
          <div>Improved BYOK Support</div>
          <p>We improved BYOK support across different parts of the product, including configuration, model fallback, and per-model cost calculations.</p>
          <p>We also introduced a clearer experience for viewing BYOK settings and understanding how each model affects token consumption.</p>
        </div>

        <div>
          <div>More Accurate Cost Tracking and Telemetry</div>
          <p>We improved the observability of LLM calls to ensure token usage is attributed correctly, especially within the new Kody Rules and agent workflows.</p>
          <p>This increases the accuracy of usage reports and prevents undercounting in more complex review scenarios.</p>
        </div>

        <div>
          <div>MCP Manager and Plugin Improvements</div>
          <p>We improved tenant isolation for MCP connections, enhanced connection sorting and testing, and removed legacy integrations that had already been deprecated.</p>
          <p>These changes increase the reliability of the plugins and integrations experience.</p>
        </div>

        <div>
          <div>Improvements for Self-Hosted Environments</div>
          <p>We applied fixes to Dockerfiles, provisioning scripts, and local configuration to make self-hosted environments more stable.</p>
          <p>We also fixed an issue involving pnpm on macOS and adjusted the API hostname configuration used during provisioning.</p>
        </div>

        <div>
          <div>More Stable Observability</div>
          <p>We fixed excessive memory consumption in the Mongo observability exporter and improved logging behavior across different environments.</p>
          <p>We also removed outdated references to the previous internal framework, simplifying the observability codebase.</p>
        </div>

        <div>
          <div>New Quality Tests and Validations</div>
          <p>We added new end-to-end scenarios and evaluations to validate Kody Rules, model recall, suggestion adherence, and prompt regressions.</p>
          <p>These validations help ensure that changes to models, prompts, or the underlying architecture do not reduce review quality.</p>
        </div>

        <div>
          <div>Updated Documentation</div>
          <p>We updated the documentation for BYOK, custom messages, and focused reviews. We also revised the README and added new pages explaining how to guide Kody during a review.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Safer Rule Execution:</strong> we added protections against potentially unsafe regex patterns in Kody Rules detectors. This prevents malformed or computationally expensive rules from affecting review performance. We also fixed cases where outdated detectors could remain associated with a rule after an edit changed the rule's intended behavior.</p>
          </div>

          <div>
            <p><strong>License and Billing Improvements:</strong> we fixed issues involving trial creation, the listing of inactive users or users removed from the Git organization, and active seat counts. These changes make the license page more consistent and reduce discrepancies between the organization's actual users and the users displayed in billing.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>July 6, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Steer a review with focus</div>
          <p>You can now ask Kody to pay special attention to something specific during a review, without changing any configuration.</p>
          <p>In a PR, use <code>@kody review \<directive></code>. In the CLI, use <code>kodus review --focus</code>.</p>
          <p>Examples:</p>

          <ul>
            <li><code>@kody review focus on security</code></li>
            <li><code>@kody review focus on performance</code></li>
            <li><code>kodus review --focus "edge cases"</code></li>
          </ul>

          <p>This is especially useful for larger PRs or sensitive changes, where you want the review to go deeper on a specific area, such as security, performance, edge cases, a business rule, or a team standard.</p>
          <p>Focus works as a priority, not a filter. Kody pays closer attention to the context you provide, but still reports other concrete issues it finds in the diff.</p>
          <p>Learn more in the <a href="https://docs.kodus.io/how_to_use/en/code_review/review_directive">Steer a Review (Focus)</a> documentation.</p>
        </div>

        <div>
          <div>Consolidate LLM prompts into a single comment</div>
          <p>We added an option to generate a single PR comment containing all prompts and suggestions, so an external agent or AI tool can apply the fixes in one pass.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Select all repositories at once</div>
          <p>In the add repositories modal, we added <strong>select all</strong> and <strong>clear selection</strong> buttons. For teams connecting dozens of repositories, this removes the need to select each one manually and significantly reduces setup time.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Cost breakdown by model (BYOK)</div>
          <p>Teams using Bring Your Own Key now have a detailed view of LLM usage by model on the costs screen. Instead of seeing only the total amount, you can identify exactly which providers and models are driving most of the usage and make clearer decisions about what to keep, replace, or limit.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Review agent consolidation</div>
          <p>We reorganized the code review agents to run on a unified infrastructure. Previously, parts of the flow were spread across different places, which could lead to duplicated suggestions and inconsistent behavior. With this consolidation, the pipeline is more predictable, easier to maintain, and less likely to repeat suggestions in the same PR.</p>
        </div>

        <div>
          <div>Content guard for deduplication</div>
          <p>We improved the deduplication algorithm so distinct bugs are not grouped as if they were the same issue. The content guard now better considers the actual content of each suggestion, reducing false-positive deduplication and making sure separate issues continue to be reported individually.</p>
        </div>

        <div>
          <div>Prose findings recovery + Gemini support</div>
          <p>We fixed unstable behavior in prose finding generation and restored strict mode for Gemini. We also updated the Anthropic SDK, keeping compatibility with newer models and improving response stability.</p>
        </div>

        <div>
          <div>RBAC documentation</div>
          <p>We updated the permissions documentation, including the <code>OrganizationSettings</code> scope and the restriction that only the organization Owner can configure BYOK. This makes it clearer who can do what inside the workspace.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Review comments with broken formatting:</strong> fixed cases where Kody comments appeared with unexpected formatting in pull requests.</p>
          </div>

          <div>
            <p><strong>Retry errors with BYOK providers:</strong> added preventive adjustments to avoid retry failures when a BYOK provider returns an empty response body.</p>
          </div>

          <div>
            <p><strong>Sandbox tool errors:</strong> the agent now handles errors better when running tools in the sandbox environment, without breaking the review.</p>
          </div>

          <div>
            <p><strong>Normalized user IDs:</strong> standardized how author, reviewer, and assignee IDs are handled, preventing PRs from breaking because of type differences, such as string vs. number.</p>
          </div>

          <div>
            <p><strong>@kody conversation crashing on JSON wrapped in prose:</strong> fixed a crash that happened when Kody responded to mentions and the output came back as text containing embedded JSON.</p>
          </div>

          <div>
            <p><strong>IDE sync config now respects approval settings:</strong> IDE rule synchronization now respects the approval configuration.</p>
          </div>

          <div>
            <p><strong>Rules with multiple directories:</strong> adjusted Kody Rules validation to correctly handle rules that apply to multiple path groups.</p>
          </div>

          <div>
            <p><strong>Automatic code review config creation:</strong> when a repository did not have a code review configuration, creating a Kody Rule could fail silently. The configuration is now created automatically.</p>
          </div>

          <div>
            <p><strong>Diff re-review in the agent:</strong> improved how the agent detects diffs from new commits during re-reviews.</p>
          </div>

          <div>
            <p><strong>MCP Manager OAuth disconnect:</strong> fixed an issue with disconnecting OAuth credentials in MCP Manager that could cause inconsistent behavior.</p>
          </div>

          <div>
            <p><strong>MCP Manager production build:</strong> the MCP Manager production build now correctly passes the GitHub token.</p>
          </div>

          <div>
            <p><strong>Orphaned users in the license list:</strong> users removed from the GitHub organization now appear correctly in the license list.</p>
          </div>

          <div>
            <p><strong>Skipped review email:</strong> the notification email sent when a review is skipped now includes the author's name/email and no longer breaks when the user does not have a license.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 29, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Validated review engine</div>
          <p>We updated Kody's review pipeline to improve analysis accuracy and reduce cases where important issues could slip through unnoticed.</p>
          <p>The engine now identifies problematic patterns more effectively, better understands changes that span multiple files, and can review code regions with more flexibility when the context is not fully obvious.</p>
          <p>We also optimized processing and reduced the average cost per review by around 30%.</p>
        </div>

        <div>
          <div>Shareable dashboard views</div>
          <p>Filters applied in Cockpit are now saved in the URL, including time range, repositories, severity, and status.</p>
          <p>This means you can copy the link and share it with your team on Slack, for example. Anyone who opens the URL will see Cockpit with the same filters applied, without having to manually recreate the view.</p>
          <p>This makes it easier to share specific analyses, such as what changed over the past week or an increase in security suggestions in a repository.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Unified Kody Rules lifecycle</div>
          <p>We unified the Kody Rules flow into a single lifecycle, regardless of where the rule was created: the library, manual creation, or inheritance from the organization to the repository.</p>
          <p>With this change, activating, editing, disabling, and approving rules now follow the same path inside the product. We also migrated older rules to the new format and centralized the control of rules pending approval.</p>
          <p>This makes the system more consistent, reduces unexpected states, and ensures that an active rule is actually applied in Kody reviews.</p>
        </div>

        <div>
          <div>Migrate away from Composio</div>
          <p>We removed the dependency on Composio as an external MCP broker and moved to our own implementation for GitHub Issues, now integrated with Kodus Issues.</p>
          <p>This reduces an external point of failure, improves call reliability, and gives us more control over authentication, rate limits, and retries.</p>
          <p>As part of the migration, we also removed low-usage integrations that depended on Composio, such as ClickUp and CloudId.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Inheritance toggle</div>
          <p>When you enable or disable rule inheritance from the organization to a repository, the UI now shows the new state immediately, without waiting for the API response.</p>
          <p>If the call fails, for example because of a connection issue, the state is automatically reverted and we show an error toast. Before, users would click, wait, and not get clear feedback about what had happened.</p>
          <p>We also improved the rules cache update. Now we only invalidate the rules affected by that inheritance change, avoiding unnecessary reloads for rules that did not change.</p>
        </div>

        <div>
          <div>Kody Rules Origin</div>
          <p>We added an explicit origin to all Kody Rules: <code>LIBRARY</code>, <code>MANUAL</code>, <code>INHERITED</code>, and <code>SUGGESTED</code>.</p>
          <p>This fixes an issue where some rule creation scenarios could fail silently because the backend expected an origin value that the frontend was not sending.</p>
          <p>Now the contract between frontend and backend is clearer, and the rule origin is validated before reaching the creation flow.</p>
        </div>

        <div>
          <div>Atlassian Rovo</div>
          <p>Rovo is an Atlassian AI agent that generates code and edits files automatically. When it creates commits, it includes specific metadata, such as message prefixes and custom headers.</p>
          <p>Previously, our review engine identified those commits as human-written code and could suggest changes on them.</p>
          <p>Now we detect Rovo commits and skip those changes both in the code review logic and in the MCP business-rule validation preflight.</p>
        </div>

        <div>
          <div>MCP OAuth callback</div>
          <p>We fixed the OAuth flow for connecting MCPs, such as GitHub and Jira.</p>
          <p>Previously, users who had already completed onboarding could be blocked when trying to add a new MCP. Now the callback works at any time, as long as the state parameter is valid.</p>
        </div>

        <div>
          <div>Pending rules section</div>
          <p>Pending rules, which need approval before entering the review pipeline, now have a dedicated section with improved UX.</p>
          <p>The section shows a status badge, who suggested the rule, when it was suggested, and inline actions to approve or reject it.</p>
          <p>Previously, these rules appeared mixed together with active rules, which made it easy to miss that something needed attention.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>GitHub Integration GitHub App post-onboarding:</strong> we fixed an issue where some GitHub integration pages returned a 404 after the user completed onboarding. This affected routes such as <code>/github/integration</code> and <code>/github/organization-name</code> when the GitHub App installation state was not updated correctly. We also adjusted the redirect after installation and added route validations to make the integration flow more reliable across different states.</p>
          </div>

          <div>
            <p><strong>Severity slicer colors:</strong> the severity control for low, medium, high, and critical used inconsistent colors. In some places, red meant critical; in others, it meant high. We standardized it to a semantic scale: gray for low, yellow for medium, orange for high, and red for critical. This affects Cockpit filters, suggestion badges, and notification settings.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 22, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Forgejo support is now on par with GitHub & GitLab</div>
          <p>Review comments, commit statuses, force-push detection, and webhook coverage now work consistently for Forgejo repositories. If you self-host with Forgejo, Kody behaves just like on any other major platform.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Faster PR closing for large repos</div>
          <p>Eliminated duplicate API calls when syncing Kody Rules from changed files. PRs with many files now close noticeably faster.</p>
        </div>

        <div>
          <div>Cleaner settings UI</div>
          <p>Platform settings that don't apply to your current Git provider, such as GitHub-specific options when you're on GitLab, are now hidden automatically. Less clutter, fewer misconfigurations.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Reconnecting a Git provider after disconnecting:</strong> previously, disconnecting a provider left stale integration configs behind, causing reconnects to fail. Now stale rows are properly cleaned up.</p>
          </div>

          <div>
            <p><strong>Kody conversation replies with empty responses:</strong> resolved an issue where Kody occasionally replied with blank content in PR comment threads when using Claude Sonnet.</p>
          </div>

          <div>
            <p><strong>NaN deduplication indices:</strong> added three-layer protection against NaN values appearing in suggestion deduplication indices, preventing rare but confusing duplicate suggestions.</p>
          </div>

          <div>
            <p><strong>Forgejo prompt field always empty:</strong> the formatPromptForLLM function was reading a non-existent field on Forgejo PRs, causing the prompt section to be blank. Now it reads the correct field.</p>
          </div>

          <div>
            <p><strong>Self-hosted AST graph reliability:</strong> the kodus-graph CLI was installed but not available to the runtime user in self-hosted worker images. Fixed PATH and install order so graph indexing works out of the box.</p>
          </div>

          <div>
            <p><strong>Orphaned agent trace records:</strong> prevented a race condition in chunked review mode that could leave orphaned <code>IN\_PROGRESS</code> trace records in the database.</p>
          </div>

          <div>
            <p><strong>Platform settings not scoped to Git tool:</strong> settings incompatible with your current Git provider were still visible. Now they're properly filtered based on the connected tool.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 15, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Operational metrics in Cockpit</div>
          <p>Track the health of your review pipeline in real time. Throughput, queue, and processing time metrics are now available in Cockpit.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Redesigned Kodus Review tab</div>
          <p>The review tab has been redesigned with a cleaner interface and more direct actions. You can now analyze and act on suggestions without leaving the PR screen.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Backend on pnpm</div>
          <p>We migrated the backend from Yarn 1 to pnpm. This makes builds faster, improves lockfile consistency, and reduces cache issues across environments.</p>
        </div>

        <div>
          <div>Token usage screen</div>
          <p>The token usage screen has been redesigned to make consumption by organization and period easier to understand. It is now simpler to track usage and see how tokens are being consumed over time.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Self-hosted analytics:</strong> we fixed the analytics integration for self-hosted deployments. Usage metrics now appear correctly in the dashboard.</p>
          </div>

          <div>
            <p><strong>Issue cache:</strong> the issue count in the sidebar could sometimes become outdated. The cache is now invalidated correctly after changes.</p>
          </div>

          <div>
            <p><strong>GitHub rate limit:</strong> we fixed a rate limit issue in cloud E2E tests. We now use round-robin across multiple bot accounts to better distribute requests.</p>
          </div>

          <div>
            <p><strong>Notification routing:</strong> we fixed the behavior of targeted notifications when combined with audience settings. Notifications now reach the right people without duplicates.</p>
          </div>

          <div>
            <p><strong>Centralized config sync:</strong> we fixed issues in the centralized sync of Kody Rules configurations across repositories. Sync now correctly handles multiple scopes, stale configurations, and merge-triggered updates.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 8, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Moonshot Kimi support for BYOK</div>
          <p>We added support for Moonshot as a provider, compatible with the Anthropic API.</p>
          <p>You can now use the Kimi Coding Plan model in BYOK setups. To configure it, set the <code>API\_MOONSHOT\_API\_KEY</code> key and select the model in the organization preferences.</p>
          <p>See the <a href="https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus">Moonshot (Kimi)</a> documentation for more setup details.</p>
        </div>

        <div>
          <div>Monthly token usage control</div>
          <p>Organizations can now set monthly token consumption limits per model.</p>
          <p>Usage is shown in real time in the interface, with a progress bar. When usage reaches 80% of the limit, the team receives an email alert. If the limit is reached, additional reviews can be blocked automatically.</p>

          <video>
            <source type="video/mp4" />
          </video>

          <p>See the <a href="https://docs.kodus.io/how_to_use/en/spend-limit">Monthly Spend Limit</a> documentation for more setup details.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>More resilient review agent</div>
          <p>The review engine now handles empty or malformed LLM responses better.</p>
          <p>This reduces loops in edge cases and helps ensure valid suggestions continue to be delivered even when the provider returns an unexpected response.</p>
        </div>

        <div>
          <div>Telemetry for self-hosted environments</div>
          <p>On-premise installations now automatically report health metrics, such as heartbeat, and usage data.</p>
          <p>The goal is to make diagnosis and support easier without exposing sensitive customer data.</p>
        </div>

        <div>
          <div>Faster Kody Rules</div>
          <p>We improved the loading and synchronization of custom rules.</p>
          <p>We also fixed the count of orphaned rules and made partial updates safer against race conditions.</p>
        </div>

        <div>
          <div>GitLab compatibility improvements</div>

          <ul>
            <li>Support for GitLab 13.x in comment webhooks</li>
            <li>Diff fallback for versions earlier than 15.7</li>
            <li>Fixes for discussion threads and replies scoped by discussionId</li>
            <li>Self-hosted development environment documentation</li>
          </ul>
        </div>
      </div>

      <div>
        <div>Fixes</div>

        <div>
          <div>
            <p><strong>GitHub:</strong> suspended users no longer appear in the member list for license assignment.</p>
          </div>

          <div>
            <p><strong>Update Connection:</strong> integration reauthentication now correctly clears the previous configuration.</p>
          </div>

          <div>
            <p><strong>Integration reset:</strong> Kody Rules linked to the repo/directory are now removed automatically.</p>
          </div>

          <div>
            <p><strong>Release Freeze:</strong> eligibility notifications only appear when the freeze is active.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>
</div>

<div>
  <Update label="July 13, 2026 - New Token Usage Experience">
    The Token Usage page has been redesigned to provide a more complete view of consumption.

    It is now easier to track costs by area, model, and review activity, as well as filter the data and drill down into more specific analyses. This helps teams better understand where tokens are being used and how they can optimize costs.

    Video: [https://kodus.io/wp-content/uploads/2026/07/new-experience-token-usage.mp4](https://kodus.io/wp-content/uploads/2026/07/new-experience-token-usage.mp4)
  </Update>

  <Update label="July 13, 2026 - Automatic Detector Backfill for Existing Rules">
    Organizations that created Kody Rules before this release can also benefit from the new architecture. We created an automated process that analyzes existing rules and, whenever possible, generates mechanical detectors for them.

    The process is incremental, safe, and does not interfere with the normal execution of rules. When a rule cannot be converted into a detector, it continues to work through the traditional semantic review flow.
  </Update>

  <Update label="July 13, 2026 - More Accurate and Predictable Kody Rules">
    We restructured how Kody applies custom rules during code reviews. Instead of relying solely on a more open-ended agent analysis, rules are now evaluated deterministically by file and PR scope.

    In practice, this improves rule coverage in large PRs, reduces cases where an applicable rule is overlooked, and makes Kody Rules behave more consistently across different models.

    We also introduced mechanical detectors for certain rules. When a rule can safely be converted into an objective check, Kody can apply it without making an LLM call, reducing costs and improving predictability.
  </Update>

  <Update label="July 13, 2026 - Code Review Engine Improvements">
    This release includes a major upgrade to the review agent runtime. We migrated important parts of the execution flow to a new agent harness foundation, making the system more modular, observable, and ready for future improvements.

    We also improved the engine used to search for evidence in the codebase, with a focus on finding more relevant cross-file references and increasing the quality of generated suggestions.
  </Update>

  <Update label="July 13, 2026 - Cleaner Review Comments">
    We adjusted the format of Kody's review comments to prevent internal reasoning structures from appearing in the output and to make suggestions more natural, concise, and easier to understand.

    We also fixed issues involving aliases and internal prompt references following recent refactors.
  </Update>

  <Update label="July 13, 2026 - Improved BYOK Support">
    We improved BYOK support across different parts of the product, including configuration, model fallback, and per-model cost calculations.

    We also introduced a clearer experience for viewing BYOK settings and understanding how each model affects token consumption.
  </Update>

  <Update label="July 13, 2026 - More Accurate Cost Tracking and Telemetry">
    We improved the observability of LLM calls to ensure token usage is attributed correctly, especially within the new Kody Rules and agent workflows.

    This increases the accuracy of usage reports and prevents undercounting in more complex review scenarios.
  </Update>

  <Update label="July 13, 2026 - MCP Manager and Plugin Improvements">
    We improved tenant isolation for MCP connections, enhanced connection sorting and testing, and removed legacy integrations that had already been deprecated.

    These changes increase the reliability of the plugins and integrations experience.
  </Update>

  <Update label="July 13, 2026 - Improvements for Self-Hosted Environments">
    We applied fixes to Dockerfiles, provisioning scripts, and local configuration to make self-hosted environments more stable.

    We also fixed an issue involving pnpm on macOS and adjusted the API hostname configuration used during provisioning.
  </Update>

  <Update label="July 13, 2026 - More Stable Observability">
    We fixed excessive memory consumption in the Mongo observability exporter and improved logging behavior across different environments.

    We also removed outdated references to the previous internal framework, simplifying the observability codebase.
  </Update>

  <Update label="July 13, 2026 - New Quality Tests and Validations">
    We added new end-to-end scenarios and evaluations to validate Kody Rules, model recall, suggestion adherence, and prompt regressions.

    These validations help ensure that changes to models, prompts, or the underlying architecture do not reduce review quality.
  </Update>

  <Update label="July 13, 2026 - Updated Documentation">
    We updated the documentation for BYOK, custom messages, and focused reviews. We also revised the README and added new pages explaining how to guide Kody during a review.
  </Update>

  <Update label="July 13, 2026 - Safer Rule Execution">
    We added protections against potentially unsafe regex patterns in Kody Rules detectors. This prevents malformed or computationally expensive rules from affecting review performance. We also fixed cases where outdated detectors could remain associated with a rule after an edit changed the rule's intended behavior.
  </Update>

  <Update label="July 13, 2026 - License and Billing Improvements">
    We fixed issues involving trial creation, the listing of inactive users or users removed from the Git organization, and active seat counts. These changes make the license page more consistent and reduce discrepancies between the organization's actual users and the users displayed in billing.
  </Update>

  <Update label="July 6, 2026 - Steer a review with focus">
    You can now ask Kody to pay special attention to something specific during a review, without changing any configuration.

    In a PR, use @kody review \<directive>. In the CLI, use kodus review --focus.

    Examples: @kody review focus on security. @kody review focus on performance. Or in the CLI: kodus review --focus "edge cases".

    This is especially useful for larger PRs or sensitive changes, where you want the review to go deeper on a specific area, such as security, performance, edge cases, a business rule, or a team standard.

    Focus works as a priority, not a filter. Kody pays closer attention to the context you provide, but still reports other concrete issues it finds in the diff.

    Learn more in the Steer a Review Focus documentation: [https://docs.kodus.io/how\_to\_use/en/code\_review/review\_directive](https://docs.kodus.io/how_to_use/en/code_review/review_directive)
  </Update>

  <Update label="July 6, 2026 - Consolidate LLM prompts into a single comment">
    We added an option to generate a single PR comment containing all prompts and suggestions, so an external agent or AI tool can apply the fixes in one pass.

    Video: [https://kodus.io/wp-content/uploads/2026/07/agent-prompt.mp4](https://kodus.io/wp-content/uploads/2026/07/agent-prompt.mp4)
  </Update>

  <Update label="July 6, 2026 - Select all repositories at once">
    In the add repositories modal, we added select all and clear selection buttons. For teams connecting dozens of repositories, this removes the need to select each one manually and significantly reduces setup time.

    Video: [https://kodus.io/wp-content/uploads/2026/07/add-repo-qa.mp4](https://kodus.io/wp-content/uploads/2026/07/add-repo-qa.mp4)
  </Update>

  <Update label="July 6, 2026 - Cost breakdown by model (BYOK)">
    Teams using Bring Your Own Key now have a detailed view of LLM usage by model on the costs screen. Instead of seeing only the total amount, you can identify exactly which providers and models are driving most of the usage and make clearer decisions about what to keep, replace, or limit.

    Video: [https://kodus.io/wp-content/uploads/2026/07/resumo-de-custos-por-modelo.mp4](https://kodus.io/wp-content/uploads/2026/07/resumo-de-custos-por-modelo.mp4)
  </Update>

  <Update label="July 6, 2026 - Review agent consolidation">
    We reorganized the code review agents to run on a unified infrastructure. Previously, parts of the flow were spread across different places, which could lead to duplicated suggestions and inconsistent behavior. With this consolidation, the pipeline is more predictable, easier to maintain, and less likely to repeat suggestions in the same PR.
  </Update>

  <Update label="July 6, 2026 - Content guard for deduplication">
    We improved the deduplication algorithm so distinct bugs are not grouped as if they were the same issue. The content guard now better considers the actual content of each suggestion, reducing false-positive deduplication and making sure separate issues continue to be reported individually.
  </Update>

  <Update label="July 6, 2026 - Prose findings recovery + Gemini support">
    We fixed unstable behavior in prose finding generation and restored strict mode for Gemini. We also updated the Anthropic SDK, keeping compatibility with newer models and improving response stability.
  </Update>

  <Update label="July 6, 2026 - RBAC documentation">
    We updated the permissions documentation, including the OrganizationSettings scope and the restriction that only the organization Owner can configure BYOK. This makes it clearer who can do what inside the workspace.
  </Update>

  <Update label="July 6, 2026 - Review comments with broken formatting">
    Fixed cases where Kody comments appeared with unexpected formatting in pull requests.
  </Update>

  <Update label="July 6, 2026 - Retry errors with BYOK providers">
    Added preventive adjustments to avoid retry failures when a BYOK provider returns an empty response body.
  </Update>

  <Update label="July 6, 2026 - Sandbox tool errors">
    The agent now handles errors better when running tools in the sandbox environment, without breaking the review.
  </Update>

  <Update label="July 6, 2026 - Normalized user IDs">
    Standardized how author, reviewer, and assignee IDs are handled, preventing PRs from breaking because of type differences, such as string vs. number.
  </Update>

  <Update label="July 6, 2026 - @kody conversation crashing on JSON wrapped in prose">
    Fixed a crash that happened when Kody responded to mentions and the output came back as text containing embedded JSON.
  </Update>

  <Update label="July 6, 2026 - IDE sync config now respects approval settings">
    IDE rule synchronization now respects the approval configuration.
  </Update>

  <Update label="July 6, 2026 - Rules with multiple directories">
    Adjusted Kody Rules validation to correctly handle rules that apply to multiple path groups.
  </Update>

  <Update label="July 6, 2026 - Automatic code review config creation">
    When a repository did not have a code review configuration, creating a Kody Rule could fail silently. The configuration is now created automatically.
  </Update>

  <Update label="July 6, 2026 - Diff re-review in the agent">
    Improved how the agent detects diffs from new commits during re-reviews.
  </Update>

  <Update label="July 6, 2026 - MCP Manager OAuth disconnect">
    Fixed an issue with disconnecting OAuth credentials in MCP Manager that could cause inconsistent behavior.
  </Update>

  <Update label="July 6, 2026 - MCP Manager production build">
    The MCP Manager production build now correctly passes the GitHub token.
  </Update>

  <Update label="July 6, 2026 - Orphaned users in the license list">
    Users removed from the GitHub organization now appear correctly in the license list.
  </Update>

  <Update label="July 6, 2026 - Skipped review email">
    The notification email sent when a review is skipped now includes the author's name/email and no longer breaks when the user does not have a license.
  </Update>

  <Update label="June 29, 2026 - Validated review engine">
    We updated Kody's review pipeline to improve analysis accuracy and reduce cases where important issues could slip through unnoticed.

    The engine now identifies problematic patterns more effectively, better understands changes that span multiple files, and can review code regions with more flexibility when the context is not fully obvious.

    We also optimized processing and reduced the average cost per review by around 30%.
  </Update>

  <Update label="June 29, 2026 - Shareable dashboard views">
    Filters applied in Cockpit are now saved in the URL, including time range, repositories, severity, and status.

    This means you can copy the link and share it with your team on Slack, for example. Anyone who opens the URL will see Cockpit with the same filters applied, without having to manually recreate the view.

    This makes it easier to share specific analyses, such as what changed over the past week or an increase in security suggestions in a repository.

    Video: [https://kodus.io/wp-content/uploads/2026/06/kodus-copy-url.mp4](https://kodus.io/wp-content/uploads/2026/06/kodus-copy-url.mp4)
  </Update>

  <Update label="June 29, 2026 - Unified Kody Rules lifecycle">
    We unified the Kody Rules flow into a single lifecycle, regardless of where the rule was created: the library, manual creation, or inheritance from the organization to the repository.

    With this change, activating, editing, disabling, and approving rules now follow the same path inside the product. We also migrated older rules to the new format and centralized the control of rules pending approval.

    This makes the system more consistent, reduces unexpected states, and ensures that an active rule is actually applied in Kody reviews.
  </Update>

  <Update label="June 29, 2026 - Migrate away from Composio">
    We removed the dependency on Composio as an external MCP broker and moved to our own implementation for GitHub Issues, now integrated with Kodus Issues.

    This reduces an external point of failure, improves call reliability, and gives us more control over authentication, rate limits, and retries.

    As part of the migration, we also removed low-usage integrations that depended on Composio, such as ClickUp and CloudId.
  </Update>

  <Update label="June 29, 2026 - Inheritance toggle">
    When you enable or disable rule inheritance from the organization to a repository, the UI now shows the new state immediately, without waiting for the API response.

    If the call fails, for example because of a connection issue, the state is automatically reverted and we show an error toast. Before, users would click, wait, and not get clear feedback about what had happened.

    We also improved the rules cache update. Now we only invalidate the rules affected by that inheritance change, avoiding unnecessary reloads for rules that did not change.
  </Update>

  <Update label="June 29, 2026 - Kody Rules Origin">
    We added an explicit origin to all Kody Rules: LIBRARY, MANUAL, INHERITED, and SUGGESTED.

    This fixes an issue where some rule creation scenarios could fail silently because the backend expected an origin value that the frontend was not sending.

    Now the contract between frontend and backend is clearer, and the rule origin is validated before reaching the creation flow.
  </Update>

  <Update label="June 29, 2026 - Atlassian Rovo">
    Rovo is an Atlassian AI agent that generates code and edits files automatically. When it creates commits, it includes specific metadata, such as message prefixes and custom headers.

    Previously, our review engine identified those commits as human-written code and could suggest changes on them.

    Now we detect Rovo commits and skip those changes both in the code review logic and in the MCP business-rule validation preflight.
  </Update>

  <Update label="June 29, 2026 - MCP OAuth callback">
    We fixed the OAuth flow for connecting MCPs, such as GitHub and Jira.

    Previously, users who had already completed onboarding could be blocked when trying to add a new MCP. Now the callback works at any time, as long as the state parameter is valid.
  </Update>

  <Update label="June 29, 2026 - Pending rules section">
    Pending rules, which need approval before entering the review pipeline, now have a dedicated section with improved UX.

    The section shows a status badge, who suggested the rule, when it was suggested, and inline actions to approve or reject it.

    Previously, these rules appeared mixed together with active rules, which made it easy to miss that something needed attention.
  </Update>

  <Update label="June 29, 2026 - GitHub Integration GitHub App post-onboarding">
    We fixed an issue where some GitHub integration pages returned a 404 after the user completed onboarding. This affected routes such as /github/integration and /github/organization-name when the GitHub App installation state was not updated correctly. We also adjusted the redirect after installation and added route validations to make the integration flow more reliable across different states.
  </Update>

  <Update label="June 29, 2026 - Severity slicer colors">
    The severity control for low, medium, high, and critical used inconsistent colors. In some places, red meant critical; in others, it meant high. We standardized it to a semantic scale: gray for low, yellow for medium, orange for high, and red for critical. This affects Cockpit filters, suggestion badges, and notification settings.
  </Update>

  <Update label="June 22, 2026 - Forgejo support is now on par with GitHub & GitLab">
    Review comments, commit statuses, force-push detection, and webhook coverage now work consistently for Forgejo repositories. If you self-host with Forgejo, Kody behaves just like on any other major platform.
  </Update>

  <Update label="June 22, 2026 - Faster PR closing for large repos">
    Eliminated duplicate API calls when syncing Kody Rules from changed files. PRs with many files now close noticeably faster.
  </Update>

  <Update label="June 22, 2026 - Cleaner settings UI">
    Platform settings that don't apply to your current Git provider, such as GitHub-specific options when you're on GitLab, are now hidden automatically. Less clutter, fewer misconfigurations.
  </Update>

  <Update label="June 22, 2026 - Reconnecting a Git provider after disconnecting">
    Previously, disconnecting a provider left stale integration configs behind, causing reconnects to fail. Now stale rows are properly cleaned up.
  </Update>

  <Update label="June 22, 2026 - Kody conversation replies with empty responses">
    Resolved an issue where Kody occasionally replied with blank content in PR comment threads when using Claude Sonnet.
  </Update>

  <Update label="June 22, 2026 - NaN deduplication indices">
    Added three-layer protection against NaN values appearing in suggestion deduplication indices, preventing rare but confusing duplicate suggestions.
  </Update>

  <Update label="June 22, 2026 - Forgejo prompt field always empty">
    The formatPromptForLLM function was reading a non-existent field on Forgejo PRs, causing the prompt section to be blank. Now it reads the correct field.
  </Update>

  <Update label="June 22, 2026 - Self-hosted AST graph reliability">
    The kodus-graph CLI was installed but not available to the runtime user in self-hosted worker images. Fixed PATH and install order so graph indexing works out of the box.
  </Update>

  <Update label="June 22, 2026 - Orphaned agent trace records">
    Prevented a race condition in chunked review mode that could leave orphaned IN\_PROGRESS trace records in the database.
  </Update>

  <Update label="June 22, 2026 - Platform settings not scoped to Git tool">
    Settings incompatible with your current Git provider were still visible. Now they're properly filtered based on the connected tool.
  </Update>

  <Update label="June 15, 2026 - Operational metrics in Cockpit">
    Track the health of your review pipeline in real time. Throughput, queue, and processing time metrics are now available in Cockpit.

    Video: [https://kodus.io/wp-content/uploads/2026/06/cockpit.mp4](https://kodus.io/wp-content/uploads/2026/06/cockpit.mp4)
  </Update>

  <Update label="June 15, 2026 - Redesigned Kodus Review tab">
    The review tab has been redesigned with a cleaner interface and more direct actions. You can now analyze and act on suggestions without leaving the PR screen.

    Video: [https://kodus.io/wp-content/uploads/2026/06/kody-review-tab.mp4](https://kodus.io/wp-content/uploads/2026/06/kody-review-tab.mp4)
  </Update>

  <Update label="June 15, 2026 - Backend on pnpm">
    We migrated the backend from Yarn 1 to pnpm. This makes builds faster, improves lockfile consistency, and reduces cache issues across environments.
  </Update>

  <Update label="June 15, 2026 - Token usage screen">
    The token usage screen has been redesigned to make consumption by organization and period easier to understand. It is now simpler to track usage and see how tokens are being consumed over time.

    Video: [https://kodus.io/wp-content/uploads/2026/06/token\_usage.mp4](https://kodus.io/wp-content/uploads/2026/06/token_usage.mp4)
  </Update>

  <Update label="June 15, 2026 - Self-hosted analytics">
    We fixed the analytics integration for self-hosted deployments. Usage metrics now appear correctly in the dashboard.
  </Update>

  <Update label="June 15, 2026 - Issue cache">
    The issue count in the sidebar could sometimes become outdated. The cache is now invalidated correctly after changes.
  </Update>

  <Update label="June 15, 2026 - GitHub rate limit">
    We fixed a rate limit issue in cloud E2E tests. We now use round-robin across multiple bot accounts to better distribute requests.
  </Update>

  <Update label="June 15, 2026 - Notification routing">
    We fixed the behavior of targeted notifications when combined with audience settings. Notifications now reach the right people without duplicates.
  </Update>

  <Update label="June 15, 2026 - Centralized config sync">
    We fixed issues in the centralized sync of Kody Rules configurations across repositories. Sync now correctly handles multiple scopes, stale configurations, and merge-triggered updates.
  </Update>

  <Update label="June 8, 2026 - Moonshot Kimi support for BYOK">
    We added support for Moonshot as a provider, compatible with the Anthropic API.

    You can now use the Kimi Coding Plan model in BYOK setups. To configure it, set the API\_MOONSHOT\_API\_KEY key and select the model in the organization preferences.

    See the Moonshot Kimi documentation for more setup details: [https://docs.kodus.io/knowledge\_base/en/how-to-use-moonshot-with-kodus](https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus)
  </Update>

  <Update label="June 8, 2026 - Monthly token usage control">
    Organizations can now set monthly token consumption limits per model.

    Usage is shown in real time in the interface, with a progress bar. When usage reaches 80% of the limit, the team receives an email alert. If the limit is reached, additional reviews can be blocked automatically.

    Video: [https://kodus.io/wp-content/uploads/2026/06/token-usage.mov](https://kodus.io/wp-content/uploads/2026/06/token-usage.mov)

    See the Monthly Spend Limit documentation for more setup details: [https://docs.kodus.io/how\_to\_use/en/spend-limit](https://docs.kodus.io/how_to_use/en/spend-limit)
  </Update>

  <Update label="June 8, 2026 - More resilient review agent">
    The review engine now handles empty or malformed LLM responses better. This reduces loops in edge cases and helps ensure valid suggestions continue to be delivered even when the provider returns an unexpected response.
  </Update>

  <Update label="June 8, 2026 - Telemetry for self-hosted environments">
    On-premise installations now automatically report health metrics, such as heartbeat, and usage data. The goal is to make diagnosis and support easier without exposing sensitive customer data.
  </Update>

  <Update label="June 8, 2026 - Faster Kody Rules">
    We improved the loading and synchronization of custom rules. We also fixed the count of orphaned rules and made partial updates safer against race conditions.
  </Update>

  <Update label="June 8, 2026 - GitLab compatibility improvements">
    Support for GitLab 13.x in comment webhooks.

    Diff fallback for versions earlier than 15.7.

    Fixes for discussion threads and replies scoped by discussionId.

    Self-hosted development environment documentation.
  </Update>

  <Update label="June 8, 2026 - GitHub member list fix">
    Suspended users no longer appear in the member list for license assignment.
  </Update>

  <Update label="June 8, 2026 - Update Connection fix">
    Integration reauthentication now correctly clears the previous configuration.
  </Update>

  <Update label="June 8, 2026 - Integration reset fix">
    Kody Rules linked to the repo or directory are now removed automatically.
  </Update>

  <Update label="June 8, 2026 - Release Freeze fix">
    Eligibility notifications only appear when the freeze is active.
  </Update>
</div>


# Changelog
Source: https://docs.kodus.io/changelog/index

Latest Kodus updates and improvements.

<div>
  <div>
    <div aria-label="Changelog filters">
      <p>Filters</p>

      <div>
        <label>
          <input type="checkbox" />

          <span>Security</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Cockpit</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>BYOK</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>AI Engine</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Self-hosted</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>GIT Provider</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Performance</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>UX & Interface</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Notifications</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Kody Rules</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>MCP</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Billing & Licenses</span>
        </label>
      </div>
    </div>
  </div>

  <div>
    <div>
      <span>July 13, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>New Token Usage Experience</div>
          <p>The Token Usage page has been redesigned to provide a more complete view of consumption.</p>
          <p>It is now easier to track costs by area, model, and review activity, as well as filter the data and drill down into more specific analyses. This helps teams better understand where tokens are being used and how they can optimize costs.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Automatic Detector Backfill for Existing Rules</div>
          <p>Organizations that created Kody Rules before this release can also benefit from the new architecture. We created an automated process that analyzes existing rules and, whenever possible, generates mechanical detectors for them.</p>
          <p>The process is incremental, safe, and does not interfere with the normal execution of rules. When a rule cannot be converted into a detector, it continues to work through the traditional semantic review flow.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>More Accurate and Predictable Kody Rules</div>
          <p>We restructured how Kody applies custom rules during code reviews. Instead of relying solely on a more open-ended agent analysis, rules are now evaluated deterministically by file and PR scope.</p>
          <p>In practice, this improves rule coverage in large PRs, reduces cases where an applicable rule is overlooked, and makes Kody Rules behave more consistently across different models.</p>
          <p>We also introduced mechanical detectors for certain rules. When a rule can safely be converted into an objective check, Kody can apply it without making an LLM call, reducing costs and improving predictability.</p>
        </div>

        <div>
          <div>Code Review Engine Improvements</div>
          <p>This release includes a major upgrade to the review agent runtime. We migrated important parts of the execution flow to a new agent harness foundation, making the system more modular, observable, and ready for future improvements.</p>
          <p>We also improved the engine used to search for evidence in the codebase, with a focus on finding more relevant cross-file references and increasing the quality of generated suggestions.</p>
        </div>

        <div>
          <div>Cleaner Review Comments</div>
          <p>We adjusted the format of Kody's review comments to prevent internal reasoning structures from appearing in the output and to make suggestions more natural, concise, and easier to understand.</p>
          <p>We also fixed issues involving aliases and internal prompt references following recent refactors.</p>
        </div>

        <div>
          <div>Improved BYOK Support</div>
          <p>We improved BYOK support across different parts of the product, including configuration, model fallback, and per-model cost calculations.</p>
          <p>We also introduced a clearer experience for viewing BYOK settings and understanding how each model affects token consumption.</p>
        </div>

        <div>
          <div>More Accurate Cost Tracking and Telemetry</div>
          <p>We improved the observability of LLM calls to ensure token usage is attributed correctly, especially within the new Kody Rules and agent workflows.</p>
          <p>This increases the accuracy of usage reports and prevents undercounting in more complex review scenarios.</p>
        </div>

        <div>
          <div>MCP Manager and Plugin Improvements</div>
          <p>We improved tenant isolation for MCP connections, enhanced connection sorting and testing, and removed legacy integrations that had already been deprecated.</p>
          <p>These changes increase the reliability of the plugins and integrations experience.</p>
        </div>

        <div>
          <div>Improvements for Self-Hosted Environments</div>
          <p>We applied fixes to Dockerfiles, provisioning scripts, and local configuration to make self-hosted environments more stable.</p>
          <p>We also fixed an issue involving pnpm on macOS and adjusted the API hostname configuration used during provisioning.</p>
        </div>

        <div>
          <div>More Stable Observability</div>
          <p>We fixed excessive memory consumption in the Mongo observability exporter and improved logging behavior across different environments.</p>
          <p>We also removed outdated references to the previous internal framework, simplifying the observability codebase.</p>
        </div>

        <div>
          <div>New Quality Tests and Validations</div>
          <p>We added new end-to-end scenarios and evaluations to validate Kody Rules, model recall, suggestion adherence, and prompt regressions.</p>
          <p>These validations help ensure that changes to models, prompts, or the underlying architecture do not reduce review quality.</p>
        </div>

        <div>
          <div>Updated Documentation</div>
          <p>We updated the documentation for BYOK, custom messages, and focused reviews. We also revised the README and added new pages explaining how to guide Kody during a review.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Safer Rule Execution:</strong> we added protections against potentially unsafe regex patterns in Kody Rules detectors. This prevents malformed or computationally expensive rules from affecting review performance. We also fixed cases where outdated detectors could remain associated with a rule after an edit changed the rule's intended behavior.</p>
          </div>

          <div>
            <p><strong>License and Billing Improvements:</strong> we fixed issues involving trial creation, the listing of inactive users or users removed from the Git organization, and active seat counts. These changes make the license page more consistent and reduce discrepancies between the organization's actual users and the users displayed in billing.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>July 6, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Steer a review with focus</div>
          <p>You can now ask Kody to pay special attention to something specific during a review, without changing any configuration.</p>
          <p>In a PR, use <code>@kody review \<directive></code>. In the CLI, use <code>kodus review --focus</code>.</p>
          <p>Examples:</p>

          <ul>
            <li><code>@kody review focus on security</code></li>
            <li><code>@kody review focus on performance</code></li>
            <li><code>kodus review --focus "edge cases"</code></li>
          </ul>

          <p>This is especially useful for larger PRs or sensitive changes, where you want the review to go deeper on a specific area, such as security, performance, edge cases, a business rule, or a team standard.</p>
          <p>Focus works as a priority, not a filter. Kody pays closer attention to the context you provide, but still reports other concrete issues it finds in the diff.</p>
          <p>Learn more in the <a href="https://docs.kodus.io/how_to_use/en/code_review/review_directive">Steer a Review (Focus)</a> documentation.</p>
        </div>

        <div>
          <div>Consolidate LLM prompts into a single comment</div>
          <p>We added an option to generate a single PR comment containing all prompts and suggestions, so an external agent or AI tool can apply the fixes in one pass.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Select all repositories at once</div>
          <p>In the add repositories modal, we added <strong>select all</strong> and <strong>clear selection</strong> buttons. For teams connecting dozens of repositories, this removes the need to select each one manually and significantly reduces setup time.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Cost breakdown by model (BYOK)</div>
          <p>Teams using Bring Your Own Key now have a detailed view of LLM usage by model on the costs screen. Instead of seeing only the total amount, you can identify exactly which providers and models are driving most of the usage and make clearer decisions about what to keep, replace, or limit.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Review agent consolidation</div>
          <p>We reorganized the code review agents to run on a unified infrastructure. Previously, parts of the flow were spread across different places, which could lead to duplicated suggestions and inconsistent behavior. With this consolidation, the pipeline is more predictable, easier to maintain, and less likely to repeat suggestions in the same PR.</p>
        </div>

        <div>
          <div>Content guard for deduplication</div>
          <p>We improved the deduplication algorithm so distinct bugs are not grouped as if they were the same issue. The content guard now better considers the actual content of each suggestion, reducing false-positive deduplication and making sure separate issues continue to be reported individually.</p>
        </div>

        <div>
          <div>Prose findings recovery + Gemini support</div>
          <p>We fixed unstable behavior in prose finding generation and restored strict mode for Gemini. We also updated the Anthropic SDK, keeping compatibility with newer models and improving response stability.</p>
        </div>

        <div>
          <div>RBAC documentation</div>
          <p>We updated the permissions documentation, including the <code>OrganizationSettings</code> scope and the restriction that only the organization Owner can configure BYOK. This makes it clearer who can do what inside the workspace.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Review comments with broken formatting:</strong> fixed cases where Kody comments appeared with unexpected formatting in pull requests.</p>
          </div>

          <div>
            <p><strong>Retry errors with BYOK providers:</strong> added preventive adjustments to avoid retry failures when a BYOK provider returns an empty response body.</p>
          </div>

          <div>
            <p><strong>Sandbox tool errors:</strong> the agent now handles errors better when running tools in the sandbox environment, without breaking the review.</p>
          </div>

          <div>
            <p><strong>Normalized user IDs:</strong> standardized how author, reviewer, and assignee IDs are handled, preventing PRs from breaking because of type differences, such as string vs. number.</p>
          </div>

          <div>
            <p><strong>@kody conversation crashing on JSON wrapped in prose:</strong> fixed a crash that happened when Kody responded to mentions and the output came back as text containing embedded JSON.</p>
          </div>

          <div>
            <p><strong>IDE sync config now respects approval settings:</strong> IDE rule synchronization now respects the approval configuration.</p>
          </div>

          <div>
            <p><strong>Rules with multiple directories:</strong> adjusted Kody Rules validation to correctly handle rules that apply to multiple path groups.</p>
          </div>

          <div>
            <p><strong>Automatic code review config creation:</strong> when a repository did not have a code review configuration, creating a Kody Rule could fail silently. The configuration is now created automatically.</p>
          </div>

          <div>
            <p><strong>Diff re-review in the agent:</strong> improved how the agent detects diffs from new commits during re-reviews.</p>
          </div>

          <div>
            <p><strong>MCP Manager OAuth disconnect:</strong> fixed an issue with disconnecting OAuth credentials in MCP Manager that could cause inconsistent behavior.</p>
          </div>

          <div>
            <p><strong>MCP Manager production build:</strong> the MCP Manager production build now correctly passes the GitHub token.</p>
          </div>

          <div>
            <p><strong>Orphaned users in the license list:</strong> users removed from the GitHub organization now appear correctly in the license list.</p>
          </div>

          <div>
            <p><strong>Skipped review email:</strong> the notification email sent when a review is skipped now includes the author's name/email and no longer breaks when the user does not have a license.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 29, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Validated review engine</div>
          <p>We updated Kody's review pipeline to improve analysis accuracy and reduce cases where important issues could slip through unnoticed.</p>
          <p>The engine now identifies problematic patterns more effectively, better understands changes that span multiple files, and can review code regions with more flexibility when the context is not fully obvious.</p>
          <p>We also optimized processing and reduced the average cost per review by around 30%.</p>
        </div>

        <div>
          <div>Shareable dashboard views</div>
          <p>Filters applied in Cockpit are now saved in the URL, including time range, repositories, severity, and status.</p>
          <p>This means you can copy the link and share it with your team on Slack, for example. Anyone who opens the URL will see Cockpit with the same filters applied, without having to manually recreate the view.</p>
          <p>This makes it easier to share specific analyses, such as what changed over the past week or an increase in security suggestions in a repository.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Unified Kody Rules lifecycle</div>
          <p>We unified the Kody Rules flow into a single lifecycle, regardless of where the rule was created: the library, manual creation, or inheritance from the organization to the repository.</p>
          <p>With this change, activating, editing, disabling, and approving rules now follow the same path inside the product. We also migrated older rules to the new format and centralized the control of rules pending approval.</p>
          <p>This makes the system more consistent, reduces unexpected states, and ensures that an active rule is actually applied in Kody reviews.</p>
        </div>

        <div>
          <div>Migrate away from Composio</div>
          <p>We removed the dependency on Composio as an external MCP broker and moved to our own implementation for GitHub Issues, now integrated with Kodus Issues.</p>
          <p>This reduces an external point of failure, improves call reliability, and gives us more control over authentication, rate limits, and retries.</p>
          <p>As part of the migration, we also removed low-usage integrations that depended on Composio, such as ClickUp and CloudId.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Inheritance toggle</div>
          <p>When you enable or disable rule inheritance from the organization to a repository, the UI now shows the new state immediately, without waiting for the API response.</p>
          <p>If the call fails, for example because of a connection issue, the state is automatically reverted and we show an error toast. Before, users would click, wait, and not get clear feedback about what had happened.</p>
          <p>We also improved the rules cache update. Now we only invalidate the rules affected by that inheritance change, avoiding unnecessary reloads for rules that did not change.</p>
        </div>

        <div>
          <div>Kody Rules Origin</div>
          <p>We added an explicit origin to all Kody Rules: <code>LIBRARY</code>, <code>MANUAL</code>, <code>INHERITED</code>, and <code>SUGGESTED</code>.</p>
          <p>This fixes an issue where some rule creation scenarios could fail silently because the backend expected an origin value that the frontend was not sending.</p>
          <p>Now the contract between frontend and backend is clearer, and the rule origin is validated before reaching the creation flow.</p>
        </div>

        <div>
          <div>Atlassian Rovo</div>
          <p>Rovo is an Atlassian AI agent that generates code and edits files automatically. When it creates commits, it includes specific metadata, such as message prefixes and custom headers.</p>
          <p>Previously, our review engine identified those commits as human-written code and could suggest changes on them.</p>
          <p>Now we detect Rovo commits and skip those changes both in the code review logic and in the MCP business-rule validation preflight.</p>
        </div>

        <div>
          <div>MCP OAuth callback</div>
          <p>We fixed the OAuth flow for connecting MCPs, such as GitHub and Jira.</p>
          <p>Previously, users who had already completed onboarding could be blocked when trying to add a new MCP. Now the callback works at any time, as long as the state parameter is valid.</p>
        </div>

        <div>
          <div>Pending rules section</div>
          <p>Pending rules, which need approval before entering the review pipeline, now have a dedicated section with improved UX.</p>
          <p>The section shows a status badge, who suggested the rule, when it was suggested, and inline actions to approve or reject it.</p>
          <p>Previously, these rules appeared mixed together with active rules, which made it easy to miss that something needed attention.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>GitHub Integration GitHub App post-onboarding:</strong> we fixed an issue where some GitHub integration pages returned a 404 after the user completed onboarding. This affected routes such as <code>/github/integration</code> and <code>/github/organization-name</code> when the GitHub App installation state was not updated correctly. We also adjusted the redirect after installation and added route validations to make the integration flow more reliable across different states.</p>
          </div>

          <div>
            <p><strong>Severity slicer colors:</strong> the severity control for low, medium, high, and critical used inconsistent colors. In some places, red meant critical; in others, it meant high. We standardized it to a semantic scale: gray for low, yellow for medium, orange for high, and red for critical. This affects Cockpit filters, suggestion badges, and notification settings.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 22, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Forgejo support is now on par with GitHub & GitLab</div>
          <p>Review comments, commit statuses, force-push detection, and webhook coverage now work consistently for Forgejo repositories. If you self-host with Forgejo, Kody behaves just like on any other major platform.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Faster PR closing for large repos</div>
          <p>Eliminated duplicate API calls when syncing Kody Rules from changed files. PRs with many files now close noticeably faster.</p>
        </div>

        <div>
          <div>Cleaner settings UI</div>
          <p>Platform settings that don't apply to your current Git provider, such as GitHub-specific options when you're on GitLab, are now hidden automatically. Less clutter, fewer misconfigurations.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Reconnecting a Git provider after disconnecting:</strong> previously, disconnecting a provider left stale integration configs behind, causing reconnects to fail. Now stale rows are properly cleaned up.</p>
          </div>

          <div>
            <p><strong>Kody conversation replies with empty responses:</strong> resolved an issue where Kody occasionally replied with blank content in PR comment threads when using Claude Sonnet.</p>
          </div>

          <div>
            <p><strong>NaN deduplication indices:</strong> added three-layer protection against NaN values appearing in suggestion deduplication indices, preventing rare but confusing duplicate suggestions.</p>
          </div>

          <div>
            <p><strong>Forgejo prompt field always empty:</strong> the formatPromptForLLM function was reading a non-existent field on Forgejo PRs, causing the prompt section to be blank. Now it reads the correct field.</p>
          </div>

          <div>
            <p><strong>Self-hosted AST graph reliability:</strong> the kodus-graph CLI was installed but not available to the runtime user in self-hosted worker images. Fixed PATH and install order so graph indexing works out of the box.</p>
          </div>

          <div>
            <p><strong>Orphaned agent trace records:</strong> prevented a race condition in chunked review mode that could leave orphaned <code>IN\_PROGRESS</code> trace records in the database.</p>
          </div>

          <div>
            <p><strong>Platform settings not scoped to Git tool:</strong> settings incompatible with your current Git provider were still visible. Now they're properly filtered based on the connected tool.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 15, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Operational metrics in Cockpit</div>
          <p>Track the health of your review pipeline in real time. Throughput, queue, and processing time metrics are now available in Cockpit.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Redesigned Kodus Review tab</div>
          <p>The review tab has been redesigned with a cleaner interface and more direct actions. You can now analyze and act on suggestions without leaving the PR screen.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Backend on pnpm</div>
          <p>We migrated the backend from Yarn 1 to pnpm. This makes builds faster, improves lockfile consistency, and reduces cache issues across environments.</p>
        </div>

        <div>
          <div>Token usage screen</div>
          <p>The token usage screen has been redesigned to make consumption by organization and period easier to understand. It is now simpler to track usage and see how tokens are being consumed over time.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Self-hosted analytics:</strong> we fixed the analytics integration for self-hosted deployments. Usage metrics now appear correctly in the dashboard.</p>
          </div>

          <div>
            <p><strong>Issue cache:</strong> the issue count in the sidebar could sometimes become outdated. The cache is now invalidated correctly after changes.</p>
          </div>

          <div>
            <p><strong>GitHub rate limit:</strong> we fixed a rate limit issue in cloud E2E tests. We now use round-robin across multiple bot accounts to better distribute requests.</p>
          </div>

          <div>
            <p><strong>Notification routing:</strong> we fixed the behavior of targeted notifications when combined with audience settings. Notifications now reach the right people without duplicates.</p>
          </div>

          <div>
            <p><strong>Centralized config sync:</strong> we fixed issues in the centralized sync of Kody Rules configurations across repositories. Sync now correctly handles multiple scopes, stale configurations, and merge-triggered updates.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 8, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Moonshot Kimi support for BYOK</div>
          <p>We added support for Moonshot as a provider, compatible with the Anthropic API.</p>
          <p>You can now use the Kimi Coding Plan model in BYOK setups. To configure it, set the <code>API\_MOONSHOT\_API\_KEY</code> key and select the model in the organization preferences.</p>
          <p>See the <a href="https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus">Moonshot (Kimi)</a> documentation for more setup details.</p>
        </div>

        <div>
          <div>Monthly token usage control</div>
          <p>Organizations can now set monthly token consumption limits per model.</p>
          <p>Usage is shown in real time in the interface, with a progress bar. When usage reaches 80% of the limit, the team receives an email alert. If the limit is reached, additional reviews can be blocked automatically.</p>

          <video>
            <source type="video/mp4" />
          </video>

          <p>See the <a href="https://docs.kodus.io/how_to_use/en/spend-limit">Monthly Spend Limit</a> documentation for more setup details.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>More resilient review agent</div>
          <p>The review engine now handles empty or malformed LLM responses better.</p>
          <p>This reduces loops in edge cases and helps ensure valid suggestions continue to be delivered even when the provider returns an unexpected response.</p>
        </div>

        <div>
          <div>Telemetry for self-hosted environments</div>
          <p>On-premise installations now automatically report health metrics, such as heartbeat, and usage data.</p>
          <p>The goal is to make diagnosis and support easier without exposing sensitive customer data.</p>
        </div>

        <div>
          <div>Faster Kody Rules</div>
          <p>We improved the loading and synchronization of custom rules.</p>
          <p>We also fixed the count of orphaned rules and made partial updates safer against race conditions.</p>
        </div>

        <div>
          <div>GitLab compatibility improvements</div>

          <ul>
            <li>Support for GitLab 13.x in comment webhooks</li>
            <li>Diff fallback for versions earlier than 15.7</li>
            <li>Fixes for discussion threads and replies scoped by discussionId</li>
            <li>Self-hosted development environment documentation</li>
          </ul>
        </div>
      </div>

      <div>
        <div>Fixes</div>

        <div>
          <div>
            <p><strong>GitHub:</strong> suspended users no longer appear in the member list for license assignment.</p>
          </div>

          <div>
            <p><strong>Update Connection:</strong> integration reauthentication now correctly clears the previous configuration.</p>
          </div>

          <div>
            <p><strong>Integration reset:</strong> Kody Rules linked to the repo/directory are now removed automatically.</p>
          </div>

          <div>
            <p><strong>Release Freeze:</strong> eligibility notifications only appear when the freeze is active.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>
</div>

<div>
  <Update label="July 13, 2026 - New Token Usage Experience">
    The Token Usage page has been redesigned to provide a more complete view of consumption.

    It is now easier to track costs by area, model, and review activity, as well as filter the data and drill down into more specific analyses. This helps teams better understand where tokens are being used and how they can optimize costs.

    Video: [https://kodus.io/wp-content/uploads/2026/07/new-experience-token-usage.mp4](https://kodus.io/wp-content/uploads/2026/07/new-experience-token-usage.mp4)
  </Update>

  <Update label="July 13, 2026 - Automatic Detector Backfill for Existing Rules">
    Organizations that created Kody Rules before this release can also benefit from the new architecture. We created an automated process that analyzes existing rules and, whenever possible, generates mechanical detectors for them.

    The process is incremental, safe, and does not interfere with the normal execution of rules. When a rule cannot be converted into a detector, it continues to work through the traditional semantic review flow.
  </Update>

  <Update label="July 13, 2026 - More Accurate and Predictable Kody Rules">
    We restructured how Kody applies custom rules during code reviews. Instead of relying solely on a more open-ended agent analysis, rules are now evaluated deterministically by file and PR scope.

    In practice, this improves rule coverage in large PRs, reduces cases where an applicable rule is overlooked, and makes Kody Rules behave more consistently across different models.

    We also introduced mechanical detectors for certain rules. When a rule can safely be converted into an objective check, Kody can apply it without making an LLM call, reducing costs and improving predictability.
  </Update>

  <Update label="July 13, 2026 - Code Review Engine Improvements">
    This release includes a major upgrade to the review agent runtime. We migrated important parts of the execution flow to a new agent harness foundation, making the system more modular, observable, and ready for future improvements.

    We also improved the engine used to search for evidence in the codebase, with a focus on finding more relevant cross-file references and increasing the quality of generated suggestions.
  </Update>

  <Update label="July 13, 2026 - Cleaner Review Comments">
    We adjusted the format of Kody's review comments to prevent internal reasoning structures from appearing in the output and to make suggestions more natural, concise, and easier to understand.

    We also fixed issues involving aliases and internal prompt references following recent refactors.
  </Update>

  <Update label="July 13, 2026 - Improved BYOK Support">
    We improved BYOK support across different parts of the product, including configuration, model fallback, and per-model cost calculations.

    We also introduced a clearer experience for viewing BYOK settings and understanding how each model affects token consumption.
  </Update>

  <Update label="July 13, 2026 - More Accurate Cost Tracking and Telemetry">
    We improved the observability of LLM calls to ensure token usage is attributed correctly, especially within the new Kody Rules and agent workflows.

    This increases the accuracy of usage reports and prevents undercounting in more complex review scenarios.
  </Update>

  <Update label="July 13, 2026 - MCP Manager and Plugin Improvements">
    We improved tenant isolation for MCP connections, enhanced connection sorting and testing, and removed legacy integrations that had already been deprecated.

    These changes increase the reliability of the plugins and integrations experience.
  </Update>

  <Update label="July 13, 2026 - Improvements for Self-Hosted Environments">
    We applied fixes to Dockerfiles, provisioning scripts, and local configuration to make self-hosted environments more stable.

    We also fixed an issue involving pnpm on macOS and adjusted the API hostname configuration used during provisioning.
  </Update>

  <Update label="July 13, 2026 - More Stable Observability">
    We fixed excessive memory consumption in the Mongo observability exporter and improved logging behavior across different environments.

    We also removed outdated references to the previous internal framework, simplifying the observability codebase.
  </Update>

  <Update label="July 13, 2026 - New Quality Tests and Validations">
    We added new end-to-end scenarios and evaluations to validate Kody Rules, model recall, suggestion adherence, and prompt regressions.

    These validations help ensure that changes to models, prompts, or the underlying architecture do not reduce review quality.
  </Update>

  <Update label="July 13, 2026 - Updated Documentation">
    We updated the documentation for BYOK, custom messages, and focused reviews. We also revised the README and added new pages explaining how to guide Kody during a review.
  </Update>

  <Update label="July 13, 2026 - Safer Rule Execution">
    We added protections against potentially unsafe regex patterns in Kody Rules detectors. This prevents malformed or computationally expensive rules from affecting review performance. We also fixed cases where outdated detectors could remain associated with a rule after an edit changed the rule's intended behavior.
  </Update>

  <Update label="July 13, 2026 - License and Billing Improvements">
    We fixed issues involving trial creation, the listing of inactive users or users removed from the Git organization, and active seat counts. These changes make the license page more consistent and reduce discrepancies between the organization's actual users and the users displayed in billing.
  </Update>

  <Update label="July 6, 2026 - Steer a review with focus">
    You can now ask Kody to pay special attention to something specific during a review, without changing any configuration.

    In a PR, use @kody review \<directive>. In the CLI, use kodus review --focus.

    Examples: @kody review focus on security. @kody review focus on performance. Or in the CLI: kodus review --focus "edge cases".

    This is especially useful for larger PRs or sensitive changes, where you want the review to go deeper on a specific area, such as security, performance, edge cases, a business rule, or a team standard.

    Focus works as a priority, not a filter. Kody pays closer attention to the context you provide, but still reports other concrete issues it finds in the diff.

    Learn more in the Steer a Review Focus documentation: [https://docs.kodus.io/how\_to\_use/en/code\_review/review\_directive](https://docs.kodus.io/how_to_use/en/code_review/review_directive)
  </Update>

  <Update label="July 6, 2026 - Consolidate LLM prompts into a single comment">
    We added an option to generate a single PR comment containing all prompts and suggestions, so an external agent or AI tool can apply the fixes in one pass.

    Video: [https://kodus.io/wp-content/uploads/2026/07/agent-prompt.mp4](https://kodus.io/wp-content/uploads/2026/07/agent-prompt.mp4)
  </Update>

  <Update label="July 6, 2026 - Select all repositories at once">
    In the add repositories modal, we added select all and clear selection buttons. For teams connecting dozens of repositories, this removes the need to select each one manually and significantly reduces setup time.

    Video: [https://kodus.io/wp-content/uploads/2026/07/add-repo-qa.mp4](https://kodus.io/wp-content/uploads/2026/07/add-repo-qa.mp4)
  </Update>

  <Update label="July 6, 2026 - Cost breakdown by model (BYOK)">
    Teams using Bring Your Own Key now have a detailed view of LLM usage by model on the costs screen. Instead of seeing only the total amount, you can identify exactly which providers and models are driving most of the usage and make clearer decisions about what to keep, replace, or limit.

    Video: [https://kodus.io/wp-content/uploads/2026/07/resumo-de-custos-por-modelo.mp4](https://kodus.io/wp-content/uploads/2026/07/resumo-de-custos-por-modelo.mp4)
  </Update>

  <Update label="July 6, 2026 - Review agent consolidation">
    We reorganized the code review agents to run on a unified infrastructure. Previously, parts of the flow were spread across different places, which could lead to duplicated suggestions and inconsistent behavior. With this consolidation, the pipeline is more predictable, easier to maintain, and less likely to repeat suggestions in the same PR.
  </Update>

  <Update label="July 6, 2026 - Content guard for deduplication">
    We improved the deduplication algorithm so distinct bugs are not grouped as if they were the same issue. The content guard now better considers the actual content of each suggestion, reducing false-positive deduplication and making sure separate issues continue to be reported individually.
  </Update>

  <Update label="July 6, 2026 - Prose findings recovery + Gemini support">
    We fixed unstable behavior in prose finding generation and restored strict mode for Gemini. We also updated the Anthropic SDK, keeping compatibility with newer models and improving response stability.
  </Update>

  <Update label="July 6, 2026 - RBAC documentation">
    We updated the permissions documentation, including the OrganizationSettings scope and the restriction that only the organization Owner can configure BYOK. This makes it clearer who can do what inside the workspace.
  </Update>

  <Update label="July 6, 2026 - Review comments with broken formatting">
    Fixed cases where Kody comments appeared with unexpected formatting in pull requests.
  </Update>

  <Update label="July 6, 2026 - Retry errors with BYOK providers">
    Added preventive adjustments to avoid retry failures when a BYOK provider returns an empty response body.
  </Update>

  <Update label="July 6, 2026 - Sandbox tool errors">
    The agent now handles errors better when running tools in the sandbox environment, without breaking the review.
  </Update>

  <Update label="July 6, 2026 - Normalized user IDs">
    Standardized how author, reviewer, and assignee IDs are handled, preventing PRs from breaking because of type differences, such as string vs. number.
  </Update>

  <Update label="July 6, 2026 - @kody conversation crashing on JSON wrapped in prose">
    Fixed a crash that happened when Kody responded to mentions and the output came back as text containing embedded JSON.
  </Update>

  <Update label="July 6, 2026 - IDE sync config now respects approval settings">
    IDE rule synchronization now respects the approval configuration.
  </Update>

  <Update label="July 6, 2026 - Rules with multiple directories">
    Adjusted Kody Rules validation to correctly handle rules that apply to multiple path groups.
  </Update>

  <Update label="July 6, 2026 - Automatic code review config creation">
    When a repository did not have a code review configuration, creating a Kody Rule could fail silently. The configuration is now created automatically.
  </Update>

  <Update label="July 6, 2026 - Diff re-review in the agent">
    Improved how the agent detects diffs from new commits during re-reviews.
  </Update>

  <Update label="July 6, 2026 - MCP Manager OAuth disconnect">
    Fixed an issue with disconnecting OAuth credentials in MCP Manager that could cause inconsistent behavior.
  </Update>

  <Update label="July 6, 2026 - MCP Manager production build">
    The MCP Manager production build now correctly passes the GitHub token.
  </Update>

  <Update label="July 6, 2026 - Orphaned users in the license list">
    Users removed from the GitHub organization now appear correctly in the license list.
  </Update>

  <Update label="July 6, 2026 - Skipped review email">
    The notification email sent when a review is skipped now includes the author's name/email and no longer breaks when the user does not have a license.
  </Update>

  <Update label="June 29, 2026 - Validated review engine">
    We updated Kody's review pipeline to improve analysis accuracy and reduce cases where important issues could slip through unnoticed.

    The engine now identifies problematic patterns more effectively, better understands changes that span multiple files, and can review code regions with more flexibility when the context is not fully obvious.

    We also optimized processing and reduced the average cost per review by around 30%.
  </Update>

  <Update label="June 29, 2026 - Shareable dashboard views">
    Filters applied in Cockpit are now saved in the URL, including time range, repositories, severity, and status.

    This means you can copy the link and share it with your team on Slack, for example. Anyone who opens the URL will see Cockpit with the same filters applied, without having to manually recreate the view.

    This makes it easier to share specific analyses, such as what changed over the past week or an increase in security suggestions in a repository.

    Video: [https://kodus.io/wp-content/uploads/2026/06/kodus-copy-url.mp4](https://kodus.io/wp-content/uploads/2026/06/kodus-copy-url.mp4)
  </Update>

  <Update label="June 29, 2026 - Unified Kody Rules lifecycle">
    We unified the Kody Rules flow into a single lifecycle, regardless of where the rule was created: the library, manual creation, or inheritance from the organization to the repository.

    With this change, activating, editing, disabling, and approving rules now follow the same path inside the product. We also migrated older rules to the new format and centralized the control of rules pending approval.

    This makes the system more consistent, reduces unexpected states, and ensures that an active rule is actually applied in Kody reviews.
  </Update>

  <Update label="June 29, 2026 - Migrate away from Composio">
    We removed the dependency on Composio as an external MCP broker and moved to our own implementation for GitHub Issues, now integrated with Kodus Issues.

    This reduces an external point of failure, improves call reliability, and gives us more control over authentication, rate limits, and retries.

    As part of the migration, we also removed low-usage integrations that depended on Composio, such as ClickUp and CloudId.
  </Update>

  <Update label="June 29, 2026 - Inheritance toggle">
    When you enable or disable rule inheritance from the organization to a repository, the UI now shows the new state immediately, without waiting for the API response.

    If the call fails, for example because of a connection issue, the state is automatically reverted and we show an error toast. Before, users would click, wait, and not get clear feedback about what had happened.

    We also improved the rules cache update. Now we only invalidate the rules affected by that inheritance change, avoiding unnecessary reloads for rules that did not change.
  </Update>

  <Update label="June 29, 2026 - Kody Rules Origin">
    We added an explicit origin to all Kody Rules: LIBRARY, MANUAL, INHERITED, and SUGGESTED.

    This fixes an issue where some rule creation scenarios could fail silently because the backend expected an origin value that the frontend was not sending.

    Now the contract between frontend and backend is clearer, and the rule origin is validated before reaching the creation flow.
  </Update>

  <Update label="June 29, 2026 - Atlassian Rovo">
    Rovo is an Atlassian AI agent that generates code and edits files automatically. When it creates commits, it includes specific metadata, such as message prefixes and custom headers.

    Previously, our review engine identified those commits as human-written code and could suggest changes on them.

    Now we detect Rovo commits and skip those changes both in the code review logic and in the MCP business-rule validation preflight.
  </Update>

  <Update label="June 29, 2026 - MCP OAuth callback">
    We fixed the OAuth flow for connecting MCPs, such as GitHub and Jira.

    Previously, users who had already completed onboarding could be blocked when trying to add a new MCP. Now the callback works at any time, as long as the state parameter is valid.
  </Update>

  <Update label="June 29, 2026 - Pending rules section">
    Pending rules, which need approval before entering the review pipeline, now have a dedicated section with improved UX.

    The section shows a status badge, who suggested the rule, when it was suggested, and inline actions to approve or reject it.

    Previously, these rules appeared mixed together with active rules, which made it easy to miss that something needed attention.
  </Update>

  <Update label="June 29, 2026 - GitHub Integration GitHub App post-onboarding">
    We fixed an issue where some GitHub integration pages returned a 404 after the user completed onboarding. This affected routes such as /github/integration and /github/organization-name when the GitHub App installation state was not updated correctly. We also adjusted the redirect after installation and added route validations to make the integration flow more reliable across different states.
  </Update>

  <Update label="June 29, 2026 - Severity slicer colors">
    The severity control for low, medium, high, and critical used inconsistent colors. In some places, red meant critical; in others, it meant high. We standardized it to a semantic scale: gray for low, yellow for medium, orange for high, and red for critical. This affects Cockpit filters, suggestion badges, and notification settings.
  </Update>

  <Update label="June 22, 2026 - Forgejo support is now on par with GitHub & GitLab">
    Review comments, commit statuses, force-push detection, and webhook coverage now work consistently for Forgejo repositories. If you self-host with Forgejo, Kody behaves just like on any other major platform.
  </Update>

  <Update label="June 22, 2026 - Faster PR closing for large repos">
    Eliminated duplicate API calls when syncing Kody Rules from changed files. PRs with many files now close noticeably faster.
  </Update>

  <Update label="June 22, 2026 - Cleaner settings UI">
    Platform settings that don't apply to your current Git provider, such as GitHub-specific options when you're on GitLab, are now hidden automatically. Less clutter, fewer misconfigurations.
  </Update>

  <Update label="June 22, 2026 - Reconnecting a Git provider after disconnecting">
    Previously, disconnecting a provider left stale integration configs behind, causing reconnects to fail. Now stale rows are properly cleaned up.
  </Update>

  <Update label="June 22, 2026 - Kody conversation replies with empty responses">
    Resolved an issue where Kody occasionally replied with blank content in PR comment threads when using Claude Sonnet.
  </Update>

  <Update label="June 22, 2026 - NaN deduplication indices">
    Added three-layer protection against NaN values appearing in suggestion deduplication indices, preventing rare but confusing duplicate suggestions.
  </Update>

  <Update label="June 22, 2026 - Forgejo prompt field always empty">
    The formatPromptForLLM function was reading a non-existent field on Forgejo PRs, causing the prompt section to be blank. Now it reads the correct field.
  </Update>

  <Update label="June 22, 2026 - Self-hosted AST graph reliability">
    The kodus-graph CLI was installed but not available to the runtime user in self-hosted worker images. Fixed PATH and install order so graph indexing works out of the box.
  </Update>

  <Update label="June 22, 2026 - Orphaned agent trace records">
    Prevented a race condition in chunked review mode that could leave orphaned IN\_PROGRESS trace records in the database.
  </Update>

  <Update label="June 22, 2026 - Platform settings not scoped to Git tool">
    Settings incompatible with your current Git provider were still visible. Now they're properly filtered based on the connected tool.
  </Update>

  <Update label="June 15, 2026 - Operational metrics in Cockpit">
    Track the health of your review pipeline in real time. Throughput, queue, and processing time metrics are now available in Cockpit.

    Video: [https://kodus.io/wp-content/uploads/2026/06/cockpit.mp4](https://kodus.io/wp-content/uploads/2026/06/cockpit.mp4)
  </Update>

  <Update label="June 15, 2026 - Redesigned Kodus Review tab">
    The review tab has been redesigned with a cleaner interface and more direct actions. You can now analyze and act on suggestions without leaving the PR screen.

    Video: [https://kodus.io/wp-content/uploads/2026/06/kody-review-tab.mp4](https://kodus.io/wp-content/uploads/2026/06/kody-review-tab.mp4)
  </Update>

  <Update label="June 15, 2026 - Backend on pnpm">
    We migrated the backend from Yarn 1 to pnpm. This makes builds faster, improves lockfile consistency, and reduces cache issues across environments.
  </Update>

  <Update label="June 15, 2026 - Token usage screen">
    The token usage screen has been redesigned to make consumption by organization and period easier to understand. It is now simpler to track usage and see how tokens are being consumed over time.

    Video: [https://kodus.io/wp-content/uploads/2026/06/token\_usage.mp4](https://kodus.io/wp-content/uploads/2026/06/token_usage.mp4)
  </Update>

  <Update label="June 15, 2026 - Self-hosted analytics">
    We fixed the analytics integration for self-hosted deployments. Usage metrics now appear correctly in the dashboard.
  </Update>

  <Update label="June 15, 2026 - Issue cache">
    The issue count in the sidebar could sometimes become outdated. The cache is now invalidated correctly after changes.
  </Update>

  <Update label="June 15, 2026 - GitHub rate limit">
    We fixed a rate limit issue in cloud E2E tests. We now use round-robin across multiple bot accounts to better distribute requests.
  </Update>

  <Update label="June 15, 2026 - Notification routing">
    We fixed the behavior of targeted notifications when combined with audience settings. Notifications now reach the right people without duplicates.
  </Update>

  <Update label="June 15, 2026 - Centralized config sync">
    We fixed issues in the centralized sync of Kody Rules configurations across repositories. Sync now correctly handles multiple scopes, stale configurations, and merge-triggered updates.
  </Update>

  <Update label="June 8, 2026 - Moonshot Kimi support for BYOK">
    We added support for Moonshot as a provider, compatible with the Anthropic API.

    You can now use the Kimi Coding Plan model in BYOK setups. To configure it, set the API\_MOONSHOT\_API\_KEY key and select the model in the organization preferences.

    See the Moonshot Kimi documentation for more setup details: [https://docs.kodus.io/knowledge\_base/en/how-to-use-moonshot-with-kodus](https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus)
  </Update>

  <Update label="June 8, 2026 - Monthly token usage control">
    Organizations can now set monthly token consumption limits per model.

    Usage is shown in real time in the interface, with a progress bar. When usage reaches 80% of the limit, the team receives an email alert. If the limit is reached, additional reviews can be blocked automatically.

    Video: [https://kodus.io/wp-content/uploads/2026/06/token-usage.mov](https://kodus.io/wp-content/uploads/2026/06/token-usage.mov)

    See the Monthly Spend Limit documentation for more setup details: [https://docs.kodus.io/how\_to\_use/en/spend-limit](https://docs.kodus.io/how_to_use/en/spend-limit)
  </Update>

  <Update label="June 8, 2026 - More resilient review agent">
    The review engine now handles empty or malformed LLM responses better. This reduces loops in edge cases and helps ensure valid suggestions continue to be delivered even when the provider returns an unexpected response.
  </Update>

  <Update label="June 8, 2026 - Telemetry for self-hosted environments">
    On-premise installations now automatically report health metrics, such as heartbeat, and usage data. The goal is to make diagnosis and support easier without exposing sensitive customer data.
  </Update>

  <Update label="June 8, 2026 - Faster Kody Rules">
    We improved the loading and synchronization of custom rules. We also fixed the count of orphaned rules and made partial updates safer against race conditions.
  </Update>

  <Update label="June 8, 2026 - GitLab compatibility improvements">
    Support for GitLab 13.x in comment webhooks.

    Diff fallback for versions earlier than 15.7.

    Fixes for discussion threads and replies scoped by discussionId.

    Self-hosted development environment documentation.
  </Update>

  <Update label="June 8, 2026 - GitHub member list fix">
    Suspended users no longer appear in the member list for license assignment.
  </Update>

  <Update label="June 8, 2026 - Update Connection fix">
    Integration reauthentication now correctly clears the previous configuration.
  </Update>

  <Update label="June 8, 2026 - Integration reset fix">
    Kody Rules linked to the repo or directory are now removed automatically.
  </Update>

  <Update label="June 8, 2026 - Release Freeze fix">
    Eligibility notifications only appear when the freeze is active.
  </Update>
</div>


# Changelog
Source: https://docs.kodus.io/changelog/index

Latest Kodus updates and improvements.

<div>
  <div>
    <div aria-label="Changelog filters">
      <p>Filters</p>

      <div>
        <label>
          <input type="checkbox" />

          <span>Security</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Cockpit</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>BYOK</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>AI Engine</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Self-hosted</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>GIT Provider</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Performance</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>UX & Interface</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Notifications</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Kody Rules</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>MCP</span>
        </label>

        <label>
          <input type="checkbox" />

          <span>Billing & Licenses</span>
        </label>
      </div>
    </div>
  </div>

  <div>
    <div>
      <span>July 13, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>New Token Usage Experience</div>
          <p>The Token Usage page has been redesigned to provide a more complete view of consumption.</p>
          <p>It is now easier to track costs by area, model, and review activity, as well as filter the data and drill down into more specific analyses. This helps teams better understand where tokens are being used and how they can optimize costs.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Automatic Detector Backfill for Existing Rules</div>
          <p>Organizations that created Kody Rules before this release can also benefit from the new architecture. We created an automated process that analyzes existing rules and, whenever possible, generates mechanical detectors for them.</p>
          <p>The process is incremental, safe, and does not interfere with the normal execution of rules. When a rule cannot be converted into a detector, it continues to work through the traditional semantic review flow.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>More Accurate and Predictable Kody Rules</div>
          <p>We restructured how Kody applies custom rules during code reviews. Instead of relying solely on a more open-ended agent analysis, rules are now evaluated deterministically by file and PR scope.</p>
          <p>In practice, this improves rule coverage in large PRs, reduces cases where an applicable rule is overlooked, and makes Kody Rules behave more consistently across different models.</p>
          <p>We also introduced mechanical detectors for certain rules. When a rule can safely be converted into an objective check, Kody can apply it without making an LLM call, reducing costs and improving predictability.</p>
        </div>

        <div>
          <div>Code Review Engine Improvements</div>
          <p>This release includes a major upgrade to the review agent runtime. We migrated important parts of the execution flow to a new agent harness foundation, making the system more modular, observable, and ready for future improvements.</p>
          <p>We also improved the engine used to search for evidence in the codebase, with a focus on finding more relevant cross-file references and increasing the quality of generated suggestions.</p>
        </div>

        <div>
          <div>Cleaner Review Comments</div>
          <p>We adjusted the format of Kody's review comments to prevent internal reasoning structures from appearing in the output and to make suggestions more natural, concise, and easier to understand.</p>
          <p>We also fixed issues involving aliases and internal prompt references following recent refactors.</p>
        </div>

        <div>
          <div>Improved BYOK Support</div>
          <p>We improved BYOK support across different parts of the product, including configuration, model fallback, and per-model cost calculations.</p>
          <p>We also introduced a clearer experience for viewing BYOK settings and understanding how each model affects token consumption.</p>
        </div>

        <div>
          <div>More Accurate Cost Tracking and Telemetry</div>
          <p>We improved the observability of LLM calls to ensure token usage is attributed correctly, especially within the new Kody Rules and agent workflows.</p>
          <p>This increases the accuracy of usage reports and prevents undercounting in more complex review scenarios.</p>
        </div>

        <div>
          <div>MCP Manager and Plugin Improvements</div>
          <p>We improved tenant isolation for MCP connections, enhanced connection sorting and testing, and removed legacy integrations that had already been deprecated.</p>
          <p>These changes increase the reliability of the plugins and integrations experience.</p>
        </div>

        <div>
          <div>Improvements for Self-Hosted Environments</div>
          <p>We applied fixes to Dockerfiles, provisioning scripts, and local configuration to make self-hosted environments more stable.</p>
          <p>We also fixed an issue involving pnpm on macOS and adjusted the API hostname configuration used during provisioning.</p>
        </div>

        <div>
          <div>More Stable Observability</div>
          <p>We fixed excessive memory consumption in the Mongo observability exporter and improved logging behavior across different environments.</p>
          <p>We also removed outdated references to the previous internal framework, simplifying the observability codebase.</p>
        </div>

        <div>
          <div>New Quality Tests and Validations</div>
          <p>We added new end-to-end scenarios and evaluations to validate Kody Rules, model recall, suggestion adherence, and prompt regressions.</p>
          <p>These validations help ensure that changes to models, prompts, or the underlying architecture do not reduce review quality.</p>
        </div>

        <div>
          <div>Updated Documentation</div>
          <p>We updated the documentation for BYOK, custom messages, and focused reviews. We also revised the README and added new pages explaining how to guide Kody during a review.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Safer Rule Execution:</strong> we added protections against potentially unsafe regex patterns in Kody Rules detectors. This prevents malformed or computationally expensive rules from affecting review performance. We also fixed cases where outdated detectors could remain associated with a rule after an edit changed the rule's intended behavior.</p>
          </div>

          <div>
            <p><strong>License and Billing Improvements:</strong> we fixed issues involving trial creation, the listing of inactive users or users removed from the Git organization, and active seat counts. These changes make the license page more consistent and reduce discrepancies between the organization's actual users and the users displayed in billing.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>July 6, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Steer a review with focus</div>
          <p>You can now ask Kody to pay special attention to something specific during a review, without changing any configuration.</p>
          <p>In a PR, use <code>@kody review \<directive></code>. In the CLI, use <code>kodus review --focus</code>.</p>
          <p>Examples:</p>

          <ul>
            <li><code>@kody review focus on security</code></li>
            <li><code>@kody review focus on performance</code></li>
            <li><code>kodus review --focus "edge cases"</code></li>
          </ul>

          <p>This is especially useful for larger PRs or sensitive changes, where you want the review to go deeper on a specific area, such as security, performance, edge cases, a business rule, or a team standard.</p>
          <p>Focus works as a priority, not a filter. Kody pays closer attention to the context you provide, but still reports other concrete issues it finds in the diff.</p>
          <p>Learn more in the <a href="https://docs.kodus.io/how_to_use/en/code_review/review_directive">Steer a Review (Focus)</a> documentation.</p>
        </div>

        <div>
          <div>Consolidate LLM prompts into a single comment</div>
          <p>We added an option to generate a single PR comment containing all prompts and suggestions, so an external agent or AI tool can apply the fixes in one pass.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Select all repositories at once</div>
          <p>In the add repositories modal, we added <strong>select all</strong> and <strong>clear selection</strong> buttons. For teams connecting dozens of repositories, this removes the need to select each one manually and significantly reduces setup time.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Cost breakdown by model (BYOK)</div>
          <p>Teams using Bring Your Own Key now have a detailed view of LLM usage by model on the costs screen. Instead of seeing only the total amount, you can identify exactly which providers and models are driving most of the usage and make clearer decisions about what to keep, replace, or limit.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Review agent consolidation</div>
          <p>We reorganized the code review agents to run on a unified infrastructure. Previously, parts of the flow were spread across different places, which could lead to duplicated suggestions and inconsistent behavior. With this consolidation, the pipeline is more predictable, easier to maintain, and less likely to repeat suggestions in the same PR.</p>
        </div>

        <div>
          <div>Content guard for deduplication</div>
          <p>We improved the deduplication algorithm so distinct bugs are not grouped as if they were the same issue. The content guard now better considers the actual content of each suggestion, reducing false-positive deduplication and making sure separate issues continue to be reported individually.</p>
        </div>

        <div>
          <div>Prose findings recovery + Gemini support</div>
          <p>We fixed unstable behavior in prose finding generation and restored strict mode for Gemini. We also updated the Anthropic SDK, keeping compatibility with newer models and improving response stability.</p>
        </div>

        <div>
          <div>RBAC documentation</div>
          <p>We updated the permissions documentation, including the <code>OrganizationSettings</code> scope and the restriction that only the organization Owner can configure BYOK. This makes it clearer who can do what inside the workspace.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Review comments with broken formatting:</strong> fixed cases where Kody comments appeared with unexpected formatting in pull requests.</p>
          </div>

          <div>
            <p><strong>Retry errors with BYOK providers:</strong> added preventive adjustments to avoid retry failures when a BYOK provider returns an empty response body.</p>
          </div>

          <div>
            <p><strong>Sandbox tool errors:</strong> the agent now handles errors better when running tools in the sandbox environment, without breaking the review.</p>
          </div>

          <div>
            <p><strong>Normalized user IDs:</strong> standardized how author, reviewer, and assignee IDs are handled, preventing PRs from breaking because of type differences, such as string vs. number.</p>
          </div>

          <div>
            <p><strong>@kody conversation crashing on JSON wrapped in prose:</strong> fixed a crash that happened when Kody responded to mentions and the output came back as text containing embedded JSON.</p>
          </div>

          <div>
            <p><strong>IDE sync config now respects approval settings:</strong> IDE rule synchronization now respects the approval configuration.</p>
          </div>

          <div>
            <p><strong>Rules with multiple directories:</strong> adjusted Kody Rules validation to correctly handle rules that apply to multiple path groups.</p>
          </div>

          <div>
            <p><strong>Automatic code review config creation:</strong> when a repository did not have a code review configuration, creating a Kody Rule could fail silently. The configuration is now created automatically.</p>
          </div>

          <div>
            <p><strong>Diff re-review in the agent:</strong> improved how the agent detects diffs from new commits during re-reviews.</p>
          </div>

          <div>
            <p><strong>MCP Manager OAuth disconnect:</strong> fixed an issue with disconnecting OAuth credentials in MCP Manager that could cause inconsistent behavior.</p>
          </div>

          <div>
            <p><strong>MCP Manager production build:</strong> the MCP Manager production build now correctly passes the GitHub token.</p>
          </div>

          <div>
            <p><strong>Orphaned users in the license list:</strong> users removed from the GitHub organization now appear correctly in the license list.</p>
          </div>

          <div>
            <p><strong>Skipped review email:</strong> the notification email sent when a review is skipped now includes the author's name/email and no longer breaks when the user does not have a license.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 29, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Validated review engine</div>
          <p>We updated Kody's review pipeline to improve analysis accuracy and reduce cases where important issues could slip through unnoticed.</p>
          <p>The engine now identifies problematic patterns more effectively, better understands changes that span multiple files, and can review code regions with more flexibility when the context is not fully obvious.</p>
          <p>We also optimized processing and reduced the average cost per review by around 30%.</p>
        </div>

        <div>
          <div>Shareable dashboard views</div>
          <p>Filters applied in Cockpit are now saved in the URL, including time range, repositories, severity, and status.</p>
          <p>This means you can copy the link and share it with your team on Slack, for example. Anyone who opens the URL will see Cockpit with the same filters applied, without having to manually recreate the view.</p>
          <p>This makes it easier to share specific analyses, such as what changed over the past week or an increase in security suggestions in a repository.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Unified Kody Rules lifecycle</div>
          <p>We unified the Kody Rules flow into a single lifecycle, regardless of where the rule was created: the library, manual creation, or inheritance from the organization to the repository.</p>
          <p>With this change, activating, editing, disabling, and approving rules now follow the same path inside the product. We also migrated older rules to the new format and centralized the control of rules pending approval.</p>
          <p>This makes the system more consistent, reduces unexpected states, and ensures that an active rule is actually applied in Kody reviews.</p>
        </div>

        <div>
          <div>Migrate away from Composio</div>
          <p>We removed the dependency on Composio as an external MCP broker and moved to our own implementation for GitHub Issues, now integrated with Kodus Issues.</p>
          <p>This reduces an external point of failure, improves call reliability, and gives us more control over authentication, rate limits, and retries.</p>
          <p>As part of the migration, we also removed low-usage integrations that depended on Composio, such as ClickUp and CloudId.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Inheritance toggle</div>
          <p>When you enable or disable rule inheritance from the organization to a repository, the UI now shows the new state immediately, without waiting for the API response.</p>
          <p>If the call fails, for example because of a connection issue, the state is automatically reverted and we show an error toast. Before, users would click, wait, and not get clear feedback about what had happened.</p>
          <p>We also improved the rules cache update. Now we only invalidate the rules affected by that inheritance change, avoiding unnecessary reloads for rules that did not change.</p>
        </div>

        <div>
          <div>Kody Rules Origin</div>
          <p>We added an explicit origin to all Kody Rules: <code>LIBRARY</code>, <code>MANUAL</code>, <code>INHERITED</code>, and <code>SUGGESTED</code>.</p>
          <p>This fixes an issue where some rule creation scenarios could fail silently because the backend expected an origin value that the frontend was not sending.</p>
          <p>Now the contract between frontend and backend is clearer, and the rule origin is validated before reaching the creation flow.</p>
        </div>

        <div>
          <div>Atlassian Rovo</div>
          <p>Rovo is an Atlassian AI agent that generates code and edits files automatically. When it creates commits, it includes specific metadata, such as message prefixes and custom headers.</p>
          <p>Previously, our review engine identified those commits as human-written code and could suggest changes on them.</p>
          <p>Now we detect Rovo commits and skip those changes both in the code review logic and in the MCP business-rule validation preflight.</p>
        </div>

        <div>
          <div>MCP OAuth callback</div>
          <p>We fixed the OAuth flow for connecting MCPs, such as GitHub and Jira.</p>
          <p>Previously, users who had already completed onboarding could be blocked when trying to add a new MCP. Now the callback works at any time, as long as the state parameter is valid.</p>
        </div>

        <div>
          <div>Pending rules section</div>
          <p>Pending rules, which need approval before entering the review pipeline, now have a dedicated section with improved UX.</p>
          <p>The section shows a status badge, who suggested the rule, when it was suggested, and inline actions to approve or reject it.</p>
          <p>Previously, these rules appeared mixed together with active rules, which made it easy to miss that something needed attention.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>GitHub Integration GitHub App post-onboarding:</strong> we fixed an issue where some GitHub integration pages returned a 404 after the user completed onboarding. This affected routes such as <code>/github/integration</code> and <code>/github/organization-name</code> when the GitHub App installation state was not updated correctly. We also adjusted the redirect after installation and added route validations to make the integration flow more reliable across different states.</p>
          </div>

          <div>
            <p><strong>Severity slicer colors:</strong> the severity control for low, medium, high, and critical used inconsistent colors. In some places, red meant critical; in others, it meant high. We standardized it to a semantic scale: gray for low, yellow for medium, orange for high, and red for critical. This affects Cockpit filters, suggestion badges, and notification settings.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 22, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Forgejo support is now on par with GitHub & GitLab</div>
          <p>Review comments, commit statuses, force-push detection, and webhook coverage now work consistently for Forgejo repositories. If you self-host with Forgejo, Kody behaves just like on any other major platform.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Faster PR closing for large repos</div>
          <p>Eliminated duplicate API calls when syncing Kody Rules from changed files. PRs with many files now close noticeably faster.</p>
        </div>

        <div>
          <div>Cleaner settings UI</div>
          <p>Platform settings that don't apply to your current Git provider, such as GitHub-specific options when you're on GitLab, are now hidden automatically. Less clutter, fewer misconfigurations.</p>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Reconnecting a Git provider after disconnecting:</strong> previously, disconnecting a provider left stale integration configs behind, causing reconnects to fail. Now stale rows are properly cleaned up.</p>
          </div>

          <div>
            <p><strong>Kody conversation replies with empty responses:</strong> resolved an issue where Kody occasionally replied with blank content in PR comment threads when using Claude Sonnet.</p>
          </div>

          <div>
            <p><strong>NaN deduplication indices:</strong> added three-layer protection against NaN values appearing in suggestion deduplication indices, preventing rare but confusing duplicate suggestions.</p>
          </div>

          <div>
            <p><strong>Forgejo prompt field always empty:</strong> the formatPromptForLLM function was reading a non-existent field on Forgejo PRs, causing the prompt section to be blank. Now it reads the correct field.</p>
          </div>

          <div>
            <p><strong>Self-hosted AST graph reliability:</strong> the kodus-graph CLI was installed but not available to the runtime user in self-hosted worker images. Fixed PATH and install order so graph indexing works out of the box.</p>
          </div>

          <div>
            <p><strong>Orphaned agent trace records:</strong> prevented a race condition in chunked review mode that could leave orphaned <code>IN\_PROGRESS</code> trace records in the database.</p>
          </div>

          <div>
            <p><strong>Platform settings not scoped to Git tool:</strong> settings incompatible with your current Git provider were still visible. Now they're properly filtered based on the connected tool.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 15, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Operational metrics in Cockpit</div>
          <p>Track the health of your review pipeline in real time. Throughput, queue, and processing time metrics are now available in Cockpit.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>

        <div>
          <div>Redesigned Kodus Review tab</div>
          <p>The review tab has been redesigned with a cleaner interface and more direct actions. You can now analyze and act on suggestions without leaving the PR screen.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>Backend on pnpm</div>
          <p>We migrated the backend from Yarn 1 to pnpm. This makes builds faster, improves lockfile consistency, and reduces cache issues across environments.</p>
        </div>

        <div>
          <div>Token usage screen</div>
          <p>The token usage screen has been redesigned to make consumption by organization and period easier to understand. It is now simpler to track usage and see how tokens are being consumed over time.</p>

          <video>
            <source type="video/mp4" />
          </video>
        </div>
      </div>

      <div>
        <div>Bug fixes</div>

        <div>
          <div>
            <p><strong>Self-hosted analytics:</strong> we fixed the analytics integration for self-hosted deployments. Usage metrics now appear correctly in the dashboard.</p>
          </div>

          <div>
            <p><strong>Issue cache:</strong> the issue count in the sidebar could sometimes become outdated. The cache is now invalidated correctly after changes.</p>
          </div>

          <div>
            <p><strong>GitHub rate limit:</strong> we fixed a rate limit issue in cloud E2E tests. We now use round-robin across multiple bot accounts to better distribute requests.</p>
          </div>

          <div>
            <p><strong>Notification routing:</strong> we fixed the behavior of targeted notifications when combined with audience settings. Notifications now reach the right people without duplicates.</p>
          </div>

          <div>
            <p><strong>Centralized config sync:</strong> we fixed issues in the centralized sync of Kody Rules configurations across repositories. Sync now correctly handles multiple scopes, stale configurations, and merge-triggered updates.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>

  <div>
    <div>
      <span>June 8, 2026</span>
    </div>

    <div>
      <div>
        <div>What's new</div>

        <div>
          <div>Moonshot Kimi support for BYOK</div>
          <p>We added support for Moonshot as a provider, compatible with the Anthropic API.</p>
          <p>You can now use the Kimi Coding Plan model in BYOK setups. To configure it, set the <code>API\_MOONSHOT\_API\_KEY</code> key and select the model in the organization preferences.</p>
          <p>See the <a href="https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus">Moonshot (Kimi)</a> documentation for more setup details.</p>
        </div>

        <div>
          <div>Monthly token usage control</div>
          <p>Organizations can now set monthly token consumption limits per model.</p>
          <p>Usage is shown in real time in the interface, with a progress bar. When usage reaches 80% of the limit, the team receives an email alert. If the limit is reached, additional reviews can be blocked automatically.</p>

          <video>
            <source type="video/mp4" />
          </video>

          <p>See the <a href="https://docs.kodus.io/how_to_use/en/spend-limit">Monthly Spend Limit</a> documentation for more setup details.</p>
        </div>
      </div>

      <div>
        <div>Improvements</div>

        <div>
          <div>More resilient review agent</div>
          <p>The review engine now handles empty or malformed LLM responses better.</p>
          <p>This reduces loops in edge cases and helps ensure valid suggestions continue to be delivered even when the provider returns an unexpected response.</p>
        </div>

        <div>
          <div>Telemetry for self-hosted environments</div>
          <p>On-premise installations now automatically report health metrics, such as heartbeat, and usage data.</p>
          <p>The goal is to make diagnosis and support easier without exposing sensitive customer data.</p>
        </div>

        <div>
          <div>Faster Kody Rules</div>
          <p>We improved the loading and synchronization of custom rules.</p>
          <p>We also fixed the count of orphaned rules and made partial updates safer against race conditions.</p>
        </div>

        <div>
          <div>GitLab compatibility improvements</div>

          <ul>
            <li>Support for GitLab 13.x in comment webhooks</li>
            <li>Diff fallback for versions earlier than 15.7</li>
            <li>Fixes for discussion threads and replies scoped by discussionId</li>
            <li>Self-hosted development environment documentation</li>
          </ul>
        </div>
      </div>

      <div>
        <div>Fixes</div>

        <div>
          <div>
            <p><strong>GitHub:</strong> suspended users no longer appear in the member list for license assignment.</p>
          </div>

          <div>
            <p><strong>Update Connection:</strong> integration reauthentication now correctly clears the previous configuration.</p>
          </div>

          <div>
            <p><strong>Integration reset:</strong> Kody Rules linked to the repo/directory are now removed automatically.</p>
          </div>

          <div>
            <p><strong>Release Freeze:</strong> eligibility notifications only appear when the freeze is active.</p>
          </div>
        </div>
      </div>

      <p>No changelog entries for this filter yet.</p>
    </div>
  </div>
</div>

<div>
  <Update label="July 13, 2026 - New Token Usage Experience">
    The Token Usage page has been redesigned to provide a more complete view of consumption.

    It is now easier to track costs by area, model, and review activity, as well as filter the data and drill down into more specific analyses. This helps teams better understand where tokens are being used and how they can optimize costs.

    Video: [https://kodus.io/wp-content/uploads/2026/07/new-experience-token-usage.mp4](https://kodus.io/wp-content/uploads/2026/07/new-experience-token-usage.mp4)
  </Update>

  <Update label="July 13, 2026 - Automatic Detector Backfill for Existing Rules">
    Organizations that created Kody Rules before this release can also benefit from the new architecture. We created an automated process that analyzes existing rules and, whenever possible, generates mechanical detectors for them.

    The process is incremental, safe, and does not interfere with the normal execution of rules. When a rule cannot be converted into a detector, it continues to work through the traditional semantic review flow.
  </Update>

  <Update label="July 13, 2026 - More Accurate and Predictable Kody Rules">
    We restructured how Kody applies custom rules during code reviews. Instead of relying solely on a more open-ended agent analysis, rules are now evaluated deterministically by file and PR scope.

    In practice, this improves rule coverage in large PRs, reduces cases where an applicable rule is overlooked, and makes Kody Rules behave more consistently across different models.

    We also introduced mechanical detectors for certain rules. When a rule can safely be converted into an objective check, Kody can apply it without making an LLM call, reducing costs and improving predictability.
  </Update>

  <Update label="July 13, 2026 - Code Review Engine Improvements">
    This release includes a major upgrade to the review agent runtime. We migrated important parts of the execution flow to a new agent harness foundation, making the system more modular, observable, and ready for future improvements.

    We also improved the engine used to search for evidence in the codebase, with a focus on finding more relevant cross-file references and increasing the quality of generated suggestions.
  </Update>

  <Update label="July 13, 2026 - Cleaner Review Comments">
    We adjusted the format of Kody's review comments to prevent internal reasoning structures from appearing in the output and to make suggestions more natural, concise, and easier to understand.

    We also fixed issues involving aliases and internal prompt references following recent refactors.
  </Update>

  <Update label="July 13, 2026 - Improved BYOK Support">
    We improved BYOK support across different parts of the product, including configuration, model fallback, and per-model cost calculations.

    We also introduced a clearer experience for viewing BYOK settings and understanding how each model affects token consumption.
  </Update>

  <Update label="July 13, 2026 - More Accurate Cost Tracking and Telemetry">
    We improved the observability of LLM calls to ensure token usage is attributed correctly, especially within the new Kody Rules and agent workflows.

    This increases the accuracy of usage reports and prevents undercounting in more complex review scenarios.
  </Update>

  <Update label="July 13, 2026 - MCP Manager and Plugin Improvements">
    We improved tenant isolation for MCP connections, enhanced connection sorting and testing, and removed legacy integrations that had already been deprecated.

    These changes increase the reliability of the plugins and integrations experience.
  </Update>

  <Update label="July 13, 2026 - Improvements for Self-Hosted Environments">
    We applied fixes to Dockerfiles, provisioning scripts, and local configuration to make self-hosted environments more stable.

    We also fixed an issue involving pnpm on macOS and adjusted the API hostname configuration used during provisioning.
  </Update>

  <Update label="July 13, 2026 - More Stable Observability">
    We fixed excessive memory consumption in the Mongo observability exporter and improved logging behavior across different environments.

    We also removed outdated references to the previous internal framework, simplifying the observability codebase.
  </Update>

  <Update label="July 13, 2026 - New Quality Tests and Validations">
    We added new end-to-end scenarios and evaluations to validate Kody Rules, model recall, suggestion adherence, and prompt regressions.

    These validations help ensure that changes to models, prompts, or the underlying architecture do not reduce review quality.
  </Update>

  <Update label="July 13, 2026 - Updated Documentation">
    We updated the documentation for BYOK, custom messages, and focused reviews. We also revised the README and added new pages explaining how to guide Kody during a review.
  </Update>

  <Update label="July 13, 2026 - Safer Rule Execution">
    We added protections against potentially unsafe regex patterns in Kody Rules detectors. This prevents malformed or computationally expensive rules from affecting review performance. We also fixed cases where outdated detectors could remain associated with a rule after an edit changed the rule's intended behavior.
  </Update>

  <Update label="July 13, 2026 - License and Billing Improvements">
    We fixed issues involving trial creation, the listing of inactive users or users removed from the Git organization, and active seat counts. These changes make the license page more consistent and reduce discrepancies between the organization's actual users and the users displayed in billing.
  </Update>

  <Update label="July 6, 2026 - Steer a review with focus">
    You can now ask Kody to pay special attention to something specific during a review, without changing any configuration.

    In a PR, use @kody review \<directive>. In the CLI, use kodus review --focus.

    Examples: @kody review focus on security. @kody review focus on performance. Or in the CLI: kodus review --focus "edge cases".

    This is especially useful for larger PRs or sensitive changes, where you want the review to go deeper on a specific area, such as security, performance, edge cases, a business rule, or a team standard.

    Focus works as a priority, not a filter. Kody pays closer attention to the context you provide, but still reports other concrete issues it finds in the diff.

    Learn more in the Steer a Review Focus documentation: [https://docs.kodus.io/how\_to\_use/en/code\_review/review\_directive](https://docs.kodus.io/how_to_use/en/code_review/review_directive)
  </Update>

  <Update label="July 6, 2026 - Consolidate LLM prompts into a single comment">
    We added an option to generate a single PR comment containing all prompts and suggestions, so an external agent or AI tool can apply the fixes in one pass.

    Video: [https://kodus.io/wp-content/uploads/2026/07/agent-prompt.mp4](https://kodus.io/wp-content/uploads/2026/07/agent-prompt.mp4)
  </Update>

  <Update label="July 6, 2026 - Select all repositories at once">
    In the add repositories modal, we added select all and clear selection buttons. For teams connecting dozens of repositories, this removes the need to select each one manually and significantly reduces setup time.

    Video: [https://kodus.io/wp-content/uploads/2026/07/add-repo-qa.mp4](https://kodus.io/wp-content/uploads/2026/07/add-repo-qa.mp4)
  </Update>

  <Update label="July 6, 2026 - Cost breakdown by model (BYOK)">
    Teams using Bring Your Own Key now have a detailed view of LLM usage by model on the costs screen. Instead of seeing only the total amount, you can identify exactly which providers and models are driving most of the usage and make clearer decisions about what to keep, replace, or limit.

    Video: [https://kodus.io/wp-content/uploads/2026/07/resumo-de-custos-por-modelo.mp4](https://kodus.io/wp-content/uploads/2026/07/resumo-de-custos-por-modelo.mp4)
  </Update>

  <Update label="July 6, 2026 - Review agent consolidation">
    We reorganized the code review agents to run on a unified infrastructure. Previously, parts of the flow were spread across different places, which could lead to duplicated suggestions and inconsistent behavior. With this consolidation, the pipeline is more predictable, easier to maintain, and less likely to repeat suggestions in the same PR.
  </Update>

  <Update label="July 6, 2026 - Content guard for deduplication">
    We improved the deduplication algorithm so distinct bugs are not grouped as if they were the same issue. The content guard now better considers the actual content of each suggestion, reducing false-positive deduplication and making sure separate issues continue to be reported individually.
  </Update>

  <Update label="July 6, 2026 - Prose findings recovery + Gemini support">
    We fixed unstable behavior in prose finding generation and restored strict mode for Gemini. We also updated the Anthropic SDK, keeping compatibility with newer models and improving response stability.
  </Update>

  <Update label="July 6, 2026 - RBAC documentation">
    We updated the permissions documentation, including the OrganizationSettings scope and the restriction that only the organization Owner can configure BYOK. This makes it clearer who can do what inside the workspace.
  </Update>

  <Update label="July 6, 2026 - Review comments with broken formatting">
    Fixed cases where Kody comments appeared with unexpected formatting in pull requests.
  </Update>

  <Update label="July 6, 2026 - Retry errors with BYOK providers">
    Added preventive adjustments to avoid retry failures when a BYOK provider returns an empty response body.
  </Update>

  <Update label="July 6, 2026 - Sandbox tool errors">
    The agent now handles errors better when running tools in the sandbox environment, without breaking the review.
  </Update>

  <Update label="July 6, 2026 - Normalized user IDs">
    Standardized how author, reviewer, and assignee IDs are handled, preventing PRs from breaking because of type differences, such as string vs. number.
  </Update>

  <Update label="July 6, 2026 - @kody conversation crashing on JSON wrapped in prose">
    Fixed a crash that happened when Kody responded to mentions and the output came back as text containing embedded JSON.
  </Update>

  <Update label="July 6, 2026 - IDE sync config now respects approval settings">
    IDE rule synchronization now respects the approval configuration.
  </Update>

  <Update label="July 6, 2026 - Rules with multiple directories">
    Adjusted Kody Rules validation to correctly handle rules that apply to multiple path groups.
  </Update>

  <Update label="July 6, 2026 - Automatic code review config creation">
    When a repository did not have a code review configuration, creating a Kody Rule could fail silently. The configuration is now created automatically.
  </Update>

  <Update label="July 6, 2026 - Diff re-review in the agent">
    Improved how the agent detects diffs from new commits during re-reviews.
  </Update>

  <Update label="July 6, 2026 - MCP Manager OAuth disconnect">
    Fixed an issue with disconnecting OAuth credentials in MCP Manager that could cause inconsistent behavior.
  </Update>

  <Update label="July 6, 2026 - MCP Manager production build">
    The MCP Manager production build now correctly passes the GitHub token.
  </Update>

  <Update label="July 6, 2026 - Orphaned users in the license list">
    Users removed from the GitHub organization now appear correctly in the license list.
  </Update>

  <Update label="July 6, 2026 - Skipped review email">
    The notification email sent when a review is skipped now includes the author's name/email and no longer breaks when the user does not have a license.
  </Update>

  <Update label="June 29, 2026 - Validated review engine">
    We updated Kody's review pipeline to improve analysis accuracy and reduce cases where important issues could slip through unnoticed.

    The engine now identifies problematic patterns more effectively, better understands changes that span multiple files, and can review code regions with more flexibility when the context is not fully obvious.

    We also optimized processing and reduced the average cost per review by around 30%.
  </Update>

  <Update label="June 29, 2026 - Shareable dashboard views">
    Filters applied in Cockpit are now saved in the URL, including time range, repositories, severity, and status.

    This means you can copy the link and share it with your team on Slack, for example. Anyone who opens the URL will see Cockpit with the same filters applied, without having to manually recreate the view.

    This makes it easier to share specific analyses, such as what changed over the past week or an increase in security suggestions in a repository.

    Video: [https://kodus.io/wp-content/uploads/2026/06/kodus-copy-url.mp4](https://kodus.io/wp-content/uploads/2026/06/kodus-copy-url.mp4)
  </Update>

  <Update label="June 29, 2026 - Unified Kody Rules lifecycle">
    We unified the Kody Rules flow into a single lifecycle, regardless of where the rule was created: the library, manual creation, or inheritance from the organization to the repository.

    With this change, activating, editing, disabling, and approving rules now follow the same path inside the product. We also migrated older rules to the new format and centralized the control of rules pending approval.

    This makes the system more consistent, reduces unexpected states, and ensures that an active rule is actually applied in Kody reviews.
  </Update>

  <Update label="June 29, 2026 - Migrate away from Composio">
    We removed the dependency on Composio as an external MCP broker and moved to our own implementation for GitHub Issues, now integrated with Kodus Issues.

    This reduces an external point of failure, improves call reliability, and gives us more control over authentication, rate limits, and retries.

    As part of the migration, we also removed low-usage integrations that depended on Composio, such as ClickUp and CloudId.
  </Update>

  <Update label="June 29, 2026 - Inheritance toggle">
    When you enable or disable rule inheritance from the organization to a repository, the UI now shows the new state immediately, without waiting for the API response.

    If the call fails, for example because of a connection issue, the state is automatically reverted and we show an error toast. Before, users would click, wait, and not get clear feedback about what had happened.

    We also improved the rules cache update. Now we only invalidate the rules affected by that inheritance change, avoiding unnecessary reloads for rules that did not change.
  </Update>

  <Update label="June 29, 2026 - Kody Rules Origin">
    We added an explicit origin to all Kody Rules: LIBRARY, MANUAL, INHERITED, and SUGGESTED.

    This fixes an issue where some rule creation scenarios could fail silently because the backend expected an origin value that the frontend was not sending.

    Now the contract between frontend and backend is clearer, and the rule origin is validated before reaching the creation flow.
  </Update>

  <Update label="June 29, 2026 - Atlassian Rovo">
    Rovo is an Atlassian AI agent that generates code and edits files automatically. When it creates commits, it includes specific metadata, such as message prefixes and custom headers.

    Previously, our review engine identified those commits as human-written code and could suggest changes on them.

    Now we detect Rovo commits and skip those changes both in the code review logic and in the MCP business-rule validation preflight.
  </Update>

  <Update label="June 29, 2026 - MCP OAuth callback">
    We fixed the OAuth flow for connecting MCPs, such as GitHub and Jira.

    Previously, users who had already completed onboarding could be blocked when trying to add a new MCP. Now the callback works at any time, as long as the state parameter is valid.
  </Update>

  <Update label="June 29, 2026 - Pending rules section">
    Pending rules, which need approval before entering the review pipeline, now have a dedicated section with improved UX.

    The section shows a status badge, who suggested the rule, when it was suggested, and inline actions to approve or reject it.

    Previously, these rules appeared mixed together with active rules, which made it easy to miss that something needed attention.
  </Update>

  <Update label="June 29, 2026 - GitHub Integration GitHub App post-onboarding">
    We fixed an issue where some GitHub integration pages returned a 404 after the user completed onboarding. This affected routes such as /github/integration and /github/organization-name when the GitHub App installation state was not updated correctly. We also adjusted the redirect after installation and added route validations to make the integration flow more reliable across different states.
  </Update>

  <Update label="June 29, 2026 - Severity slicer colors">
    The severity control for low, medium, high, and critical used inconsistent colors. In some places, red meant critical; in others, it meant high. We standardized it to a semantic scale: gray for low, yellow for medium, orange for high, and red for critical. This affects Cockpit filters, suggestion badges, and notification settings.
  </Update>

  <Update label="June 22, 2026 - Forgejo support is now on par with GitHub & GitLab">
    Review comments, commit statuses, force-push detection, and webhook coverage now work consistently for Forgejo repositories. If you self-host with Forgejo, Kody behaves just like on any other major platform.
  </Update>

  <Update label="June 22, 2026 - Faster PR closing for large repos">
    Eliminated duplicate API calls when syncing Kody Rules from changed files. PRs with many files now close noticeably faster.
  </Update>

  <Update label="June 22, 2026 - Cleaner settings UI">
    Platform settings that don't apply to your current Git provider, such as GitHub-specific options when you're on GitLab, are now hidden automatically. Less clutter, fewer misconfigurations.
  </Update>

  <Update label="June 22, 2026 - Reconnecting a Git provider after disconnecting">
    Previously, disconnecting a provider left stale integration configs behind, causing reconnects to fail. Now stale rows are properly cleaned up.
  </Update>

  <Update label="June 22, 2026 - Kody conversation replies with empty responses">
    Resolved an issue where Kody occasionally replied with blank content in PR comment threads when using Claude Sonnet.
  </Update>

  <Update label="June 22, 2026 - NaN deduplication indices">
    Added three-layer protection against NaN values appearing in suggestion deduplication indices, preventing rare but confusing duplicate suggestions.
  </Update>

  <Update label="June 22, 2026 - Forgejo prompt field always empty">
    The formatPromptForLLM function was reading a non-existent field on Forgejo PRs, causing the prompt section to be blank. Now it reads the correct field.
  </Update>

  <Update label="June 22, 2026 - Self-hosted AST graph reliability">
    The kodus-graph CLI was installed but not available to the runtime user in self-hosted worker images. Fixed PATH and install order so graph indexing works out of the box.
  </Update>

  <Update label="June 22, 2026 - Orphaned agent trace records">
    Prevented a race condition in chunked review mode that could leave orphaned IN\_PROGRESS trace records in the database.
  </Update>

  <Update label="June 22, 2026 - Platform settings not scoped to Git tool">
    Settings incompatible with your current Git provider were still visible. Now they're properly filtered based on the connected tool.
  </Update>

  <Update label="June 15, 2026 - Operational metrics in Cockpit">
    Track the health of your review pipeline in real time. Throughput, queue, and processing time metrics are now available in Cockpit.

    Video: [https://kodus.io/wp-content/uploads/2026/06/cockpit.mp4](https://kodus.io/wp-content/uploads/2026/06/cockpit.mp4)
  </Update>

  <Update label="June 15, 2026 - Redesigned Kodus Review tab">
    The review tab has been redesigned with a cleaner interface and more direct actions. You can now analyze and act on suggestions without leaving the PR screen.

    Video: [https://kodus.io/wp-content/uploads/2026/06/kody-review-tab.mp4](https://kodus.io/wp-content/uploads/2026/06/kody-review-tab.mp4)
  </Update>

  <Update label="June 15, 2026 - Backend on pnpm">
    We migrated the backend from Yarn 1 to pnpm. This makes builds faster, improves lockfile consistency, and reduces cache issues across environments.
  </Update>

  <Update label="June 15, 2026 - Token usage screen">
    The token usage screen has been redesigned to make consumption by organization and period easier to understand. It is now simpler to track usage and see how tokens are being consumed over time.

    Video: [https://kodus.io/wp-content/uploads/2026/06/token\_usage.mp4](https://kodus.io/wp-content/uploads/2026/06/token_usage.mp4)
  </Update>

  <Update label="June 15, 2026 - Self-hosted analytics">
    We fixed the analytics integration for self-hosted deployments. Usage metrics now appear correctly in the dashboard.
  </Update>

  <Update label="June 15, 2026 - Issue cache">
    The issue count in the sidebar could sometimes become outdated. The cache is now invalidated correctly after changes.
  </Update>

  <Update label="June 15, 2026 - GitHub rate limit">
    We fixed a rate limit issue in cloud E2E tests. We now use round-robin across multiple bot accounts to better distribute requests.
  </Update>

  <Update label="June 15, 2026 - Notification routing">
    We fixed the behavior of targeted notifications when combined with audience settings. Notifications now reach the right people without duplicates.
  </Update>

  <Update label="June 15, 2026 - Centralized config sync">
    We fixed issues in the centralized sync of Kody Rules configurations across repositories. Sync now correctly handles multiple scopes, stale configurations, and merge-triggered updates.
  </Update>

  <Update label="June 8, 2026 - Moonshot Kimi support for BYOK">
    We added support for Moonshot as a provider, compatible with the Anthropic API.

    You can now use the Kimi Coding Plan model in BYOK setups. To configure it, set the API\_MOONSHOT\_API\_KEY key and select the model in the organization preferences.

    See the Moonshot Kimi documentation for more setup details: [https://docs.kodus.io/knowledge\_base/en/how-to-use-moonshot-with-kodus](https://docs.kodus.io/knowledge_base/en/how-to-use-moonshot-with-kodus)
  </Update>

  <Update label="June 8, 2026 - Monthly token usage control">
    Organizations can now set monthly token consumption limits per model.

    Usage is shown in real time in the interface, with a progress bar. When usage reaches 80% of the limit, the team receives an email alert. If the limit is reached, additional reviews can be blocked automatically.

    Video: [https://kodus.io/wp-content/uploads/2026/06/token-usage.mov](https://kodus.io/wp-content/uploads/2026/06/token-usage.mov)

    See the Monthly Spend Limit documentation for more setup details: [https://docs.kodus.io/how\_to\_use/en/spend-limit](https://docs.kodus.io/how_to_use/en/spend-limit)
  </Update>

  <Update label="June 8, 2026 - More resilient review agent">
    The review engine now handles empty or malformed LLM responses better. This reduces loops in edge cases and helps ensure valid suggestions continue to be delivered even when the provider returns an unexpected response.
  </Update>

  <Update label="June 8, 2026 - Telemetry for self-hosted environments">
    On-premise installations now automatically report health metrics, such as heartbeat, and usage data. The goal is to make diagnosis and support easier without exposing sensitive customer data.
  </Update>

  <Update label="June 8, 2026 - Faster Kody Rules">
    We improved the loading and synchronization of custom rules. We also fixed the count of orphaned rules and made partial updates safer against race conditions.
  </Update>

  <Update label="June 8, 2026 - GitLab compatibility improvements">
    Support for GitLab 13.x in comment webhooks.

    Diff fallback for versions earlier than 15.7.

    Fixes for discussion threads and replies scoped by discussionId.

    Self-hosted development environment documentation.
  </Update>

  <Update label="June 8, 2026 - GitHub member list fix">
    Suspended users no longer appear in the member list for license assignment.
  </Update>

  <Update label="June 8, 2026 - Update Connection fix">
    Integration reauthentication now correctly clears the previous configuration.
  </Update>

  <Update label="June 8, 2026 - Integration reset fix">
    Kody Rules linked to the repo or directory are now removed automatically.
  </Update>

  <Update label="June 8, 2026 - Release Freeze fix">
    Eligibility notifications only appear when the freeze is active.
  </Update>
</div>