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.

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

1
Poll your git history
2
The daemon wakes every 30 seconds by default (configurable with --poll) and reads the most recent commits in your repository. It waits until it sees at least 3 new commits since the last analysis cycle (configurable with --lag) before proceeding. This ensures it analyses real work, not isolated fixups.
3
Analyse code health
4
Once enough commits have accumulated, the daemon’s analyst scans three dimensions:
5
  • Blast radius growth — how many files each package now touches, compared to the configured threshold (default 40%). If the blast radius of recently changed files exceeds this percentage of the total codebase, it is flagged.
  • Circular dependencies — import cycles detected across the files changed in the commit window.
  • Repeated patterns — structural anti-patterns (e.g. the same struct definition copy-pasted into multiple files) that suggest a shared abstraction is missing.
    • 6
    Create a Ghost Branch fix
    7
    When a finding crosses the threshold, Kode speculatively generates a refactoring on a Ghost Branch worktree and validates it against your test suite. This happens entirely in the background — your working tree is never touched.
    8
    Prompt you to review
    9
    Once the Ghost Branch fix is ready and tests pass, the daemon prompts you to review the proposed changes and merge if you agree. If you decline or dismiss the prompt, the Ghost Branch is discarded with no side effects.

    ​
    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

    FlagDescriptionDefault
    --pollPoll interval in seconds30
    --lagNumber of new commits to wait for before analyzing3
    --thresholdBlast radius growth percentage that triggers a fix40.0
    --onceRun a single analysis pass and exitfalse
    --project-dirProject root directorycurrent 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.
    ThresholdBehaviour
    20.0Aggressive — flags moderate drift; useful on strictly-layered codebases
    40.0 (default)Balanced — catches meaningful growth without excessive noise
    60.0Conservative — 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.