Contents
Start here
TERSL — the language
TERSL/DB — the system
Portal guide
HTTP API
Reference
TERSL — the language

Open-source tooling

What the open-source repository terse-lang/terse contains, from the specification to the Python and TypeScript implementations, the MCP server, host integrations and applications.

Overview#

The TERSL language and its open-source tooling live in one repository, terse-lang/terse, under the Apache-2.0 licence. This page describes each part of the repository and what you would use it for, so that you can pick the right starting point: the specification to learn or implement the language, the MCP server to give an AI host a TERSL store, or one of the applications built on top.

About the name#

The language was renamed from TERSE to TERSL in 2026. Repository names, package names, commands, wire headers, the .terse file extension and diagnostic codes such as TERSE028 keep the original spelling. The rest of this documentation writes TERSL for the language and uses the identifiers as they are.

terse-spec#

terse-spec defines the language. It contains three layers:

  • TERSE.md, the written-form guide. It describes the language as operators and agents should write it, with examples, and is the place to start.
  • TERSE_Specification.md, the normative reference. Where the guide and the specification differ, the specification is right.
  • syntax/, the implementer contract: the token catalogue, the grammar in EBNF, the AST node definitions that an implementation conforms to, the parser states and the semantic rules.

The directory also holds CHANGELOG.md and a prompt-reference/ pack of short primers written in TERSL, sized for a model's system prompt. The specification is at version 0.5.1, a pre-1.0 draft. Changes follow an issue-first process, and implementations track releases by version tag, such as spec-0.5.1. You can browse it at github.com/terse-lang/terse/tree/main/terse-spec.

terse-py#

terse-py is the Python implementation: a parser, AST, state tree, library API and command-line tool. It has no runtime dependencies, works on a state file on disk, requires Python 3.12 or later, and is the engine underneath terse-mcp. The command-line verbs are:

Command Effect
terse-py validate <file> Parse a file and report diagnostics.
terse-py parse <file> Parse a file and emit canonical TERSL.
terse-py fmt <file> Re-serialize a file in canonical form.
terse-py query <state> <expr> Run a query against a state file.
terse-py apply <state> <change> -i Apply a change file to a state file in place.

apply -i takes a lock on a sidecar <state>.lock file for the duration of the write, so concurrent writers queue instead of overwriting each other. terse-py implements an earlier language level than the current specification; the specification's README lists it as implementing 0.3.0 attribute semantics, without the 0.4.0 delta model or the 0.5.0 changes. Some examples on these pages therefore behave differently under terse-py.

terse-ts#

terse-ts is the TypeScript implementation. It is an embedded library with no network code: it tokenizes, parses, validates and emits TERSL, applies declarations to a store, and answers queries. It is ESM-only, its core runs unchanged in a browser, and it provides terse/node for a file-backed store and terse/browser for a localStorage-backed one. It implements the current specification's directives, including the 0.5.1 query changes. It keeps only the latest state, with no history.

terse-mcp#

terse-mcp is an MCP server that exposes a file-backed TERSL store to an AI host. It is designed for local, single-user work: one operator, one AI host and state files on disk. It offers two tools:

Tool Purpose
terse_command One call with two optional channels: declarations for changes and queries for reads. When both are present, the declarations run first and the queries then read the result from the same store.
terse_info Introspection: the store's label and description, whether new namespaces may be created, and the known namespaces. It answers with a TERSL document.

At least one channel must be supplied on each terse_command call. A ? line inside the declarations channel is a command that writes; values come back only through the queries channel. An optional namespace argument selects which store the call runs against.

The server also serves the language on demand as MCP resources: terse://spec/quickstart, a short primer, and terse://spec/full, the written-form guide. Its operator data lives under a home root, ~/.terse/ by default, which holds config.toml, the default store state.terse and further stores under stores/.

To install it from a clone of the repository:

text
git clone https://github.com/terse-lang/terse && cd terse
pip install -e ./terse-py -e ./terse-mcp

An MCP host then needs one entry in its configuration:

text
{
  "mcpServers": {
    "terse": {
      "command": "terse-mcp"
    }
  }
}

terse-integrations#

terse-integrations holds the per-host wiring around terse-mcp:

  • claude-plugin/, a plugin for Claude Code and Cowork. It launches terse-mcp over stdio and ships a using-terse skill. The same plugin installs under OpenClaw as a Claude-format bundle.
  • grok/, configuration and install notes for the Grok CLI.
  • hermes/, configuration for Hermes Agent.
  • openclaw/, install notes for OpenClaw, with a manual fallback.

The repository is also a Claude Code plugin marketplace. In a Claude Code session, these two commands install the plugin:

text
/plugin marketplace add terse-lang/terse
/plugin install terse@terse

Applications#

Three applications in apps/ are built on the language and the shared MCP server:

  • terse-brain is a personal knowledge base that an LLM builds and maintains, in the pattern of an LLM-maintained wiki. It uses a brain namespace, records sources with register-source, checks the store for drift with lint, and can draw the store as an interactive HTML graph.
  • terse-memory gives an agent durable long-term memory in a memory namespace. Its init, wire, setup and doctor commands create and connect the store, and the rules the agent follows for remembering are kept inside the store itself, so every MCP host that connects reads the same policy.
  • terse-browser is a chat-log style operator interface that drives the same terse_command and terse_info operations the AI uses. The repository lists it as a work in progress.

Resources on tourbillon.ai#

The Tourbillon.ai site publishes learning material for the language. These pages are maintained there and are not repeated in this documentation:

  • Getting started: the three ways to start, from a prompt to an agent stack.
  • Syntax cheatsheet: a quick reference that maps JSON to TERSL.
  • Playground: an interactive page for trying the language.
  • Cookbook: task-shaped recipes, such as session memory and a support queue.
  • LLM primer: a condensed primer to paste into a model's system prompt.
  • TERSL explorer: an interactive explorer with guided lessons.