Building local-first AI developer tools

“Local-first” can describe several different choices: where files are read, where a model runs, where credentials live, or whether an application requires a hosted account. A developer tool should be precise about each boundary instead of implying that the whole workflow is offline or private by default.

Keep workspace access with the host

The client that owns the workspace should mediate file reads, writes, terminal commands, and Git operations. A model request can then receive bounded context and return a proposed action; the host validates the action against a tool schema and the active permission policy before running it.

That host boundary is valuable even when a user selects a cloud model. It lets the application keep direct filesystem access and command execution local while sending only the context needed for a particular task to the selected provider. The product should make that data flow understandable.

Separate runtime from interface

CLI, terminal, editor, and desktop clients have different interaction patterns. They do not need separate agent logic. Define runtime contracts for sessions, plans, tool events, approvals, and provider requests, then let each client adapt those contracts to its environment.

This separation makes a new interface less risky. A terminal client can render keyboard-focused approvals while an editor client can show diffs beside the file. Neither should reimplement authorization or call providers directly if the shared runtime owns those responsibilities.

Treat local providers as a first-class path

Local model servers change operational assumptions: endpoints may appear and disappear, model identifiers may be user-defined, and compatible servers may not support the same tools or structured outputs. A provider adapter should probe and report capabilities, normalize events where possible, and return clear errors when a workflow cannot run.

The same local-first setup can also support cloud providers. Keep model choice in workspace or user profiles, but keep secrets in a host credential flow or environment variable—not a repository configuration file that may be committed.

Design permissions around actions

Modes such as Chat, Plan, and Edit can help set expectations, but the tool layer still needs its own policy. Read-only inspection, file writes, network calls, and terminal execution have different consequences. A useful permission model makes those differences visible and allows a user to review the actual operation before it runs.

Workspace-scoped memory and plans need the same care. Persist what helps continue a task, keep it local to the workspace where appropriate, and let people inspect or clear it. “Local” should not become a synonym for “unbounded.”

Make state portable across clients

Conversations alone are a fragile record of work. Persist structured plans, changed-file lists, tool results, checkpoints, and enough provider metadata to resume or explain an interrupted task. Keep those records versioned so one client can pick up work another began without losing the decision trail.

Recovery needs to account for partial effects. A file write may have completed before a client disconnected. A resumable operation should check actual workspace state before repeating a mutation.

A boundary checklist

• Which process reads and writes workspace files?
• Where do model credentials live?
• What context leaves the machine for a cloud provider?
• Which actions require approval, and what does the person review?
• Which state is shared across clients and how is it scoped?
• What happens if a client or provider disconnects mid-operation?

A local-first coding tool is not just a model endpoint inside an editor. It is a host-controlled workflow that can explain where data goes, what an agent can do, and how work continues across interruptions.