Skip to main content
Agents spend tokens every time they fetch context at runtime — cloning repos, listing issues, calling APIs. Hooks let you stage this data before the LLM session starts, so the agent begins with everything it needs.

​
The Problem

Without hooks, a typical agent run looks like:
  1. LLM starts
  2. LLM runs git clone (waits, uses tokens to read output)
  3. LLM runs gh issue list (waits, uses tokens to parse JSON)
  4. LLM starts actual work
Steps 2-3 are mechanical — the agent always needs to do them, and they don’t benefit from LLM reasoning.

​
The Solution: Hooks

Pre-hooks run after credentials are loaded but before the LLM session starts. They execute inside the container with full access to credentials and environment variables. Define them in the agent’s config.toml:
Then reference the staged files in the body of your SKILL.md:

​
Example: Git clone

The most common hook — clone the repo the agent will work on:

​
Example: Shell command

Run any shell command. GITHUB_TOKEN, GH_TOKEN, and other credential env vars are already set:

​
Example: HTTP fetch

Fetch data from an API endpoint:
Environment variable interpolation (${VAR_NAME}) is supported since commands run via /bin/sh.

​
Post-hooks

Post-hooks run after the LLM session completes. Use them for cleanup, artifact upload, or reporting:

​
Referencing Staged Files in SKILL.md

After hooks run, tell the agent what’s available in the body of your SKILL.md:

​
Direct Context Injection

For simple, inline data that needs to be embedded directly in your SKILL.md instructions, use direct context injection with the !`command` syntax. Commands are executed after pre-hooks but before the LLM session starts, and their output replaces the expression inline.

​
Syntax

Becomes:

​
When to use

  • Hooks: For setup tasks like cloning repos or downloading data files
  • Direct injection: For inline values the agent needs to reference in instructions

​
Examples

Basic usage:
With pre-staged data:
Error handling: If a command fails, it’s replaced with [Error: <message>]:
Becomes:

​
Limitations

  • Commands have a 60-second timeout
  • Output is limited to prevent prompt explosion
  • Errors are inline — use hooks for critical setup that should fail the run

​
Tips

  • Hooks run sequentially in the order defined in config.toml
  • Each hook has a 5-minute timeout — hooks are also bounded by the container-level timeout
  • If a command fails (non-zero exit), the run aborts with an error
  • Environment variables set inside hook commands do not propagate back to the agent’s process.env
  • Use hooks for setup, direct injection for values — hooks for cloning repos or staging files, direct context injection for inline dynamic values the agent needs to reference

​
Next steps