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

Agent Files

Toolang keeps authored state in ordinary files. Most of the time you work in one agent home, edit one .too file, and let the runtime manage everything else under .toolang/.

What belongs in an agent home

ship-docs/
  ship-docs.too
  agents.too
  channels.toml
  hooks.toml
  .env
  .toolang/

The important split is:

  • ship-docs.too one runnable agent
  • agents.too optional shared source for all agents in the same home
  • channels.toml and hooks.toml optional bindings for long-lived runtime loops
  • .toolang/ machine-managed synced state, logs, chats, and runtime metadata

What a .too file does

A .too file is the authored source for one agent. It describes:

  • which capabilities the agent depends on
  • which reusable structures the agent defines
  • which thunk the runtime is allowed to execute

A complete .too example

ship-docs.too
use skill openhat/workspace-search
use service openhat/github
use prompt openhat/rewrite
 
struct DocPatch: ```json
{
  "summary": "string",
  "files": ["string"],
  "follow_up_issue": "string | null"
}
```
 
thunk ship-docs(user) => DocPatch:
    tools - memory.forget
    model = gpt-5.4, high
    Read the changed docs in the workspace.
    Summarize the user-facing changes.

Shared source stays separate

If several agents in the same home need shared refs or shared declarations, put them in agents.too instead of copying them into each top-level file.

That separation matters because Toolang keeps:

  • authored source in .too
  • local editable caps in dedicated cap roots
  • synced runtime output in .toolang/

The result is practical:

  • the files you review stay small
  • shared declarations stop drifting between agents
  • generated runtime data can be replaced or repaired without editing source

Agent identity and selection

When you pass an agent to the CLI, Toolang can resolve it from:

  • a simple name such as ship-docs
  • a home/agent selector
  • a local path
  • a canonical URI
  • a stable known-agent identifier

That lets the same command surface work before an agent is registered, while it is running, and after it has been discovered from another source.

Read next

© 2026 Toolang