# 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

```bash
uv sync --extra dev
uv run clfgui
```

## Backend API

The minimal Hermes backend can be started separately:

```bash
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:

```bash
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:

```bash
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`.