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

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

Standard background watch

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.

Related

• Ghost Branches concept — how speculative fix branches work
• kode stats — review historical blast radius and failure trends
• kode loop — run a targeted fix on a specific task