toolang

Toolang is a description language and runtime for agents.

Tool calling turned LLMs from chatbots into agents. Toolang makes agents easy to build, run, and share.

Language

Toolang is an agent description language. It is designed to feel close to natural language, while still being structured enough for the runtime to execute.

Toolang files usually use the .too extension. A .too file can describe an agent, the caps it uses, and the thunks it can run.

use psyche  briceyan/senior-engineer
use psyche  briceyan/concise
use service briceyan/github
use skill   briceyan/codebase-navigation
 
thunk:
  models = gpt-5
  tools = shell, filesystem, web_search, service_use
 
  user:
    Work as a coding agent for software engineering tasks.
    Understand the repository before editing.
    Make focused changes that fit the existing code.
    Verify the result and report exactly what passed.

Caps

Lines that start with use reference remote caps.

Caps are short for composable agent primitives. They are the basic building blocks of Toolang agents.

You can also define caps directly inside a .too file:

psyche help-english-learning:
  The user is learning English.
  Whenever you notice mistakes, briefly correct them at the bottom of the response.

Toolang supports four kinds of caps:

Kind	Purpose
`psyche`	Instructions that shape the agent's role, style, and operating mindset
`skill`	Reusable behavior or knowledge that can be loaded into instructions or context when needed
`service`	Services available to the agent through protocols such as MCP
`prompt`	User-facing prompts, often used like custom slash commands for convenient interaction with agents

Thunks

A thunk is an agentic procedure powered by LLMs and agent loops.

thunk review:
  models = gpt-5
  skills = none
  services = github
  tools = shell, filesystem
 
  user:
    Review the changed files and summarize risks.

You can probably already guess what these lines mean.

The header lines with = are called directives. They select or limit what is available during an agent run, including models, tools, caps, recall sources, and sub-thunks.

The later blocks are messages. They define what is sent to the model. In chat, the runtime fills these from the conversation. In scripts, you can write them directly to run a thunk without interactive input.

You can skip thread history and write the message history yourself, including simulated assistant messages or tool results. This makes it easy to test a model in a specific conversation state.

use skill briceyan/verification
 
thunk try-models:
  models = gpt-5
  tools = shell, filesystem
  recall = none
 
  user:
    Reproduce a docs build failure after a grammar update.
    Find the likely cause and propose the smallest fix.
 
  assistant:
    I will run the docs build and inspect the first TypeScript error.
 
  tool:
    bun run build
    vocs.config.tsx:25 Type 'string | LanguageRegistration' is not assignable.

Every part of a thunk has a sensible default. Even an empty thunk is valid and can run out of the box.

Caps and thunks are enough to understand the core of Toolang.

For the full syntax, see the language reference or grammar documentation.

Runtime

Toolang is also a runtime for agents. It can run agents in a few forms:

Form	How it is run
Remote agent	Run a shared agent directly from a remote `.too` file, URL, or reference
Local agent	Run a named agent that has already been created locally
Agent script	Run a `.too` file as a script and invoke a specific thunk

Preparation

Before an agent runs, Toolang prepares everything the runtime needs:

Resolve and fetch the agent source, unless it is already local or used as a script
Resolve, fetch, and materialize caps
Load available models from configured provider plugins and API keys
Load tools from built-in or installed plugins

Toolang caches prepared results and refreshes them when related files, caps, configs, or plugins change.

Serving chats, tasks, and chores

When Toolang runs a remote or local agent, it usually launches several runners:

toolang run https://toolang.ai/dev.too
toolang start alice

Each runner handles a different kind of request:

Request	What it handles
`chat`	Interactive conversations
`task`	One-shot or project-based work
`chore`	Recurring work

For each request, Toolang looks for a matching thunk named chat, task, or chore. The matching thunk decides how the request is handled. If no matching thunk is defined, Toolang uses the default behavior, so newly created agents can run out of the box.

Toolang uses selectors to limit the available models, tools, and caps. These limits form a ceiling set. Toolang combines this ceiling with the selected thunk's directives to compute the effective runtime environment for each run.

Toolang also sets up triggers to react to events. watch reloads agent state when source files, configs, caps, tasks, or chores change. pulse pushes chore requests into the runner queue on schedule.

Runners, triggers, and selectors can all be specified explicitly at startup, making agents more controllable and safer to run.

One-shot invocation

When Toolang executes an agent script, it runs the named thunk and exits when the work is done:

toolang helpers.too review

In this mode, runners and triggers are not launched by default. Selectors might be specified to limit the available models, tools, and caps for the one-shot run.

Runners, triggers, and selectors can all be specified explicitly at startup for more advanced scenarios.

Extensions

Caps are the standard way to extend an agent. They let agents use reusable instructions, skills, prompts, SaaS services, desktop applications, and more.

Toolang itself can also be extended through plugins. Supported plugin types include:

Plugin	Purpose	Bundled implementations
Model providers	Connect Toolang to model providers	`Ollama`, `OpenRouter`, `OpenAI`, `DeepSeek`, `Google`
Model adapters	Support different model API formats	`chat_completions`, `responses`
Tools	Add callable tools to agent runs	`filesystem`, `shell`, `service_use`, `web_search`
Loops	Add agent loop implementations	`basic`
Channels	Let users interact with agents from different places	`telegram`

The bundled implementations listed here are the current set and will continue to grow.

Toolang can automatically discover and load user-defined plugins, unless they are excluded by configuration or limited by selectors or thunk directives.