Agents (agent command)

An agent is a named persona: a system prompt, a model, a turn limit, and a tool allowlist bundled under one name. Wayland Core ships a read-only pack of built-in agents, and the agent subcommand lets you create and manage your own.

List agents

See the built-in personas, and your own:

wayland-core --list-agents          # built-in personas
wayland-core agent list             # your user agents
wayland-core agent list --builtins  # user agents plus the built-in pack

Create an agent

Create a user agent by name. Inherit from a built-in to start from its prompt, model, and tools, then override what you need:

wayland-core agent create reviewer \
  --inherit-from architect \
  --description "Strict code reviewer" \
  --model claude-sonnet-4-20250514 \
  --max-turns 20 \
  --tool Read --tool Grep

For a long system prompt, read it from a file with the @path form:

wayland-core agent create planner --system-prompt @prompts/planner.md

User agents persist as TOML under the agents directory. A new agent’s name must not clash with a built-in or an existing user agent; pass --force to overwrite an existing file.

Inspect, edit, and delete

wayland-core agent show reviewer    # print the resolved manifest
wayland-core agent edit reviewer    # open the TOML in $EDITOR
wayland-core agent delete reviewer --yes

show resolves built-ins too, so you can read a built-in’s manifest before inheriting from it. Built-in agents are read-only: they cannot be edited or deleted. The --yes flag on delete confirms intent for scripts.

Run with an agent

Pass --agent to a normal run to inherit that persona’s system prompt and turn limit for the session:

wayland-core --agent debugger "Find why the test in auth_test.rs fails"

An explicit --system-prompt or --max-turns on the same command takes precedence over the agent’s values.

Next

• Sub-Agents (Delegate)
• Single-shot and REPL
• CLI Subcommand Reference