Skip to main content

Documentation Index

Fetch the complete documentation index at: https://kode-f177b001.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

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

FlagTypeDefaultDescription
--project-dirstringcurrent working directoryProject root
--pollint30Poll interval in seconds
--lagint3Number of commits to wait before analyzing
--thresholdfloat40.0Blast radius growth percentage that triggers a fix
--onceboolfalseRun a single analysis and exit (CI mode)

​
Examples

kode daemon

​
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. 
# Example GitHub Actions step
- name: Code health check
  run: kode daemon --once --threshold 30
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.

​
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.
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.