Local-first AI coding

What “local-first” actually means

Local-first does not mean “no network.” It means the orchestration loop — planning, tool dispatch, context compression, memory writes, and audit trails — executes in a process you run (TUI or web UI on localhost). Your repository, shell, git state, and optional Obsidian vault are accessed from your machine, not from a vendor sandbox you cannot inspect.

When you send a message, AgentHarness.send() binds chat context, runs intent classification on the fast model, then enters a multi-round ReAct loop. Each round can call dozens of tools; outputs land in tiered context (hot rounds verbatim, older output distilled to .agent_artifacts/). Session JSONL under .agent_sessions/ records the full trace for compliance or debugging.

What stays on your disk

• Session traces: .agent_sessions/<taskId>.jsonl when AGENT_SESSION_JSONL is on (default).
• Workspace artifacts and distilled tool output: .agent_artifacts/.
• Structured memory: .agent_notes.json with scoped notes (chat / workspace / global).
• Embedding index: ~/.liminal/memory.index.json (user-global, not trapped in a temp workspace).
• Optional Obsidian vault: real markdown files under Facts/, Entities/, Reflections/, etc.
• Runtime prefs (non-secret): .agent_runtime_prefs.json for harness toggles without editing .env.

What may still use the cloud

LLM completions go to whatever you configure in AGENT_API_BASE_URL — OpenRouter, OpenAI, Anthropic, xAI, or a local OpenAI-compatible endpoint. Embeddings for hybrid recall use AGENT_EMBED_MODEL when set; disable with an empty embed model for BM25-only.

Vision sidecar (vision_analyze) and optional safety judge are separate model calls you control via env. None of this requires a Liminal Cloud seat for Community Edition.

Approvals and destructive tools

run_shell and run_background are destructive: they go through the normal approval path unless AGENT_YOLO is enabled in a trusted environment. The safety judge (optional) can auto-clear obviously safe calls. Resource locks on file and shell prefixes prevent concurrent corruption.

Air-gapped and on-prem inference

Point AGENT_API_BASE_URL at Ollama or an internal gateway. The same tool surface (files, git, tests, memory) works; only model quality and speed change. See the Ollama guide for slug examples.

AGENT_API_BASE_URL=http://127.0.0.1:11434/v1
AGENT_MODEL=your-local-model
AGENT_FAST_MODEL=your-local-model