Configuration Reference

All Workshop configuration is set through configure/1 or individual functions. Configuration is stored in :persistent_term for zero-cost reads.

configure/1

configure(
  backend: AgentWorkshop.Backends.Claude,
  backend_config: ClaudeWrapper.Config.new(working_dir: "."),
  model: "sonnet",
  permission_mode: :bypass_permissions,
  context: "Elixir project. Run mix test before committing.",
  max_cost_usd: 10.00,
  mcp: [port: 4222],
  dashboard: true,
  persistence: true,
  git_context: true
)

Required options

Agent defaults

These apply to all agents unless overridden per-agent:

Feature toggles

Agent options

Options passed to agent/3 override global defaults:

agent(:impl, "You write clean, well-tested code.",
  model: "sonnet",
  max_turns: 15,
  timeout: :timer.minutes(5),
  max_cost_usd: 2.00,
  allowed_tools: ["Read", "Edit", "Write", "Bash"],
  skill: :pair,
  workshop_tools: true
)

Profiles

Profiles are reusable agent templates. Define once, create many agents:

profile(:coder, "You write clean, well-tested code.",
  model: "sonnet",
  max_turns: 15,
  timeout: :timer.minutes(5))

profile(:reviewer, "Review for correctness. Do not modify files.",
  model: "opus",
  allowed_tools: ["Read", "Bash"])

# Create agents from profiles
from_profile(:coder, :dev_1)
from_profile(:coder, :dev_2)
from_profile(:reviewer, :rev_1)

# Or use profiles with board workers
board_worker(:dev_1, :code, profile: :coder, interval: :timer.seconds(30))

Manage profiles:

profiles()              # list all profiles

Backends

A backend implements AgentWorkshop.Backend -- 8 callbacks for starting sessions, sending messages, and reading state.

Claude (recommended)

configure(
  backend: AgentWorkshop.Backends.Claude,
  backend_config: ClaudeWrapper.Config.new(working_dir: ".")
)

The Claude backend wraps the Claude Code CLI via claude_wrapper. Backend config options are passed through to ClaudeWrapper.Config.

Codex

configure(
  backend: AgentWorkshop.Backends.Codex,
  backend_config: CodexWrapper.Config.new(working_dir: ".")
)

Custom backends

Implement the AgentWorkshop.Backend behaviour:

defmodule MyBackend do
  @behaviour AgentWorkshop.Backend

  @impl true
  def start_session(config, opts), do: ...
  @impl true
  def send_message(pid, prompt, opts), do: ...
  @impl true
  def session_id(pid), do: ...
  @impl true
  def history(pid), do: ...
  @impl true
  def total_cost(pid), do: ...
  @impl true
  def turn_count(pid), do: ...
  @impl true
  def last_result(pid), do: ...
  @impl true
  def stop_session(pid), do: ...
end

Budgets

Set cost limits globally or per-agent:

# Global budget
configure(max_cost_usd: 10.00)

# Per-agent budget
agent(:impl, "Coder", max_cost_usd: 2.00)

# Check budgets
budget()         # global remaining
budget(:impl)    # per-agent
cost()           # itemized by agent
total_cost()     # total across all agents

When a budget is exceeded, the agent's next message returns {:error, :budget_exceeded}.

Persistence

Persist work board, store, and events to disk:

configure(persistence: true)              # .agent_workshop/ in cwd
configure(persistence: "/path/to/dir")    # custom directory

Files written

• work.json -- full work board snapshot
• store.json -- key-value store snapshot
• workflows.json -- workflow definitions
• events.jsonl -- append-only event log

Writes are debounced (100ms) and triggered by PubSub events. On startup with persistence enabled, saved state is loaded back into ETS.

Git context

Automatically inject git state into agent prompts:

configure(git_context: true)

This appends the current branch, working tree status, and recent commits to each agent's system prompt. The context is refreshed on each message. Requires the optional {:git, "~> 0.2"} dependency.

# Manual access
git_summary()    # structured map of git state
git_diff()       # current diff text

Scheduling

Run prompts on a recurring interval:

every(:monitor, "Check CI status and report",
  interval: :timer.minutes(5))

schedules()         # list active schedules
cancel(:monitor)    # stop a schedule

The scheduler skips ticks when the agent is busy.

Event log

All Workshop activity is logged to a ring buffer:

watch()              # print events live (PubSub subscription)
unwatch()            # stop watching
events()             # last 20 events
events(last: 50)     # more history
clear_events()       # reset the ring buffer

Events include agent creation/dismissal, ask/cast completions, work board changes, board worker claims, and workflow state transitions.

Shared store

Key-value scratchpad for agent coordination:

put(:spec, "LRU cache with TTL support")
get(:spec)
store()              # show all entries
store_keys()         # list keys
delete(:spec)

Values are stored in ETS and optionally persisted to disk.

Skills

Skills follow the agentskills.io open standard. Skill content is injected into the agent's system prompt:

agent(:impl, "Coder", skill: :pair)

Built-in skills (in skills/):

Log level

Control Workshop log verbosity:

log_level(:warning)    # quiet -- only warnings and errors
log_level(:info)       # default
log_level(:debug)      # verbose -- see send/receive for every message

Teardown

reset(:impl)       # clear one agent's conversation
dismiss(:impl)     # remove an agent
reset_all()        # stop all agents, clear config
stop()             # full teardown (agents, tables, config)

Examples

The examples/ directory contains ready-to-use setup files:

Load any example:

load("examples/board.exs")