Agents

WTmag ships with built-in support for four agents: Pi, OpenCode, Claude Code, and Codex. All four spawn in interactive TUI mode so you can jump in and work alongside the agent at any point. The default agent and launch preferences are configurable globally or per project, and always overridable on a per-command basis.

The built-in agents

Pi is the default in the generated config. Change it globally in ~/.config/wtmag/config.toml, per project in wtmag.toml, or per run with --agent.

Interactive mode, not headless

All agents spawn in interactive mode (TUI). This is deliberate. The worker is not a black box running in the background — it's a terminal session you can walk into at any point. Read the conversation, run commands in a split pane, or stop the agent and take over. It's just tmux.

Custom agents

Custom agents are fully supported. Define your own with a name, a command, and how it receives prompts, and WTmag handles the rest.

[agents.aider]
command = "aider"
prompt_flag = "--message"

With fixed args:

[agents.my-agent]
command = "my-agent"
args = ["run", "--profile", "coding"]
prompt_flag = "--prompt"

Use it:

wtmag create --github 456 -t issue --agent aider

Or make it the default:

[agents.default]
name = "aider"

See configuration for the full schema and agents reference for auth and model overrides.

How prompt_flag works

WTmag writes the full brief to .wtmag/prompt.md, then passes a bootstrap prompt that tells the agent to read that file. The prompt_flag tells WTmag how to send that bootstrap prompt:

• --prompt → opencode --prompt "Read ./.wtmag/prompt.md and use it as the full task brief."
• --message → aider --message "Read ./.wtmag/prompt.md and use it as the full task brief."
• empty → pi "Read ./.wtmag/prompt.md and use it as the full task brief." (positional)

Leave it empty or omit it if the agent takes the prompt as a positional argument.

Auth

WTmag intentionally stays out of credential management. Every agent authenticates through its own native flow, so there is nothing extra to configure on WTmag's side. Install each agent separately, configure its auth separately, and make sure it already works from a normal shell before you use it with WTmag.

• opencode, claude, and codex should be authenticated with their own native login or config flow.
• pi should be configured in ~/.pi/agent/models.json. Pi supports literal keys, environment variable names, and ! shell commands for resolving provider credentials — useful with secret managers like 1Password or Infisical.

Extensibility

The agent system is open by design, same as the task source system. The four built-in agents can be extended with any CLI you define. Either side of the system — agents and task sources — can grow without the other changing.

For auth and model override details, see the agents reference.