> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trykode.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# kode daemon — Background Code Health Monitor

> kode daemon watches your git history, detects blast radius growth and circular dependencies, and proposes Ghost Branch fixes when thresholds are crossed.

`kode daemon` runs as a long-lived background process that watches your repository for code health trends. Every N seconds it samples your git history, measures blast radius growth and circular dependency accumulation, and — when thresholds are crossed — speculatively opens a Ghost Branch fix for you to review. Think of it as a continuous hygiene monitor that works alongside your normal development flow.

## Synopsis

```bash theme={null}
kode daemon
```

## What it does

The daemon operates in a tight polling loop:

1. **Polls git history** — samples the last `--lag` commits at each `--poll` interval
2. **Analyzes health signals** — measures blast radius growth percentage, circular dependency chains, and repeated anti-patterns across commits
3. **Triggers speculative fixes** — when a metric crosses its threshold, the daemon creates a Ghost Branch with a proposed refactor and prints the branch name to the terminal
4. **Reports status** — each analysis cycle prints a one-line summary so you can follow along without a separate dashboard

## Flags

| Flag            | Type   | Default                   | Description                                        |
| --------------- | ------ | ------------------------- | -------------------------------------------------- |
| `--project-dir` | string | current working directory | Project root                                       |
| `--poll`        | int    | `30`                      | Poll interval in seconds                           |
| `--lag`         | int    | `3`                       | Number of commits to wait before analyzing         |
| `--threshold`   | float  | `40.0`                    | Blast radius growth percentage that triggers a fix |
| `--once`        | bool   | `false`                   | Run a single analysis and exit (CI mode)           |

## Examples

<CodeGroup>
  ```bash Standard background watch theme={null}
  kode daemon
  ```

  ```bash More aggressive monitoring theme={null}
  kode daemon --poll 60 --threshold 25
  ```

  ```bash Single-shot CI analysis theme={null}
  kode daemon --once
  ```

  ```bash Watch a non-current directory theme={null}
  kode daemon --project-dir /path/to/project --poll 120
  ```
</CodeGroup>

## CI usage

`kode daemon --once` is designed for integration into CI pipelines. It runs a single analysis cycle, writes a JSON report to stdout, then exits:

* **Exit 0** — no issues found; codebase is within thresholds
* **Exit 1** — one or more findings exceeded the threshold

The JSON report includes a `findings` array with the affected files, the metric that triggered the finding, and the measured value. You can feed this directly into your CI reporting or pull request checks.

```bash theme={null}
# Example GitHub Actions step
- name: Code health check
  run: kode daemon --once --threshold 30
```

<Note>
  `kode daemon --once` does not require an LLM API key. It only analyzes git history and emits a report — it does not generate fixes. The full daemon (without `--once`) requires `KODE_LLM_API_KEY` or `OPENAI_API_KEY` to be set so it can create Ghost Branch repairs.
</Note>

## How blast radius is measured

Blast radius represents the percentage of the codebase that is transitively affected by a change to a given file. The daemon calculates this by walking the project's import graph and counting downstream dependents. A single commit that sharply increases this number — past `--threshold` — signals that something is accumulating unintended coupling.

## Commit lag

`--lag 3` tells the daemon to wait until at least three new commits have landed before it runs an analysis. This prevents false positives from single-commit spikes and ensures the trend signal is stable before suggesting a fix.

<Tip>
  Run `kode daemon` in a `tmux` or `screen` session during active development sprints. It stays silent when everything is healthy and only interrupts you when it finds a real signal worth acting on.
</Tip>

## Related

* [Ghost Branches concept](/concepts/ghost-branches) — how speculative fix branches work
* [`kode stats`](/cli/stats) — review historical blast radius and failure trends
* [`kode loop`](/cli/loop) — run a targeted fix on a specific task