Skip to content

Assistant Agent Persona Matrix

Last verified: 2026-02-22

This document describes agent persona capabilities for each assistant supported by Nyia Keeper.

Nyia Keeper Abstraction

Nyia provides two optional flags for agent persona management:

Flag Description
--agent <name> Select an agent persona for the session
--list-agents List available agent personas (host-side discovery)

Project-shared agents (.nyiakeeper/shared/agents/) are staged per session in the container (Plan 393): Claude gets them through --add-dir, OpenCode through OPENCODE_CONFIG_DIR (unless you set it); vibe and codex get none. Nothing is copied into the project.

Scope Precedence

  1. Session override (--agent <name>) — highest priority
  2. Project-local agent definitions (assistant-specific project path)
  3. Global user agent definitions (assistant-specific global path)
  4. Assistant default behavior (no explicit persona)

Unsupported Behavior

  • If an assistant does not support --agent, Nyia prints guidance and continues with the default launch behavior. No hard error.
  • If an assistant does not support --list-agents, Nyia prints guidance and returns success.

Per-Assistant Capabilities

Claude Code (Anthropic)

Feature Support Details
--agent <name> Direct mapping Maps to claude --agent <name>
--list-agents File-based discovery Scans .claude/agents/ and ~/.claude/agents/
In-session switching /agents slash command Native Claude feature
Agent format Markdown Frontmatter with name, description, optional tools

Agent paths: - Project: .claude/agents/*.md - Global: ~/.claude/agents/*.md (mounted from host ~/.config/nyiakeeper/claude/agents/)

Codex CLI (OpenAI)

Feature Support Details
--agent <name> Guidance-only No CLI flag; prints manual instructions
--list-agents Guidance-only Points to config file location
In-session switching /agent slash command Native Codex feature
Agent format TOML config [agents.<name>] sections in ~/.codex/config.toml

Why guidance-only: Codex does not expose a top-level --agent CLI flag. Agent selection requires interactive /agent commands or pre-configured config.toml sections.

OpenCode

Feature Support Details
--agent <name> Direct mapping Maps to opencode --agent <name>
--list-agents File-based discovery Scans .opencode/agents/ and ~/.config/opencode/agents/
In-session switching Tab key, @ mention Native OpenCode feature
Agent format Markdown or JSON .md and .json definitions

Agent paths: - Project: .opencode/agents/*.md, .opencode/agents/*.json - Global: ~/.config/opencode/agents/ (mounted from host config)

Vibe (Mistral)

Feature Support Details
--agent <name> Direct mapping Maps to vibe --agent <name>
--list-agents File-based discovery Scans <project>/.vibe/agents/, .nyiakeeper/shared/agents/, the team dir and $NYIAKEEPER_HOME/agents/. It does not scan ~/.vibe/agents/, where the shipped personas are
In-session switching Shift+Tab See the note below
Agent format TOML ~/.vibe/agents/*.toml

Reserved names (vibe 3.0.4): ask, accept-edits, smart-approve, auto-approve, explore, lean, main

Selecting a persona: use --agent at launch. A persona is delivered at launch or on a Shift+Tab press before the first message; a later press brought no text in the one run measured; pressing away drops it.

Approvals: a persona starts from ask-like approval and has all of vibe's tools, so it is not read-only. Reading prompts nothing; an edit or a shell write prompts; git status does not.

Agent file format: vibe reads the text from top-level instructions. It does not read [prompt] system, on any version measured (2.25.8, 2.26.1, 3.0.1, 3.0.4). Keys must come before any table:

display_name = "My Reviewer"
description = "Reviews against the plan."
instructions = """
You are acting as a pragmatic reviewer.
"""

Vibe 2.x is not supported for personas. Measured with instructions: delivered on 3.0.4, 3.0.1 and 2.26.1; on 2.25.8 the file loads and no text is delivered.

If the persona you select from ~/.vibe/agents/ has [prompt] and no instructions, Nyia warns before the session and at exit, and the session still starts. On upgrade, Nyia replaces a shipped persona you did not edit. A file you edited is never overwritten: move its text to instructions yourself.

Agent paths: - Global: ~/.vibe/agents/*.toml (mounted from host config) - Config: the global ~/.vibe/config.toml. Since Plan 393 Nyia gives vibe a session VIBE_HOME in the container (links to the global entries, trust/history/worktrees in Nyia's per-project data dir, logs in .nyiakeeper/vibe/logs); a /config change is copied back to the global file at exit when nobody else changed it meanwhile (else a config.toml.conflict-<time>-<pid> copy). The copy-back cannot tell who made a change: an edit the agent makes during the session (through /config or by rewriting config.toml or .env) reaches the global vibe dir too, as it did when these files were linked there directly. No <project>/.vibe/ is created. - Project-shared agents (.nyiakeeper/shared/agents/) are not given to vibe (nor to codex).

Container Boundary

Nyia runs on the host; assistants run inside Docker containers. The agent selection mechanism works as follows:

  1. Host-side parser parses --agent <name> and stores it in NYIA_AGENT
  2. Host-side launcher passes NYIA_AGENT as a Docker env var into the container
  3. Container entrypoint reads NYIA_AGENT and maps it to the assistant's native flag
  4. --list-agents runs entirely host-side by scanning mounted paths — no container needed

Agent definition files are accessible from the host because: - Project-local paths (.claude/agents/) are in the project directory, which is mounted into the container - Global paths (~/.claude/agents/) are in the Nyia config directory, also mounted into the container

Source Anchors