> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trykode.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Automate Tech Debt Detection with Kode Daemon
> Kode Daemon runs silently in the background, watching your git history for code health trends and proactively suggesting fixes on Ghost Branches.
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
### Poll your git history
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.
### Analyse code health
Once enough commits have accumulated, the daemon's analyst scans three dimensions:
* **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.
### Create a Ghost Branch fix
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.
### Prompt you to review
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
```bash theme={null}
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.
```bash theme={null}
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:
```json theme={null}
{
"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:
```bash theme={null}
# 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:
```yaml theme={null}
# 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
Trigger the full pipeline manually for a specific task, with Ghost Branch exploration and automatic rollback.
Expose Kode's engine to Claude Desktop and other agents via the Model Context Protocol.