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
What it does
The daemon operates in a tight polling loop:
- Polls git history — samples the last
--lag commits at each --poll interval
- Analyzes health signals — measures blast radius growth percentage, circular dependency chains, and repeated anti-patterns across commits
- 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
- Reports status — each analysis cycle prints a one-line summary so you can follow along without a separate dashboard
Flags
Examples
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.
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.
