AI Groups System Architecture

Version: 2.0 (2026-01-04) Status: In Development Server: /opt/mcp-servers/aimsg/mcp_aimsg_server.py (to be renamed)

Standardized Terminology

Concept	Term	ID Prefix	Description
Container	Group	`g_`	The coordination space where AIs collaborate on a project
Leader	Ops (Ops Manager)	`o_`	The AI in charge - voices to user, delegates tasks, can have multiple
Worker	Agent	`a_`	Silent worker AI - receives tasks, executes, reports back
Comms Line	Channel	`ch_`	Direct communication line between Ops and Agent

Architecture

Group: g_tfno "Multi-Tenant Implementation"
├── Ops: o_c9um (Terminal 1 - voices to Chris, delegates)
├── Ops: o_xyz2 (Terminal 2 - co-ops, can also delegate)
├── Agent: a_abc1 (Terminal 3 - silent worker)
├── Agent: a_def2 (Terminal 4 - silent worker)
└── Channels:
    ├── ch_001: o_c9um ↔ a_abc1
    ├── ch_002: o_c9um ↔ a_def2
    ├── ch_003: o_xyz2 ↔ a_abc1 (ops can share agents)
    └── ch_004: o_c9um ↔ o_xyz2 (ops-to-ops communication)

Two Entry Points

/recover - For Ops and Solo Work

Full Nexus memory
Voice protocols enabled
Session history, track projects
Can see open groups and choose to join as Ops
For: Running the show, direct user interaction

/crew - For Agents Only

Minimal context
NO voice protocols
NO track projects, session history
Just: User ID (security), auto tools, aimsg tools, wait instructions
Immediately joins group and waits for Ops
For: Silent task execution

Agent Workflow

User runs /crew in new terminal
Claude gets minimal context + group info
Auto-joins group → gets a_XXXX ID
Calls aimsg.wait(group_id, my_id) → BLOCKS
Ops sends task → Agent wakes up
Agent does work using auto.* tools (bypasses UI approval)
Agent sends report via aimsg.send()
Agent calls aimsg.wait() again
Repeat until group closes

Ops Workflow

User runs /recover in terminal
Claude gets full Nexus context
Creates group or joins existing as Ops
Voices to user, plans work
Delegates tasks to Agents via aimsg.send()
Can aimsg.wait() for Agent reports
Verifies work, assigns next tasks
When approaching context limit → open new terminal, /recover, transfer

Key Tools

Auto Tools (bypass UI approval)

auto.read - Read files
auto.write - Write files
auto.edit - Edit files
auto.bash - Run commands
auto.mkdir - Create directories

AImsg Tools

aimsg.initiate - Create new group (becomes Ops)
aimsg.join - Join group (as Ops or Agent)
aimsg.send - Send message
aimsg.wait - Block until message arrives
aimsg.read - Read channel history
aimsg.pending - Check unread messages
aimsg.transfer_initiator - Hand off Ops role

Critical Rules for Agents

❌ NO voice output - only Ops speaks to user
❌ NO polling loops - use aimsg.wait()
❌ NO Claude built-in tools - use auto.*
✅ Wait silently for tasks
✅ Execute with auto tools
✅ Report completion
✅ Wait again

Server Rename Consideration

Current: aimsg (AI messaging) Proposed: aigroups or groups

This better reflects the Group/Ops/Agent/Channel model.

Migration Notes

Old IDs: m_ (mission/coordination), i_ (initiator), p_ (participant)
New IDs: g_ (group), o_ (ops), a_ (agent), ch_ (channel)
Existing coordinations will need migration script
Server code needs ID prefix updates