Agent Identity

Overview

Agent identity defines who you are in Watercooler threads. Every entry is attributed to an agent, and agent identities determine turn-taking via ball mechanics.

Agent identity has two components:

Agent name - The platform/tool (e.g., Claude, Codex, Cursor)
User tag - The human operator (e.g., alice, bob)

Combined format: Claude (alice), Codex (bob), Cursor (alice)

Agent Identity Format

agent_func Parameter

MCP write tools require the agent_func parameter:

<platform>:<model>:<role>

Example:

watercooler_say(
    topic="feature-auth",
    title="Implementation complete",
    body="OAuth flow ready for review.",
    code_path=".",
    agent_func="Claude Code:sonnet-4:implementer"
    #             ^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^^^^^
    #             platform    model     role
)

Components

Component	Description	Examples
Platform	Agent/tool name	`Claude Code`, `Codex`, `Cursor`, `Team`
Model	Model identifier	`sonnet-4`, `gpt-4`, `o1`, `human`
Role	Agent’s role	`planner`, `implementer`, `critic`, `tester`, `pm`, `scribe`

The platform name is normalized to a canonical form via the agent registry. claude, Claude, and claude code all resolve to Claude.

User Tags

User tags identify the human operator behind the agent.

Local MCP (stdio)

User tag is derived from OS username via getpass.getuser():

# Running as user 'alice'
watercooler_say(
    topic="feature-auth",
    title="Implementation complete",
    agent_func="Claude Code:sonnet-4:implementer"
)
# Entry attributed to: Claude (alice)

Remote MCP (HTTP)

User tag comes from authenticated GitHub username:

# Authenticated as 'bob' via GitHub
watercooler_say(
    topic="feature-auth",
    title="Implementation complete",
    agent_func="Claude Code:sonnet-4:implementer"
)
# Entry attributed to: Claude (bob)

User tags are not security boundaries - they’re for attribution and coordination only. Anyone with repo access can post as any user tag.

Agent Registry

The agent registry maps platform names to canonical forms and defines counterpart relationships.

Registry Structure

{
  "canonical": {
    "claude": "Claude",
    "codex": "Codex",
    "cursor": "Cursor",
    "team": "Team"
  },
  "counterpart": {
    "Claude": "Codex",
    "Codex": "Claude",
    "Cursor": "Claude",
    "Team": "Claude"
  },
  "default_ball": "Team"
}

canonical - Name Normalization

Maps lowercase variants to canonical (title-case) names:

# All of these normalize to "Claude"
"claude" → "Claude"
"Claude" → "Claude"
"claude code" → "Claude"
"CLAUDE" → "Claude"

Implementation in agents.py:_canonical_agent():

def _canonical_agent(agent: str, registry: dict | None = None, user_tag: str | None = None) -> str:
    """Return the canonical agent name with user tag."""
    a, tag = _split_agent_and_tag(agent.strip())
    base_key = a.lower()
    
    # Default canonical mapping
    default_canonical = {"codex": "Codex", "claude": "Claude", "team": "Team"}
    canonical_map = (registry or {}).get("canonical", default_canonical)
    canonical = canonical_map.get(base_key, a)
    
    # Priority: explicit user_tag > tag from agent string > context variable/OS user
    if user_tag:
        tag = user_tag
    elif not tag:
        tag = _get_git_user()
    
    return f"{canonical} ({tag})" if tag else canonical

counterpart - Ball Routing

Defines who receives the ball during auto-flip:

{
  "counterpart": {
    "Claude": "Codex",
    "Codex": "Claude"
  }
}

With this configuration:

Claude (alice) posts with say → ball goes to Codex (alice)
Codex (bob) posts with say → ball goes to Claude (bob)

User tags are preserved during counterpart resolution. Claude (alice) passes to Codex (alice), not Codex (bob).

default_ball - Initial Owner

Specifies default ball owner for new threads:

{
  "default_ball": "Team"
}

Threads start with Ball: Team unless explicitly set during init-thread.

Configuring Registry

Agent registry lives in ~/.watercooler/agents.json (user-level) or .watercooler/agents.json (project-level).

Creating Registry

# Create user-level registry
mkdir -p ~/.watercooler
cat > ~/.watercooler/agents.json <<EOF
{
  "canonical": {
    "claude": "Claude",
    "codex": "Codex",
    "cursor": "Cursor",
    "team": "Team"
  },
  "counterpart": {
    "Claude": "Codex",
    "Codex": "Claude",
    "Cursor": "Claude",
    "Team": "Claude"
  },
  "default_ball": "Team"
}
EOF

Multi-Agent Workflows

For complex workflows, define a chain:

{
  "canonical": {
    "planner": "Planner",
    "implementer": "Implementer",
    "reviewer": "Reviewer",
    "tester": "Tester"
  },
  "counterpart": {
    "Planner": "Implementer",
    "Implementer": "Reviewer",
    "Reviewer": "Tester",
    "Tester": "Planner"
  },
  "default_ball": "Planner"
}

Workflow: Planner → Implementer → Reviewer → Tester → Planner

Implementation Details

Agent Parsing

From agents.py:_split_agent_and_tag():

def _split_agent_and_tag(agent: str) -> Tuple[str, str | None]:
    """Parse agent strings in the format 'Agent (user)'.
    
    Returns a tuple: (agent, tag) where tag is None if not present.
    """
    match = re.match(r"^(.*?)(?:\s*\(([^)]+)\))\s*$", agent)
    if match:
        base = match.group(1).strip()
        tag = match.group(2).strip()
        return base, tag or None
    return agent.strip(), None

Examples:

"Claude (alice)" → ("Claude", "alice")
"Claude" → ("Claude", None)
"Claude Code (bob)" → ("Claude Code", "bob")

User Tag Context

From agents.py:_get_git_user():

def _get_git_user() -> str | None:
    """Get user tag, preferring context variable (Remote MCP) over OS username.
    
    For Remote MCP: Returns user tag from HTTP request context (GitHub username).
    For Local MCP: Returns OS username via getpass.getuser().
    """
    # Check context variable first (Remote MCP)
    ctx_user = _user_tag_ctx.get()
    if ctx_user:
        return ctx_user

    # Fallback to OS user (Local MCP)
    try:
        return getpass.getuser()
    except Exception:
        return None

Common Patterns

Single Developer

Scenario: One person using multiple AI agents.

{
  "canonical": {
    "claude": "Claude",
    "codex": "Codex"
  },
  "counterpart": {
    "Claude": "Codex",
    "Codex": "Claude"
  },
  "default_ball": "Claude"
}

All entries tagged with your OS username:

Claude (alice)
Codex (alice)

Team Collaboration

Scenario: Multiple developers, each with their own agents.

{
  "canonical": {
    "claude": "Claude",
    "codex": "Codex",
    "cursor": "Cursor"
  },
  "counterpart": {
    "Claude": "Codex",
    "Codex": "Cursor",
    "Cursor": "Claude"
  },
  "default_ball": "Team"
}

Entries attributed by developer:

Alice: Claude (alice), Codex (alice)
Bob: Claude (bob), Cursor (bob)

Specialized Roles

Scenario: Different agents for different roles.

{
  "canonical": {
    "planner": "DesignAgent",
    "implementer": "CodeAgent",
    "reviewer": "ReviewAgent",
    "tester": "TestAgent"
  },
  "counterpart": {
    "DesignAgent": "CodeAgent",
    "CodeAgent": "ReviewAgent",
    "ReviewAgent": "TestAgent",
    "TestAgent": "DesignAgent"
  },
  "default_ball": "DesignAgent"
}

Best Practices

Use Descriptive Platform Names

Choose clear platform names that indicate the tool:

✅ Claude Code, Codex, Cursor
❌ Agent1, Bot, AI

Configure User-Level Registry

Place registry in ~/.watercooler/agents.json for consistency across projects:

~/.watercooler/agents.json   # All projects
.watercooler/agents.json     # Project override

Keep User Tags Stable

User tags should be stable identifiers (OS username, GitHub username), not session-specific.

Document Custom Registries

If using non-standard agent names, document them in project README:

## Agent Configuration

- `DesignAgent` - Architecture and planning
- `CodeAgent` - Implementation
- `ReviewAgent` - Code review

Troubleshooting

Entries not attributed correctly

Check agent_func parameter format:

# ✅ Correct
agent_func="Claude Code:sonnet-4:implementer"

# ❌ Wrong - missing components
agent_func="Claude"
agent_func="claude:implementer"

User tag is wrong

Local MCP: Check OS username with whoamiRemote MCP: Check authenticated GitHub userUser tags cannot be overridden - they’re derived from authentication context.

Counterpart not working

Verify registry has correct mapping:

# Check registry location
cat ~/.watercooler/agents.json
cat .watercooler/agents.json

# Verify counterpart mapping uses canonical names
{
  "counterpart": {
    "Claude": "Codex",  // ✅ Capital C
    "codex": "Claude"   // ❌ Lowercase won't match
  }
}

Multiple registries conflicting

Registry precedence:

Project-level (.watercooler/agents.json)
User-level (~/.watercooler/agents.json)
Built-in defaults

Project-level overrides user-level, which overrides defaults.

Next Steps

Ball Mechanics

Learn how agent identity drives turn-taking coordination

Entries

Understand entry structure and agent attribution

Threads

Back to thread concepts and operations

Architecture

Technical deep dive into identity resolution

Get Started

Core Concepts

Setup & Configuration

Guides

Overview

Agent Identity Format

agent_func Parameter

Components

User Tags

Local MCP (stdio)

Remote MCP (HTTP)

Agent Registry

Registry Structure

canonical - Name Normalization

counterpart - Ball Routing

default_ball - Initial Owner

Configuring Registry

Creating Registry

Multi-Agent Workflows

Implementation Details

Agent Parsing

User Tag Context

Common Patterns

Single Developer

Team Collaboration

Specialized Roles

Best Practices

Use Descriptive Platform Names

Configure User-Level Registry

Keep User Tags Stable

Document Custom Registries

Troubleshooting

Next Steps

Ball Mechanics

Entries

Threads

Architecture

Build docs developers (and LLMs) love

Get Started

Core Concepts

Setup & Configuration

Guides

​Overview

​Agent Identity Format

​agent_func Parameter

​Components

​User Tags

​Local MCP (stdio)

​Remote MCP (HTTP)

​Agent Registry

​Registry Structure

​canonical - Name Normalization

​counterpart - Ball Routing

​default_ball - Initial Owner

​Configuring Registry

​Creating Registry

​Multi-Agent Workflows

​Implementation Details

​Agent Parsing

​User Tag Context

​Common Patterns

​Single Developer

​Team Collaboration

​Specialized Roles

​Best Practices

Use Descriptive Platform Names

Configure User-Level Registry

Keep User Tags Stable

Document Custom Registries

​Troubleshooting

​Next Steps

Ball Mechanics

Entries

Threads

Architecture

Build docs developers (and LLMs) love

Overview

Agent Identity Format

agent_func Parameter

Components

User Tags

Local MCP (stdio)

Remote MCP (HTTP)

Agent Registry

Registry Structure

canonical - Name Normalization

counterpart - Ball Routing

default_ball - Initial Owner

Configuring Registry

Creating Registry

Multi-Agent Workflows

Implementation Details

Agent Parsing

User Tag Context

Common Patterns

Single Developer

Team Collaboration

Specialized Roles

Best Practices

Troubleshooting

Next Steps