Skip to content
claudestream agent
Updated Edit
On this page

Manage and run agents defined in .agent.json files.

#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

Flags
NameShortTypePresenceEnvDescription
--varlist[str]default: []Template variable in key=value format, repeatable for multiple variables
--model-mstroptionalOverride the model declared in the agent definition file; when omitted the definition's own model is used
--profilestrrequiredName of the claudewheel profile to use for authentication
--cwdstroptionalWorking directory path for the Claude Code process to operate in; when omitted the subprocess inherits this process's directory
--footer, --no-footerbooloptionalDisplay cost and timing summary on stderr after completion (displayed when neither --footer nor --no-footer is passed)
--color, --no-colorbooloptionalEnable ANSI colored output for terminal display and formatting (enabled, subject to TTY and NO_COLOR detection, when neither --color nor --no-color is passed)

#Arguments

Arguments
NameTypePresenceDescription
definitionstrrequiredAgent name or filesystem path to a .agent.json definition file
promptstrrequiredUser message prompt to send to the agent for processing

#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

Flags
NameShortTypePresenceEnvDescription
--cwdstroptionalWorking directory path to scan for agent definitions; when omitted the current directory is scanned

#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

Arguments
NameTypePresenceDescription
namestrrequiredAgent 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

Arguments
NameTypePresenceDescription
namestrrequiredAgent name or filesystem path to the .agent.json definition

More tools from this site

  • claudewheel A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • selfdoc Static Site Generator that builds a project's documentation site directly from its source code, so the docs can never drift from the code they describe, with SEO/AEO, first-class blog, search, and cross-project linking built in
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search