Get Started

Toolang keeps agent source in ordinary files, materializes exact runtime inputs with toolang sync, and lets you run the same agent as a one-shot command or a long-lived local runtime.

The shortest useful workflow

1. Create or clone an agent home.
2. Edit one .too file and add the capabilities it needs.
3. Run toolang sync to resolve refs and write runtime inputs.
4. Choose a run surface:
   • invoke for one request
   • run for a foreground runtime
   • start for a background runtime

toolang new alice
toolang sync alice
toolang invoke alice
toolang run alice
toolang start alice

What you work with

Most teams only need four concepts to get started:

• an agent home that contains the files you edit
• a top-level .too file that defines one runnable agent
• capabilities that provide reusable skills, services, prompts, and psyches
• a machine-managed .toolang/ directory for synced and runtime state

alice/
  alice.too
  agents.too
  channels.toml
  hooks.toml
  .env
  .toolang/

The authored files stay readable and diffable. Generated runtime state stays in .toolang/, so you can inspect what changed without mixing it into source.

What happens after sync

toolang sync is the boundary between what you author and what the runtime executes. It:

• resolves capability refs to exact inputs
• writes scope-separated synced output
• records the exact program and metadata later commands should reuse

If something behaves differently than expected, checking synced state is often faster than guessing what the runtime loaded.

Read next

• Read Agent Files for the files that belong in an agent home.
• Read Capabilities for refs, local caps, and scope precedence.
• Read Running Agents for invoke, run, start, and agent selectors.
• Read Tasks and Chores for durable work items and recurring work.
• Read Runtime State for the files to inspect when something goes wrong.
• Read Developer Overview if you want the underlying design model.