clog

clog is a runtime-first oversight agent for watching product and runtime health, pulling evidence from systems like PostHog, GitHub, and Vercel, and surfacing clear findings through a shared backend.

What is here

• apps/clog: core runtime, gateway, monitoring loop, integrations, and AI bridge.
• apps/types: shared contracts consumed by every frontend.
• apps/launcher: bootstrap launcher and frontend chooser.
• apps/frontends/tui: terminal UI for the runtime.
• apps/frontends/telegram: Telegram transport and bridge.
• apps/frontends/web: Svelte dashboard frontend.
• docs: architecture, runtime setup, and service docs.

Quick start

bun install
bun run dev

The launcher boots or connects to the runtime, then lets you choose TUI or Web.

Direct entrypoints:

bun run runtime
bun run tui
bun run web

Common commands

bun run dev              # start the launcher
bun run runtime          # start the runtime only
bun run runtime --wakeup # start runtime and run one wakeup pass immediately
bun run tui              # start the terminal UI directly
bun run web              # start the Svelte dashboard in Vite
bun run web:build        # build the Svelte dashboard for the runtime server
bun run lint             # run oxlint
bun run typecheck        # run tsc --noEmit
bun run web:typecheck    # run svelte-check for the dashboard
bun run test             # run the Bun test suite
bun run build            # bundle apps/clog to dist/
bun run ci               # lint + typecheck + test
bun run update-all       # update workspace deps to latest

How it is structured

apps/clog is the authority. Frontends are adapters.

• src/config.ts: environment parsing and capability shaping.
• src/brain/service.ts: shared chat entrypoint used by the gateway and transports.
• src/monitoring: turns observations into findings.
• src/gateway: transport-agnostic API surface.
• src/integrations: PostHog, GitHub, Vercel, and other external boundaries.
• src/execution/shell-executor.ts: restricted read-only shell access for runtime inspection.

Runtime layout

The runtime expects per-instance state under .runtime/instances/<instance>/:

• read-only/settings.json: runtime-owned settings.
• read-only/tools.json: tool visibility and enablement.
• wakeup.json: wakeup prompt and frequency.
• storage/: structured runtime state.
• workspace/: model-targeted writable workspace.

Secrets still belong in .env.

Docs

• Architecture
• Runtime setup
• Conversation schema