agents

Overview

snippbot agents list                         # List agents + workspace version (v1/v2)
snippbot agents show <name>                   # Inspect one agent's workspace
snippbot agents migrate                       # v1→v2 migration (dry-run by default)
snippbot agents migrate --no-dry-run          # Actually rewrite workspace files
snippbot agents reflect <name>                # Force a reflection pass
snippbot agents conflicts                     # Find duplicate workspaces
snippbot agents reconcile                     # Merge them (dry-run by default)

Agent workspaces moved from the v1 layout (PERSONA.md, PROFILE.md, BEHAVIORS.md, SKILLS.md) to the v2 layout (IDENTITY.md, NOTES.md). These commands inspect that state and run the migration.

---

snippbot agents list

List every discoverable agent and whether its workspace is v1 or v2 (detected by the presence of IDENTITY.md).

snippbot agents list

---

snippbot agents show

Show one agent’s workspace: its path, evolution mode, files (with v1/v2 markers), and any pending memory writes.

snippbot agents show <name>

Argument	Description
name	Agent id to inspect

---

snippbot agents migrate

Run the v1→v2 workspace migration script. Defaults to a dry run that prints the proposed changes without writing.

snippbot agents migrate                  # dry-run (default)
snippbot agents migrate --no-dry-run     # apply changes
snippbot agents migrate --agent <name>   # limit to one agent

Option	Default	Description
--dry-run / --no-dry-run	--dry-run	Print proposed changes vs. actually rewrite files
--agent <name>	all	Only migrate the named agent

---

snippbot agents reflect

Force a reflection pass on the agent’s most-recent conversation (requires the local daemon’s dependencies).

snippbot agents reflect <name>

Argument	Description
name	Agent id whose latest conversation to reflect on

---

snippbot agents conflicts

List agents whose workspace exists in more than one directory, and show the search order used to resolve them.

snippbot agents conflicts

A conflict means part of an agent’s memory is invisible to the running daemon. The tools write whichever copy wins resolution; the shadowed copy is never read. Before the resolver was unified, snippbot_core scanned vps/agents first while the gateway scanned ~/.snippbot/agents first, so an agent in both trees ended up with two divergent copies of NOTES.md — one being written, the other displayed.

The output marks the winning copy wins and the others shadowed, with the size and last-modified date of each file so you can see what diverged.

Resolution order:

1. SNIPPBOT_AGENTS_DIR environment variable
2. [agents] dir in config.toml
3. ~/.snippbot/agents — canonical
4. <repo>/vps/agents — legacy fallback for source checkouts

Within that order, a workspace holding an identity or memory file beats a higher-priority empty one, so a half-created directory can never shadow the real workspace.

---

snippbot agents reconcile

Merge duplicate agent workspaces into the canonical location.

snippbot agents reconcile                     # dry-run (default)
snippbot agents reconcile --no-dry-run        # apply the merge
snippbot agents reconcile --agent <name>      # limit to one agent
snippbot agents reconcile --strategy newest   # take the most recent copy

Flag	Default	Description
--dry-run / --no-dry-run	--dry-run	Print the plan without writing
--agent <name>	all	Only reconcile the named agent
--strategy	merge	merge, newest, or canonical

Strategies

• merge — union the content of NOTES.md and USER.md across copies, dropping duplicates, ordered oldest-source-first so the newest phrasing reads last. Non-bullet prose is preserved, not just - bullets.
• newest — take whichever copy has the most recent mtime, per file.
• canonical — keep the copy already in the winning workspace.

Safety

• Dry-run by default; nothing is written until --no-dry-run.
• Every file touched is backed up to _reconcile_backup_<timestamp>/ in the target workspace first.
• A merge that would drop any content block is refused and reported as needing a manual decision, rather than applied.
• A merge whose result would exceed the file’s character cap is refused — consolidate the notes first, then re-run.
• IDENTITY.md and IDLE.md are never auto-merged. They are prose, and a naive union produces a self-contradicting persona. Differences are flagged for manual review, or resolved with --strategy newest|canonical.

Exit codes: 0 success or nothing to do, 1 error, 2 a manual decision is required.