Skip to main content
AgentUse supports variable placeholders in agent files (both YAML frontmatter and markdown content) to make your agent definitions more flexible and secure.

​
Available Variables

VariableSyntaxUsage LocationsDescription
Project Root${root}Filesystem paths, System promptExpands to the project root directory
Agent Directory${agentDir}Filesystem paths, System promptExpands to the directory containing the agent file
Temp Directory${tmpDir}Filesystem paths, System promptExpands to the system temp directory
Environment Variable${env:VAR_NAME}mcpServers.<name>.auth.token onlyExpands to the value of an environment variable
${env:VAR_NAME} is intentionally NOT supported in the system prompt (markdown content) to prevent accidental secret exposure to the LLM.

​
${root} - Project Root

The ${root} variable expands to your project’s root directory, which is detected by looking for markers like .git, package.json, or .agentuse directory.

​
Usage

Use ${root} in filesystem tool path configurations to reference paths relative to your project root, regardless of where you run the agent from. 
---
model: anthropic:claude-sonnet-4-5
tools:
  filesystem:
    - path: ${root}/src
      permissions: [read, write]
    - paths:
        - ${root}/docs
        - ${root}/tests
      permissions: [read]
---

​
Benefits

  • Portable: Paths work regardless of current working directory
  • Consistent: Always references the same location relative to project
  • Safe: Restricts file access to defined project paths

​
${agentDir} - Agent Directory

The ${agentDir} variable expands to the directory containing the agent file. This is useful for referencing files bundled with your agent.

​
Usage

Use ${agentDir} to access files that are distributed alongside your agent file, such as scripts, configs, or data files. 
---
model: anthropic:claude-sonnet-4-5
tools:
  filesystem:
    - path: ${agentDir}/scripts
      permissions: [read]
    - path: ${agentDir}/data
      permissions: [read, write]
---

​
Benefits

  • Self-contained agents: Bundle resources with your agent file
  • Relocatable: Agent works regardless of where it’s installed
  • No absolute paths: Avoid hardcoding paths in agent definitions
${agentDir} is only available when the agent is loaded from a file. If the agent is loaded from a string or other source, this variable will not be resolved.

​
${tmpDir} - Temp Directory

The ${tmpDir} variable expands to the system’s temporary directory (os.tmpdir()).

​
Usage

Use ${tmpDir} for temporary file storage that doesn’t need to persist across agent runs. 
---
model: anthropic:claude-sonnet-4-5
tools:
  filesystem:
    - path: ${tmpDir}/agentuse
      permissions: [read, write]
---

​
Benefits

  • Platform-independent: Works on macOS, Linux, and Windows
  • No cleanup needed: Temp files are typically cleaned by the OS
  • Safe for scratch work: Ideal for intermediate processing files

​
${env:VAR_NAME} - Environment Variables

The ${env:VAR_NAME} syntax allows you to reference environment variables in your configuration. This is particularly useful for sensitive values like API tokens.

​
Usage

Currently supported in HTTP MCP server authentication: 
---
model: anthropic:claude-sonnet-4-5
mcpServers:
  api_server:
    url: https://api.example.com/mcp
    auth:
      type: bearer
      token: ${env:API_TOKEN}
    requiredEnvVars:
      - API_TOKEN  # Validates the variable exists before connecting
---

​
How It Works

  1. When the agent starts, ${env:API_TOKEN} is replaced with process.env.API_TOKEN
  2. If the environment variable is not set, a warning is logged
  3. Use requiredEnvVars to ensure the variable exists before the agent runs

​
Security Benefits

  • No hardcoded secrets: Tokens stay in environment variables, not in code
  • Version control safe: .agentuse files can be committed without exposing secrets
  • Explicit requirements: requiredEnvVars documents what’s needed to run the agent

​
Variables in System Prompt

You can use path variables (${root}, ${agentDir}, ${tmpDir}) in the markdown content (system prompt) of your agent file. This helps the agent understand its environment.

​
Usage

---
model: anthropic:claude-sonnet-4-5
tools:
  filesystem:
    - path: ${root}/data
      permissions: [read, write]
---

You are a data processing agent.

## Your Environment

- Project root: ${root}
- Agent location: ${agentDir}
- Temp workspace: ${tmpDir}

You have read/write access to the project's data directory.
When the agent runs, these variables are resolved to actual paths, so the agent receives: 
You are a data processing agent.

## Your Environment

- Project root: /home/user/my-project
- Agent location: /home/user/my-project/agents
- Temp workspace: /tmp

You have read/write access to the project's data directory.

​
Security Note

${env:VAR_NAME} is not supported in the system prompt to prevent accidental secret exposure. Environment variables should only be used for authentication tokens in MCP server configuration, where they are handled securely and never sent to the LLM.

​
Examples

​
Complete Agent with All Path Variables

---
model: anthropic:claude-sonnet-4-5
description: "Agent with multiple filesystem paths"
tools:
  filesystem:
    - path: ${root}/data
      permissions: [read, write]
    - path: ${agentDir}/templates
      permissions: [read]
    - path: ${tmpDir}/workspace
      permissions: [read, write]
mcpServers:
  external_api:
    url: https://api.example.com/mcp
    auth:
      type: bearer
      token: ${env:EXTERNAL_API_KEY}
    requiredEnvVars:
      - EXTERNAL_API_KEY
---

You are an agent with access to project files, bundled templates, and temp workspace.

​
Self-Contained Agent with Bundled Resources

---
model: anthropic:claude-sonnet-4-5
description: "Agent with bundled scripts and data"
tools:
  filesystem:
    - path: ${agentDir}/scripts
      permissions: [read]
    - path: ${agentDir}/prompts
      permissions: [read]
    - path: ${tmpDir}/output
      permissions: [read, write]
---

You have access to bundled scripts in ./scripts and prompt templates in ./prompts.
Write output files to the temp workspace.

​
Multiple Environment Variables

mcpServers:
  service_a:
    url: https://a.example.com/mcp
    auth:
      type: bearer
      token: ${env:SERVICE_A_TOKEN}
    requiredEnvVars:
      - SERVICE_A_TOKEN

  service_b:
    url: https://b.example.com/mcp
    auth:
      type: bearer
      token: ${env:SERVICE_B_TOKEN}
    requiredEnvVars:
      - SERVICE_B_TOKEN

​
Variable Resolution

Variables are resolved at different times:
VariableResolution TimeScope
${root}Agent initializationFilesystem paths, System prompt
${agentDir}Agent initializationFilesystem paths, System prompt
${tmpDir}Agent initializationFilesystem paths, System prompt
${env:VAR_NAME}MCP connection setupHTTP auth tokens only

​
Troubleshooting

Ensure you’re using the correct syntax:
  • Project root: ${root} (lowercase)
  • Agent directory: ${agentDir} (camelCase)
  • Temp directory: ${tmpDir} (camelCase)
  • Environment variables: ${env:VAR_NAME} (with env: prefix)
The old ${VAR_NAME} syntax without the env: prefix is not supported.
${agentDir} is only available when the agent is loaded from a file path. It will not resolve when:
  • The agent is loaded from a URL
  • The agent is loaded from a string
  • The agent file path is not passed to the runner
In these cases, ${agentDir} will remain as literal text and path validation may fail.
If you see a warning about an environment variable not being set:
  1. Check that the variable is exported in your shell or defined in .env
  2. Verify the variable name matches exactly (case-sensitive)
  3. Add the variable to requiredEnvVars for early validation
If ${root} isn’t pointing to the expected directory:
  1. Ensure your project has a recognizable marker (.git, package.json, etc.)
  2. Run the agent from within your project directory
  3. Use agentuse run -C /path/to/project to specify the project root

​
Next Steps

Agent Syntax

Complete YAML configuration reference

Environment Variables

All environment variables used by AgentUse