CLFGUI

Native desktop owner interface for a local agent kernel.

V1 is intentionally small:

• enter an intent
• watch the running plan
• answer human gates
• review and approve the result

The GUI and kernel currently run in one process. The boundary is kept explicit through LocalAgentKernel, so the kernel can later move into a headless daemon behind the same application-facing API.

Run

uv sync --extra dev
uv run clfgui

Backend API

The minimal Hermes backend can be started separately:

uv run clfgui-api

Configuration:

• CLFGUI_HERMES_PROFILES_DIR: defaults to Hermes/profiles
• CLFGUI_BACKEND_STATE_DIR: defaults to .clfgui
• CLFGUI_HERMES_BIN: defaults to hermes
• CLFGUI_HERMES_TIMEOUT: defaults to 180
• CLFGUI_API_HOST: defaults to 127.0.0.1
• CLFGUI_API_PORT: defaults to 8765

Endpoints:

• GET /
• GET /api/health
• GET /api/agents
• GET /api/context
• POST /api/context
• POST /api/run-agent
• GET /api/runs
• GET /api/runs/<run_id>

Examples:

curl http://127.0.0.1:8765/
curl http://127.0.0.1:8765/api/health
curl http://127.0.0.1:8765/api/agents
curl http://127.0.0.1:8765/api/context
curl -X POST http://127.0.0.1:8765/api/context \
  -H 'Content-Type: application/json' \
  -d '{"context":"initial context"}'
curl -X POST http://127.0.0.1:8765/api/run-agent \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"planner"}'
curl http://127.0.0.1:8765/api/runs

Trailing slashes are accepted for API collection routes, so /api/agents/ works like /api/agents.

For local development without installing the package:

PYTHONPATH=src python3 -m clfgui.app

The SQLite database is stored in the platform app-data directory by default. Override it with CLFGUI_DB_PATH=/path/to/clfgui.sqlite3.