Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Design Principles

This page stays at /docs/design-principles so the landing page can keep its existing link target. The full design set now lives under Developer Overview.

Toolang is intentionally small and explicit. These principles explain what the runtime is optimizing for and where to look next for the detailed design.

Local-first by default

Toolang keeps the primary execution truth on your machine.

That shows up in a few concrete ways:

  • local files are the authored source of truth
  • synced runtime state is written back to disk
  • chats, logs, and registries use local storage
  • shared APIs and event streams are projections, not the only source of truth

Plain files over hidden state

Toolang uses ordinary formats with explicit roles:

  • .too agent source
  • Markdown human-authored prompts, services, psyches, and skills
  • TOML authored configuration
  • JSON synced state and runtime metadata
  • SQLite durable local databases such as chats, registries, and run traces

That keeps the system readable, diffable, and repairable with normal tools.

Synced runtime state is the execution boundary

Toolang does not treat raw source as the thing that runs. toolang sync materializes exact runtime inputs first.

That gives you:

  • repeatable execution inputs
  • fewer surprises when refs move over time
  • a clear place to inspect what the runtime actually used

A small operational surface

Toolang keeps one runtime, one CLI, a short local storage stack, and a direct path from source files to a running agent.

The goal is not to hide the machine. The goal is to keep it simple enough that you can operate and understand the runtime locally first.

Replaceable integrations

Toolang treats memory, channel transport, and sandbox execution as plugin boundaries.

That means integrations can change without replacing the rest of the runtime model. Core runtime behavior still owns scheduling, prompt construction, local state, and diagnostics.

Read the full design set

© 2026 Toolang