Skip to content

Support first-class main-session agent/role presets with skill scoping #17545

Open

Description

@isCopyman

Summary

Codex should support first-class role/agent presets for the main session, not just top-level --profile config overrides or isolated CODEX_HOME workarounds.

A role should be able to define things like:

  • system/developer instructions
  • allowed/disallowed tools
  • preloaded skills
  • model / provider / profile defaults
  • optional approval / sandbox defaults

and then be selectable directly at startup, for example:

codex --agent frontend
codex --agent backend
codex --agent reviewer

Problem

Today, --profile appears to be a config/profile selector, not a true role/agent definition mechanism.

That means there is currently no clean built-in way to express a setup like:

  • frontend agent can use frontend/UI skills
  • backend agent can use backend/server skills
  • reviewer agent can use review-focused skills and prompts

without falling back to heavier workarounds like separate CODEX_HOME directories.

Using separate CODEX_HOME roots is functional but awkward because it can also split:

  • config state
  • installed skills
  • local history/session state
  • auth and other user-local data

That is much heavier than “start the same Codex, but as a different role”.

Why this matters

This is useful even for single-user workflows, not only multi-agent orchestration.

Typical usage:

  • one terminal starts a frontend role
  • another starts a backend role
  • both belong to the same overall user/workspace flow
  • but each should have different instructions, skill preload, and capability surface

Claude Code already exposes a much more direct version of this idea via --agent / custom agents. Codex currently feels noticeably less ergonomic for this specific workflow.

Proposed UX

Any of these would help, with a strong preference for the first two:

Option 1: first-class top-level agents

Allow config like:

[agents.frontend]
description = "Frontend/UI specialist"
prompt = "You are a frontend specialist..."
skills = ["frontend-skill", "ui-review"]
tools = ["Read", "Edit", "Write", "Bash"]
profile = "frontend"

[agents.backend]
description = "Backend specialist"
prompt = "You are a backend specialist..."
skills = ["backend-skill"]
tools = ["Read", "Edit", "Write", "Bash"]
profile = "backend"

Then:

codex --agent frontend
codex --agent backend

Option 2: role presets that extend profiles

Keep profiles for ordinary config, but add a higher-level role layer that can also bind skills, prompts, and tool restrictions.

Option 3: make skills profile-scoped

If Codex does not want a full agent abstraction yet, allowing profiles.<name>.skills (or equivalent) would still close a large part of the gap.

Expected behavior

  • A role should be selectable at startup without switching to a different CODEX_HOME
  • Different roles should be able to preload different skills
  • Different roles should be able to set different instructions / tool restrictions
  • Roles should compose cleanly with existing profiles
  • Session/history storage should remain in the same normal Codex environment unless the user explicitly wants full separation

Non-goal

This request is not asking for full background subagent orchestration by itself.
It is mainly about making “start Codex as role X” a first-class concept for the main session.

Related issues

This request is adjacent to those, but narrower:
it is specifically about role/agent presets for the main interactive session, especially with skill scoping.

Activity

  1. added
    enhancementNew feature or request
    CLIIssues related to the Codex CLI
    skillsIssues related to skills
    configIssues involving config.toml, config keys, config merging, or config updates
    on Apr 12, 2026
  2. isCopyman commented on Apr 12, 2026

    @isCopyman
    Author

    One clarification that may make this request easier to scope:

    This does not necessarily need a brand-new orchestration system.

    Codex already has an internal subagent concept/threading model. What seems to be missing is a way to reuse a similar agent definition abstraction for the main session itself.

    In other words, the request is closer to:

    • let the main interactive session choose an agent/role preset at startup
    • let that preset define system prompt / MCP / skills / tool restrictions / model defaults
    • keep using the normal session/history environment

    rather than:

    • require users to spawn a background subagent
    • or split into a separate CODEX_HOME just to simulate a role

    So the desired UX is not "I want a subagent".
    It is "I want to configure which agent role the main session runs as".

  3. added
    subagentIssues involving subagents or multi-agent features
    and removed
    CLIIssues related to the Codex CLI
    skillsIssues related to skills
    on Apr 12, 2026
  4. Keesan12 commented on May 18, 2026

    @Keesan12

    I think main-session roles matter because they reduce accidental overreach before you ever get to subagents. The load-bearing part for me is not just preloaded skills, it is a visible receipt of effective role config at session start: instructions hash, allowed tools, loaded skills, and profile or model defaults. Otherwise role drift gets debugged from behavior instead of from state. We have been wrapping similar role-aware runs in MartinLoop, and the sessions stay much easier to reason about when the root session prints its effective contract up front.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    configIssues involving config.toml, config keys, config merging, or config updatesenhancementNew feature or requestsubagentIssues involving subagents or multi-agent features

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions