Automate Tech Debt Detection with Kode Daemon

The longer a codebase grows without deliberate refactoring, the more expensive each new feature becomes. kode daemon addresses this by running silently in the background, polling your git history for code health signals — blast radius growth, circular dependencies, repeated anti-patterns — and creating speculative fixes on Ghost Branches before the debt becomes structural. You decide whether to merge the fix; the daemon handles the detection and generation.

How the daemon works

Starting the daemon

kode daemon

The daemon runs in the foreground and prints a brief header showing the detected repository, branch, and active configuration:

── Kode Daemon ──────────────────────────────────────
  Repository: github.com/example/api (main)
  Poll interval: 30s | Commit lag: 3 | Threshold: 40%
✓ Daemon active — watching main
  Press Ctrl+C to stop

Keep the daemon running in a persistent terminal session (tmux, screen, or a background process manager) during active development.

All flags

Flag	Description	Default
`--poll`	Poll interval in seconds	`30`
`--lag`	Number of new commits to wait for before analyzing	`3`
`--threshold`	Blast radius growth percentage that triggers a fix	`40.0`
`--once`	Run a single analysis pass and exit	`false`
`--project-dir`	Project root directory	current working directory

Single-shot CI mode

Pass --once to run exactly one analysis cycle and exit. This mode does not require an API key — it performs the analysis phase only, without generating Ghost Branch fixes. It is designed to be used as a code-health gate in CI pipelines.

kode daemon --once

Kode writes a JSON analysis report to stdout and exits with code 0 if the codebase is clean or code 1 if issues were found:

{
  "findings": [
    {
      "title": "Blast Radius Growth",
      "description": "Recent commits expanded blast radius to 63% of the codebase",
      "severity": "warning",
      "file": "~63% of Go files affected",
      "metric": 62.5,
      "threshold": 40.0
    }
  ],
  "files_changed": 4,
  "blast_radius": 18,
  "blast_radius_pct": 62.5,
  "commit_count": 3
}

Typical workflows

Development: persistent background watcher

Run the daemon alongside your normal development workflow in a dedicated terminal pane:

# In a dedicated tmux pane
kode daemon --poll 60 --lag 5

Increase --lag on repos with a high commit frequency to avoid analysis running on every trivial fix.

CI: code health gate

Add a kode daemon --once step to your pipeline to fail the build when blast radius growth exceeds your threshold:

# GitHub Actions example
- name: Kode health check
  run: kode daemon --once --threshold 50
  # exits 1 if blast radius growth exceeds 50%

The daemon works best on repositories with a consistent, incremental commit cadence — several small commits per day. If your team uses very large infrequent merge commits, increase --lag (e.g. --lag 1) so the daemon analyses each merge as soon as it lands rather than waiting for additional commits that may not come for days.

The full daemon (without --once) requires a valid KODE_LLM_API_KEY to generate Ghost Branch fixes. The --once analysis-only mode does not make any LLM calls and works without an API key.

Tuning the threshold

The --threshold flag controls how sensitive the daemon is. A lower value means more findings; a higher value means only severe growth is flagged.

Threshold	Behaviour
`20.0`	Aggressive — flags moderate drift; useful on strictly-layered codebases
`40.0` (default)	Balanced — catches meaningful growth without excessive noise
`60.0`	Conservative — only flags severe structural regressions

Next steps

Loop Mode

Trigger the full pipeline manually for a specific task, with Ghost Branch exploration and automatic rollback.

MCP Integration

Expose Kode’s engine to Claude Desktop and other agents via the Model Context Protocol.

Get Started

Core Concepts

Configuration

Guides

Troubleshooting

Automate Tech Debt Detection with Kode Daemon

How the daemon works

Starting the daemon

All flags

Single-shot CI mode

Typical workflows

Development: persistent background watcher

CI: code health gate

Tuning the threshold

Next steps

Loop Mode

MCP Integration

​How the daemon works

​Starting the daemon

​All flags

​Single-shot CI mode

​Typical workflows

​Development: persistent background watcher

​CI: code health gate

​Tuning the threshold

​Next steps

Loop Mode

MCP Integration

How the daemon works

Starting the daemon

All flags

Single-shot CI mode

Typical workflows

Development: persistent background watcher

CI: code health gate

Tuning the threshold

Next steps