features local daemon api

Local daemon API

Active contributors: Bryan

The local daemon API lets tools use Lode through HTTP instead of spawning the CLI. src/lode/daemon.py exposes health, status, search, index, context, impact, and metrics endpoints on localhost by default.

Purpose

The daemon is useful when an editor, agent, or local service wants repeated access to the same SQLite index. It uses the same core functions as the CLI, so behavior stays consistent across command-line and HTTP usage.

Directory layout

src/lode/daemon.py         # HTTP server and route handlers
openapi/loded.openapi.yml  # endpoint schema
docs/api/loded.md          # generated endpoint docs
docs/runbooks/loded.md     # operational runbook

Endpoints

Endpoint	Method	Implementation
/health	GET	LodeHandler.do_GET() in src/lode/daemon.py
/metrics	GET	LodeHandler.do_GET() in src/lode/daemon.py
/status	GET	LodeHandler.do_GET() in src/lode/daemon.py
/search	GET, POST	LodeHandler.do_GET() and LodeHandler.do_POST()
/index	POST	LodeHandler.do_POST()
/context	POST	LodeHandler.do_POST()
/impact	GET, POST	LodeHandler.do_GET() and LodeHandler.do_POST()

Integration points

• src/lode/observability.py provides request logs and counters.
• src/lode/features.py gates /metrics behind LODE_FEATURE_METRICS.
• scripts/generate_openapi_docs.py keeps docs/api/loded.md synced to openapi/loded.openapi.yml.

Key source files

File	Purpose
src/lode/daemon.py	HTTP route handling.
openapi/loded.openapi.yml	API schema.
docs/api/loded.md	Generated human-readable API docs.
tests/test_e2e.py	Daemon e2e coverage.

Entry points for modification

Add or change routes in src/lode/daemon.py, then update openapi/loded.openapi.yml and regenerate docs/api/loded.md with scripts/generate_openapi_docs.py.

Related pages

• Daemon endpoints
• Logging
• Metrics