wularcoderBeta

agent

define and run agents

Define and run agents from the CLI, the dashboard, or on GitHub, Slack and other platforms.

agent list [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

list local or server-owned agents

Without --server, one row per built-in and workspace agent. With --server, list the agent records and current versions owned by that Coder server.

  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current

agent show [id] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

one agent in full: settings, integrations, events, tools, installations

Describe one agent as it will run here, or its active version on a server. It lists its settings, access and per-integration events, and on a server its installations.

  • <id> the agent
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current
coder agent show coder  # what the built-in agent listens to and may do

agent settings [id] [--model <model>] [--access <access>] [--runner <runner>] [--connections <connections>] [--skills <skills>] [--events <events>] [--instructions <instructions>] [--append-system <append-system>] [--match <match>] [--server <server>] [--yes] [--json]

change an agent's settings on your Coder server

Set the model, access, runner, connections, skills, events or appended instructions of an agent in the saved workspace, or publish its next version with new instructions or matches. Settings you leave out stay as they are.

  • <id> the agent
  • --model <model> model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high)
  • --access <access> read-only or auto, at most its definition
  • --runner <runner> the runner its tasks start on, by id or name; empty clears it
  • --connections <connections> the connections its tasks may use, by id
  • --skills <skills> repositories whose skills its tasks get, as owner/name[/path][@ref or commit]; empty clears them
  • --events <events> the events it answers on a platform
  • --instructions <instructions> its system prompt, published as its next version
  • --append-system <append-system> text every task reads after its instructions, up to 64 KB; empty clears it
  • --match <match> start tasks only for event text matching a regex, as event=regex pairs
  • --server <server> act on your Coder server, in the saved workspace
  • --yes connect to a server used for the first time without asking
  • --json JSON output
coder agent settings helper --model sonnet  # a cheaper model for a simple agent

agent init [id] [--integrations <integrations>] [--events <events>] [--access <access>] [--name <name>] [--description <description>] [--match <match>] [--yes] [--json] [--cwd <cwd>]

scaffold an agent folder in .coder/agents

Create .coder/agents// with an agent.json built from the integration catalog, a system.md to write the prompt in, and one sample event per integration for coder agent run. Asks for the id, integrations, events, and access when run in a terminal without them.

  • <id> the agent id: its folder under .coder/agents
  • --integrations <integrations> platforms the agent listens to (see coder agent integrations list)
  • --events <events> events that start tasks, applied to each integration that has them (default: mention)
  • --access <access> read-only or auto, for its tasks, platforms and connections (default: auto)
  • --name <name> display name used in replies (default: the id)
  • --description <description> one line for agent list
  • --match <match> start tasks only for event text matching a regex, as event=regex pairs
  • --yes skip the questions and take the defaults
  • --json JSON output
  • --cwd <cwd> workspace directory; default current
coder agent init  # answer the questions, id included
coder agent init triage --integrations github --events issue,mention --access read-only  # no questions

agent push [id] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

upload workspace agents to a Coder server

Upload one workspace agent, or every agent in .coder/agents when no id is given. The server creates a new immutable version only when its definition, prompt, or files changed.

  • <id> the agent (default: every workspace agent)
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current
coder agent push helper  # upload helper

agent run [agent] [file] [--server <server>] [--workspace <workspace>] [--yes] [--wait] [--task <task>] [--json] [--cwd <cwd>]

run a recorded event through an agent, offline or on a server

Run a recorded platform event (AgentEvent JSON) through an agent. With --server it goes through your Coder server exactly like a webhook: real app, tokens, runner, and the reply is posted. Without it the engine runs here on the agent's prompt and this checkout, platform tools off, and the reply is printed.

  • <agent> the agent id
  • <file> the event JSON file
  • --server <server> act on your Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --wait with --server: follow the task log here until it finishes, then print the reply
  • --task <task> a runner's form: run that server task here
  • --json JSON output
  • --cwd <cwd> workspace directory; default current
coder agent run helper sample-slack-mention.json  # offline: print what the agent would reply
coder agent run helper event.json --server  # for real, through the server

agent usage [--since <since>] [--by <by>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]

aggregate usage by agent, installation, or engine

  • --since <since> period such as 7d or 24h, or milliseconds since epoch
  • --by <by> agent, installation, or engine
  • --server <server> act on the Coder server
  • --workspace <workspace> with --server: the workspace to act in (default: the saved one)
  • --yes with --server: connect to a server used for the first time without asking
  • --json JSON output
  • --cwd <cwd> workspace directory; default current

agent integrations

the integration catalog: events and tool presets

The platforms an agent can listen to and act on: their events and tool presets.

agent integrations list [--json]

list integrations with their events and tools

One row per integration: its id, the events an agent can wire, and every tool it offers; show splits the tools by preset.

  • --json JSON output

agent integrations show [id] [--json]

events and tools of one integration

Describe one integration: each event with what triggers it, and the tools each access (read-only, auto) allows.

  • <id> the integration
  • --json JSON output
coder agent integrations show github  # the GitHub integration in full