[UX/DX] Multi-agent TUI overhaul: named agents, per-agent config, async orchestration & @mention messaging

What variant of Codex are you using?

CLI (TUI mode)

What feature would you like to see?

Summary

This issue bundles several related UX/DX improvements for the multi-agent (orchestrator) experience in Codex TUI. Each section is self-contained and can be implemented independently, but together they form a coherent vision for a legible, composable, and async-friendly agent team interface.

---

1. Named agents & readable TUI output (UX)

Problem

Current sub-agent events in TUI look like raw scaffolding noise:

• Agent spawned
  └ call: call_L8EBbcS9pdc8StNP7dxUPpAk
    agent: 019c6da1-1521-7f31-9a1f-6c04e2c4fb64
    status: pending init
    prompt: Independent review of changeset ...

• Agent closed
  └ call: call_3638stez6LgpgLvvSHhIDMI2
    receiver: 019c6da1-1521-7f31-9a1f-6c04e2c4fb64
    status: completed

UUIDs and raw call-IDs are meaningless to the user and create cognitive overhead.

Proposed change

• Replace UUID/call-ID display with the agent's human-readable name (defined in config, see §2).
• Prefix every agent message/event with a colored @handle tag, e.g.:

◉ @validator  [spawned]
  ┆ REWORK — Findings
  ┆ critical: missing cargo test / cargo fmt / compas validate evidence;
  ┆           merge-ready status not confirmed.
  ┆ suggestion: re-run full gate pipeline and re-attach artefacts.

◉ @reviewer   [done ✓]

• Agent handle color is read from per-agent config (see §2, tui_color).
• Show a compact collapsible block for long agent output (collapsed by default, expandable with a key-bind).
• Keep raw IDs available in a verbose/debug mode (--verbose flag or v key in TUI).

---

2. Per-agent & per-team config files (DX)

Problem

All agent customisation today either does not exist or must be crammed into the global ~/.codex/config.toml, which becomes unmaintainable for teams using more than 2–3 agents. More critically, there is no concept of a team — a named, self-contained group of agents with a designated orchestrator that can be launched as a single unit.

Proposed directory layout

~/.codex/
  agents/
    _builtin/                   # built-in agents (explore, etc.) — always available
    {teamname}/                 # a named, self-contained agent team
      team.toml                 # team manifest: orchestrator, members, launch rules
      {agentname}/
        config.toml             # individual agent definition
        system_prompt.md        # (optional) large system prompt kept separate

team.toml — team manifest

A team is a named, composable unit that can be launched with a single command and exposes a single entry-point to the rest of the system.

[team]
name        = "backend-review"
description = "Full backend review pipeline: static analysis, security audit, integration tests"
tui_color   = "blue"            # color badge for the team in TUI

# The agent that acts as the team's orchestrator and public interface
orchestrator = "lead_reviewer"

# Explicit member list (optional — defaults to all agents in the directory)
members = ["lead_reviewer", "validator", "security_auditor", "test_runner"]

# Inter-team messaging: which other teams this team can send @mentions to
can_address_teams = ["devops", "frontend-review"]

[launch]
# "manual"    — only when explicitly invoked by the user or another team's orchestrator
# "on_task"   — spawned automatically when the user starts a new task
# "always"    — running for the whole session
trigger = "manual"

config.toml schema (per-agent, unchanged from §2 original)

[agent]
name        = "validator"          # @handle used in TUI and @mentions
description = "Static-analysis and gate-check agent"
tui_color   = "cyan"              # ANSI color for @handle badge

[prompt]
# Inline short prompt OR path to an external markdown file (mutually exclusive)
# inline  = "You are a strict code reviewer..."
file = "system_prompt.md"

[invocation]
trigger = "manual"
watch_paths = ["crates/**/*.rs", "Cargo.toml"]

[tools]
shell       = true
apply_patch = false
web_search  = false

[[tools.mcp]]
name    = "github-mcp"
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-github"]

[permissions]
network      = false
fs_read      = true
fs_write     = false
allow_paths  = ["./reports/"]

Benefits

• Arbitrarily large system prompts live in a dedicated .md file — no TOML quoting hell.
• Adding a new agent = creating a new directory; no global config editing.
• Adding a new team = one team.toml + agent subdirectories; zero changes to global config.
• Team members can commit team definitions to VCS alongside project config.
• Built-in agents (explore, etc.) remain available to all teams from _builtin/.

---

3. Teams as first-class units: launch, composition & cross-team collaboration (DX/UX)

3a. Launching a whole team

A team is invoked as a single unit, not by assembling agents one by one:

# Launch a named team — its orchestrator becomes the session's entry point
codex --team backend-review "Review PR #142 for security regressions"

# Or address it in-session via @mention
@backend-review please review the latest changeset

• The team's orchestrator receives the task and fans it out to members according to its own system prompt and the team.toml rules.
• All member agents are spawned lazily (only when the orchestrator actually dispatches to them) unless trigger = "always" is set.
• The team appears in TUI as a collapsible group, prefixed with its colored team badge, e.g. [backend-review].

3b. Team-internal collaboration

Within a team, agents behave as described in §4 (async messaging, @mentions, idle states). Additionally:

• Every agent in a team has implicit access to the team inbox — a shared message bus visible in TUI's team chat panel.
• Agents can use built-in tools (explore, etc.) from _builtin/ without any extra configuration.
• Any agent can post a progress update to the team inbox with a structured status line, visible to the user and to all teammates:

◉ @validator   [progress] Checked 12/20 files — 2 critical findings so far.
◉ @test_runner [progress] Running integration suite (3 min estimated).

3c. Cross-team collaboration

Multiple teams can collaborate within a single session:

• A team is addressable by its name just like an individual agent: @backend-review, @devops.
• Messages addressed to a team are routed to that team's orchestrator, which decides how to handle them internally.
• A team's orchestrator can @mention another team or a specific agent in another team: @devops/deploy_bot please roll out after green CI.
• Cross-team addressing syntax: @{teamname}/{agentname} for individual agents, @{teamname} for the team orchestrator.

3d. Hierarchical orchestration

Teams can be composed into higher-order pipelines without writing code:

User
 └─ @orchestrator (top-level, e.g. "project-lead" team)
      ├─ @backend-review  ←→  @frontend-review
      └─ @devops
           └─ @deploy_bot

• The top-level orchestrator delegates entire sub-goals to teams; it does not need to know which individual agents are inside them.
• Results bubble up through team orchestrators to the top-level orchestrator or directly to the user.
• Any level can go idle and be woken by an @mention from any other level.

---

4. Async orchestrator & agent-to-agent messaging (DX/UX)

Problem

The current orchestrator model requires the top-level agent to block and wait for every sub-agent response, preventing it from doing any other work and creating artificial serialisation.

Proposed model

4a. Non-blocking orchestrator

• Orchestrator can dispatch work and suspend itself (go idle) without holding a context slot.
• Sub-agents post results to a shared team inbox (visible in TUI as a team chat panel).
• When a sub-agent posts a reply addressed to the orchestrator (@orchestrator mention), the orchestrator is woken and resumes with that message in context.

4b. Agent-to-agent @mentions

• Any agent (including the orchestrator) can address another by @handle:

``
@reviewer please verify the patch in reports/diff.patch before I submit.
``

• The target agent receives the message as a high-priority event and can respond when it finishes its current task.
• Agents can also address the user with @user, surfacing an attention indicator in TUI.

4c. Shared team chat panel in TUI

• A scrollable side-panel (or bottom panel) shows all agent-to-agent and agent-to-user messages in chronological order.
• Each message is prefixed with the colored @handle badge (§1) and team badge (§3).
• The user can type @agentname message or @teamname message directly in the chat input.

4d. Wait / idle states

• Agents that have completed their task enter an explicit idle state shown in TUI (e.g., @validator [idle]).
• No CPU/context is consumed while idle; agents are event-driven.

---

5. User @mention of agents & teams (UX)

Problem

Currently the user cannot direct a message to a specific agent or team mid-session without interrupting the entire conversation.

Proposed UX

• In the TUI input bar, typing @agentname ... routes the message only to that agent.
• Typing @teamname ... routes the message to that team's orchestrator.
• The agent/team processes the message asynchronously and responds in the team chat panel when it has capacity.
• If the user's message changes the agent's current task (intent conflict), the agent surfaces an explicit conflict notice and waits for resolution rather than silently ignoring one or the other.
• A plain message (no @) continues to go to the top-level orchestrator as today.

---

6. Acceptance criteria

• [ ] Agent events in TUI show @name instead of UUID/call-ID.
• [ ] ~/.codex/agents/{team}/{agent}/config.toml is loaded at session start.
• [ ] ~/.codex/agents/{team}/team.toml defines the team: orchestrator, members, launch rules.
• [ ] codex --team {teamname} launches the team's orchestrator as the session entry point.
• [ ] system_prompt.md is supported as external prompt source per agent.
• [ ] Per-agent tui_color, tools, permissions, and MCP bindings are respected.
• [ ] Built-in agents (explore, etc.) remain usable by all team members from _builtin/.
• [ ] Cross-team @mention syntax @{teamname} and @{teamname}/{agentname} works in TUI input.
• [ ] Teams appear as collapsible groups in TUI with a team-level badge.
• [ ] Orchestrator can suspend and be woken by a targeted @orchestrator reply.
• [ ] Agents post structured progress updates to the shared team inbox.
• [ ] Agents enter idle state instead of spinning or hallucinating activity.
• [ ] --verbose flag or v key reveals raw UUIDs/call-IDs for debugging.

---

Related issues

• #12000 — spawn_agent hides root cause as "not found"
• (add others as found)

---

Notes

These changes are purely additive — existing single-agent usage and the global config.toml remain fully backward-compatible. The new agent/team directory layout is opt-in.