Truss: One local-first agent across developer clients

Overview

Truss is a local-first coding-agent platform. Developers can use the same models, tools, permissions, workspace memory, and plans from the CLI, terminal UI, Neovim, VS Code, desktop, and a paired mobile client. A compatible local model server can run the workflow without a hosted control plane; cloud providers are also supported with the user's own credentials.

The interfaces are clients of a shared runtime. Truss is designed so a developer can change how they work without rebuilding provider and safety setup for each surface.

The problem

Coding agents are often tied to one editor or one model service. That makes model choice, workspace context, session state, and tool permissions difficult to carry between a terminal and an editor—or to keep under local control.

The engineering goal was to keep the core workflow useful across clients while leaving provider selection and workspace policy with the developer.

Architecture

1. 01CLI · TUI · editor · desktopDifferent clients, shared workflow
2. 02Agent runtimePlans, sessions, workspace context
3. 03Providers + MCPLocal inference or supported cloud models
4. 04Host policyTool grants, approvals, recovery

Truss is a TypeScript monorepo with distinct runtime, provider, MCP, CLI, TUI, VS Code, Neovim, desktop, and mobile packages. CLI and terminal workflows share local configuration and workspace state. Clients connect through host-side services that keep provider credentials and tool permissions at the host, rather than handing them to a remote control plane.

Engineering decisions

Keep the provider boundary replaceable

Provider adapters support local endpoints such as Ollama, LM Studio, and llama.cpp, along with supported cloud providers. Profiles carry endpoint, model, mode, and permission policy, while credentials stay in client credential flows or environment variables rather than workspace configuration.

Keep capabilities shared and clients focused

CLI, TUI, editor, and desktop interfaces provide different ways to enter the same workflow. The runtime owns agent execution and shared tools; the clients present context, plans, approvals, diffs, and session state in forms that fit their host.

Make permission policy visible

Chat and Plan modes are read-only. Edit mode can change files and execute commands, while tool permissions are separately controlled through ask-every-time, auto-allow-read-only, or an explicitly broader policy. MCP configuration follows the same rule: read-only modes load only servers marked read-only.

Technical challenge and solution

Local tools create a serious boundary problem: a model request can lead to filesystem changes, terminal commands, or network work. Truss routes execution through the host and makes requested actions reviewable under a workspace policy. It also supports multiple workspace-local managed-agent profiles, so a task can use separate providers or modes without silently sharing a write lease.

Cross-client state creates a second challenge. Truss shares sessions, plans, workspace memory, and Git-aware context while keeping each client thin enough to own its own interface. Checkpoint and recovery behavior lets a workflow continue after interruption rather than relying on a single uninterrupted chat.

What I built

I built the shared runtime and provider integrations, MCP and tool workflows, host permission boundaries, workspace and session state, and product clients spanning command line, terminal, editor, desktop, and mobile use.

Engineering takeaways

• A local-first system still needs explicit policy because local tool access can be powerful.
• Provider portability depends on normalizing capabilities and failures, not only renaming API endpoints.
• Shared runtime contracts make new client surfaces possible without moving business logic into each UI.
• Recovery and state carry more product value than an uninterrupted chat transcript.

Stack

TypeScript, Node.js, local and cloud model providers, Model Context Protocol, Zod, Git, VS Code, Neovim, terminal UI, Electron, Android, and Vitest.