applications lode

CLI and daemon

Active contributors: Bryan

The CLI and daemon are the two ways agents talk to Lode. The CLI in src/lode/cli.py is best for per-turn commands, while the daemon in src/lode/daemon.py keeps a local HTTP surface warm for tools that prefer requests.

Directory layout

src/lode/
  cli.py       # command-line parser and handlers
  daemon.py    # local HTTP server
  __main__.py  # python -m lode entry point
pyproject.toml # console script registration

Key abstractions

Name	File	Description
build_parser()	src/lode/cli.py	Builds subcommands for index, status, search, symbol, context, neighbors, impact, Kuzu sync, embeddings, and serve.
cmd_index()	src/lode/cli.py	Calls index_repo() and optionally Kuzu sync.
cmd_impact()	src/lode/cli.py	Resolves a target and emits impact reports.
LodeHandler	src/lode/daemon.py	Handles local HTTP GET and POST routes.
serve()	src/lode/daemon.py	Starts ThreadingHTTPServer with the selected data directory.

How it works

The CLI maps each subcommand to a cmd_* function, opens the SQLite database with connect() from src/lode/storage.py, and emits JSON when --json is set. The daemon uses the same storage and graph functions through LodeHandler.do_GET() and LodeHandler.do_POST().

sequenceDiagram
    participant Agent
    participant CLI as lode CLI
    participant Daemon as loded
    participant Core as shared core
    participant DB as SQLite

    Agent->>CLI: lode context "query" --json
    CLI->>Core: build_context_pack()
    Core->>DB: FTS + graph neighbors
    CLI-->>Agent: JSON context
    Agent->>Daemon: POST /impact
    Daemon->>Core: impact_report()
    Core->>DB: resolved graph traversal
    Daemon-->>Agent: JSON impact report

Loading

Integration points

• src/lode/cli.py imports index_repo() from src/lode/indexer.py, graph helpers from src/lode/graph.py, and query helpers from src/lode/storage.py.
• src/lode/daemon.py imports the same core functions and adds request IDs plus metrics through src/lode/observability.py.
• pyproject.toml exposes both new names (lode, loded) and temporary aliases (kg, kgd).

Entry points for modification

Add CLI flags in build_parser() in src/lode/cli.py, then wire behavior in the matching cmd_* function. Add daemon routes in LodeHandler.do_GET() or LodeHandler.do_POST() in src/lode/daemon.py, then update openapi/loded.openapi.yml and docs/api/loded.md.

Key source files

File	Purpose
src/lode/cli.py	CLI commands and JSON/plain output.
src/lode/daemon.py	Local HTTP routes, request IDs, and metrics hooks.
src/lode/__main__.py	Module execution entry point.
pyproject.toml	Console script registration.
openapi/loded.openapi.yml	API contract for daemon endpoints.

Related pages

• Daemon endpoints
• Context packs
• Impact analysis