On this page
Reference for the claudestream agent command group: run, list, info, and validate agents defined in .agent.json files with tools, sandbox, and budget.
#claudestream agent
Manage and run agents defined in .agent.json files. Agent definitions declare a model, prompt template, allowed tools with input schemas, sandbox permissions, and budget limits (cost, turns, tokens). Use subcommands to validate configurations, run agents against prompts, and inspect metadata.
#agent run
Load an agent definition and run it with the given prompt. Accepts a path to a .agent.json file or a bare agent name (resolved from .claudestream/agents/). The definition specifies the model, a prompt template with {variable} placeholders, tool schemas, sandbox policy, and budget constraints. Use --var key=value to substitute template variables. Use --model to override the model declared in the definition.
Effect: mutating
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--var | str | Template variable in key=value format, repeatable for multiple variables | |||
--model | -m | str | Override the model declared in the agent definition file | ||
--profile | str | Name of the claudewheel profile to use for authentication | |||
--cwd | str | Working directory path for the Claude Code process to operate in | |||
--footer | bool | True | Display cost and timing summary on stderr after completion | ||
--color | bool | True | Enable ANSI colored output for terminal display and formatting |
#Arguments
| Name | Required | Description |
|---|---|---|
prompt | yes | User message prompt to send to the agent for processing |
definition | yes | Agent name or filesystem path to a .agent.json definition file |
#agent list
List available agents from .claudestream/agents/. Scans the agents directory in the working directory (or the directory specified by --cwd) and prints a table with each agent's name, schema version, and description. Use this to discover which agents are configured before running one with 'agent run'.
Effect: read_only
#Flags
| Name | Short | Type | Default | Env | Description |
|---|---|---|---|---|---|
--cwd | str | Working directory path for the Claude Code process to operate in |
#agent info
Display agent definition details for a given agent name or path. Loads the .agent.json file, parses it, and prints every configured field: name, version, description, model, budget limits, sandbox policy, tool schemas, MCP server config, and stream options. Use this to inspect an agent's full configuration before invoking it.
Effect: read_only
#Arguments
| Name | Required | Description |
|---|---|---|
name | yes | Agent name or filesystem path to the .agent.json definition |
#agent validate
Validate an agent definition by loading and checking its .agent.json file for structural and semantic correctness. Verifies that budget values are non-negative, the prompt template is non-empty, tool schemas are well-formed, and required fields are present. Reports specific errors on failure or prints a success confirmation.
Effect: read_only
#Arguments
| Name | Required | Description |
|---|---|---|
name | yes | Agent name or filesystem path to the .agent.json definition |