# toolang

> Agent language, runtime, and CLI.

## Probe

<div>
  ```bash
  echo hi
  ```
</div>


## CLI

The `toolang` command is the main user interface for the runtime.

### Analysis commands

```bash
toolang check <agent_ref>
toolang dump ast <agent_ref>
toolang dump ir <agent_ref>
toolang dump messages <agent_ref>
```

These commands inspect or validate an agent without starting long-running
execution.

### Execution commands

```bash
toolang run <agent_ref>
toolang serve <agent_ref>
toolang start <agent_ref>
```

* `run`: one-shot foreground execution
* `serve`: long-running foreground execution
* `start`: long-running background execution

### Capability commands

```bash
toolang skill add <cap_ref>
toolang skill remove <cap_ref>
toolang skill list
toolang skill sync
toolang skill update
```

The same command shape applies to:

* `service`
* `prompt`
* `psyche`

There are also aggregate commands:

```bash
toolang caps list
toolang caps sync
toolang caps update
```

### Running-agent commands

```bash
toolang ps
toolang inspect <run_ref>
toolang logs <run_ref>
toolang stop <run_ref>
```

`run_ref` may be either:

* an `agent_ref`
* a `house_no`


## Getting Started

Toolang is an agent-oriented system with three layers:

* a language
* a runtime
* a CLI

In Toolang, each runnable agent is defined by a top-level `.too` file inside a
home.

### Core ideas

* A **home** is the private root directory of a Toolang setup.
* An **agent** is one runnable `.too` file inside that home.
* **Caps** are composable agent primitives such as skills, services, prompts,
  and psyches.
* The runtime resolves caps, prepares model context, runs the model and tools,
  and persists local agent state.

### Core commands

```bash
toolang check reviewer.too
toolang run reviewer
toolang serve reviewer
toolang start reviewer
toolang ps
```

### Home layout

```text
home/
  reviewer.too
  toolang.toml
  toolang.lock
  skills/
  services/
  prompts/
  psyches/
  .caps/
  agents/
```

Read [Runtime Design](/runtime-design) next for the full model.


## Implementation Choices

Toolang v1 is intentionally small and local-first.

### Main choices

* Python for the runtime
* Typer for the CLI
* Pydantic v2 for typed internal models
* OpenAI Python SDK for the model layer
* FastAPI and Uvicorn for HTTP serving
* httpx for network access
* SQLite for local persistence
* Tree-sitter for editor support

### Parser strategy

Toolang uses two parser layers:

* a runtime parser
* a Tree-sitter grammar for editor tooling

For v1, the runtime parser stays hand-written.

### Config and lock formats

* `toolang.toml`: TOML
* `toolang.lock`: TOML
* `.caps/index.json`: JSON

TOML is preferred for human-facing configuration, and inline tables are
preferred where they improve clarity.

### Registry and publishing

V1 uses:

* the `toolang` CLI for cap management
* `caps.sh` as the hosted registry for searching, exploring, and scoring caps

A separate `caps` CLI is not part of v1.


## Language

Toolang source files use the `.too` extension.

A `.too` file defines an agent and may contain:

* cap references
* inline cap definitions
* structs
* stashes
* prompts
* thunks

### What Toolang is

Toolang is not only a syntax.

It includes:

* the language for describing agents
* the runtime for executing them
* the CLI for running and managing them

### Caps

Toolang works with four cap kinds:

* skill
* service
* prompt
* psyche

Caps can come from three default sources:

* source caps
* config caps
* local caps

When names collide, precedence is:

1. local caps
2. config caps
3. source caps

### References

Capability references use the `cap_ref` form:

```text
user-or-org/cap-name
```

The final resolution depends on the cap kind. A skill and a service may probe
different GitHub repositories and paths for the same bare `cap_ref`.

### Thunks

Thunks are the executable entrypoints of an agent. They define what the runtime
prepares and what the model run is trying to do.

See [CLI](/cli) and [Runtime Design](/runtime-design) for execution semantics.


## Runtime Design

The Toolang runtime is built around the idea of a **home**.

### Home

A home contains:

* top-level `.too` agent files
* `toolang.toml`
* `toolang.lock`
* local caps under `skills/`, `services/`, `prompts/`, and `psyches/`
* resolved artifacts under `.caps/`
* per-agent state under `agents/<agent_name>/`

### Global storage

Toolang also uses global storage under `~/.toolang/`:

```text
~/.toolang/
  store/
  registry/
  cache/
  hotel/
  agents.db
```

#### What each part does

* `store/`: global object store for resolved artifacts
* `registry/`: cached registry metadata, including `caps.sh`
* `cache/`: transient download cache
* `hotel/`: materialized homes for URL-based execution
* `agents.db`: table of running agents across homes

### Resolution

Capability resolution follows this order:

1. source files
2. `toolang.lock`
3. home `.caps/`
4. global `~/.toolang/store/`
5. remote registry
6. rematerialize into home `.caps/`

### References

* `agent_ref` resolves to an agent source
* `run_ref` resolves to a running agent
* `house_no` is the short persistent identifier used for runtime lookup

For the full design spec, see the repository document:
`runtime-design.md`.