agents-status(5)¶

NAME¶

agents-status - internal state file for Agent Smith

SYNOPSIS¶

$XDG_STATE_HOME/agent-smith/status.yaml

DESCRIPTION¶

The status.yaml file persists the internal state of agents(1). It tracks the active persona and the list of files managed for each persona.

WARNING: This file is managed automatically by the agents CLI. Manual editing is discouraged and may lead to inconsistent state.

FILE FORMAT¶

The file uses YAML format with the following structure:

Top-Level Fields¶

canonical_target (string): The absolute path to the currently active canonical symlink (Source of Truth).
agent_files (list): A list of tracked personas and their associated targets.

Agent File Object¶

Each entry in agent_files represents a known persona:

name (string): The persona name (e.g., “coder”).
path (string): The absolute path to the source definition file (e.g., .../AGENTS.coder.md).
targets (list): A list of target files managed for this persona.

Target Object¶

Each entry in targets represents a specific file or symlink updated when this persona is active:

path (string): The absolute path to the target.
mode (string):
- link: The target is a symbolic link to the source.
- copy: The target is a copy of the source.

EXAMPLE¶

canonical_target: /home/user/.config/agents/AGENTS.md
agent_files:
  - name: coder
    path: /home/user/.local/share/agent-smith/personas/AGENTS.coder.md
    targets:
      - path: /home/user/.config/agents/AGENTS.md
        mode: link
      - path: /home/work/repo/AGENTS.md
        mode: copy
  - name: writer
    path: /home/user/.local/share/agent-smith/personas/AGENTS.writer.md
    targets:
      - path: /home/user/.config/agents/AGENTS.md
        mode: link