Toolang

A language and runtime for agents and humans.

The language expresses agent loops with fine-grained control using a small subset of natural language — readable by humans and agents, precise enough for the runtime to execute.

Getting started

Toolang runs on macOS and Linux with Python 3.11+. Windows support is coming soon.

Install Toolang with uv or pip; the main command is toolang, with too as a shorter alias:

uv tool install toolang  # or: pip install toolang
too --version            # same as: toolang --version

Toolang supports Anthropic, DeepSeek, Google, OpenAI and OpenRouter out of the box, along with local models through Ollama and llama.cpp. To inspect all configured providers and list available models, run:

too providers --all
too models

To use additional providers or models, put a compatible flat catalog at ~/.toolang/catalog.json. See Model Catalog for the format and an upstream conversion example.

Remote agents

Run a shared agent locally by referencing its URL or GitHub shorthand. Toolang fetches the definition and starts a terminal chat using your model configuration:

too https://toolang.ai/dev.too chat
too briceyan/dev chat

In remote-agent chat mode, the agent responds only to your messages; it does not start tasks or chores on its own.

Local agents

Create an agent from scratch, or clone a shared one as a starting point:

too new NAME
too clone https://toolang.ai/dev.too NAME

Once created, the agent is ready for a conversation:

too NAME chat
too NAME shell

too NAME shell opens an interactive shell in the agent's home. Use too shell to open one in the Toolang root (TOOLANG_ROOT, or ~/.toolang by default), or too --root /path/to/toolang-root shell to select another root. The destination must already exist. Exit to return to your previous shell; an interactive terminal is required.

You can then configure the agent's capabilities and add tasks or recurring chores. Use the CLI help to see the available commands:

too --help

Scripts

Toolang also runs agents as scripts. Here is hello world in Toolang:

cat > hello-world.too <<'EOF'
agic():
  Say hello to the world.
EOF

too hello-world.too

Use too init to generate aide.too as a starting point. Read the source or use --help to see its available runnables:

too init DIR
too DIR/aide.too --help

You can rename the file or modify the code to suit your needs, then call it from Makefiles, CI jobs, or other scripts to add agent capabilities to existing automation.

To execute a runnable, pass its name and the arguments defined by its signature. If you omit the name, Toolang calls the entry runnable, as in the hello-world script above:

too DIR/aide.too polish tone=professional -- "Can you send the notes?"

The same script can also run interactively:

too DIR/aide.too chat

Language

The tree-sitter-toolang repository provides the grammar and parser packages for Python, JavaScript, and Rust. See the syntax reference for the full language syntax.

See examples for runnable Toolang programs:

Common commands

Use these commands to run and manage agents. Add --help to any command for its usage and options.

too new <agent>                       # Create a local agent
too clone <ref> <agent>               # Clone an agent definition
too serve <ref>                       # Run an agent service in the foreground
too start <agent>                     # Start a local agent service in the background
too stop <agent>                      # Stop a running agent service

too init <dir>                        # Create aide.too in a directory
too [run] <script> [runnable]         # Execute a script; run is optional

too caps                              # List available capabilities
too tools                             # List available tools
too models                            # List available models
too providers                         # List available providers

too --help                            # Show common commands
too more                              # Show additional commands

Links

• Website: toolang.ai
• Docs: toolang.ai/docs
• GitHub: github.com/openhat-ai/toolang