aim

AIM — Agent Instant Messenger


A Claude Code plugin for multi-agent collaboration. Run multiple Claude Code agents across local and remote workspaces in a single conversation — with automatic push notifications when agents respond.

Install

claude plugin install --from "https://raw.githubusercontent.com/the-vampiire/agent-instant-messenger/master/.claude-plugin/plugin.json"

Quick Start

# Add an agent (creates a session automatically)
/aim:add /path/to/other-project

# Talk to it
@other-project what are you working on?

# The response is delivered automatically — no polling needed

Usage

Add agents

/aim:add /path/to/project              # local workspace
/aim:add /path/to/project:api          # local with alias
/aim:add user@host:/path/to/project    # remote via SSH
/aim:add user@host:/path/to/project:prod-api  # remote with alias

Agent names are derived from the last directory component unless you provide an alias after :.

Talk to agents

@agent-name do something              # message a specific agent
@all what's the status?               # broadcast to all agents (you respond too)

After sending a message, a background sidecar automatically polls for the response and delivers it to your session when it arrives. No manual checking needed.

Manage the session

/aim:status                            # agents, message counts, activity, config
/aim:set @agent permission_mode bypassPermissions  # skip permission prompts
/aim:set @agent timeout_ms 600000      # 10 minute timeout
/aim:set break_timeout_ms 300000       # sidecar polls for 5 min before giving up

How It Works

Terminal A (you)                       Terminal B (agent workspace)
─────────────────                      ──────────────────────────
@backend deploy to staging
  │
  ├─ aim_send fires
  ├─ PostToolUse hook spawns           claude --print runs in
  │  aim-sidecar in background         /path/to/backend workspace
  │                                      │
  │  sidecar polls aim_check ←──────── response written to
  │  every 5 seconds                   shared history.jsonl
  │                                      │
  ├─ sidecar detects new message ◄─────┘
  ├─ delivers to your session
  │
  ▼
@backend: Deployed to staging.
Build #47, all checks passed.

Key concepts

• Sessions — Created automatically on first /aim:add. Tracks agents, history, and config. Stored at ~/.claude/aim/sessions/<id>/.
• DEFAULT_AGENT — Your current Claude Code session. You're a participant too — @all messages include you.
• Fire-and-forget delivery — aim_send returns immediately. The agent runs in the background via claude --print.
• Sidecar push notifications — A background subagent polls aim_check and delivers responses automatically when they arrive.
• Session upsert — Agents resume their most recent Claude Code session in the target workspace, preserving context across messages.

MCP Tools

| Tool | Description | |------|-------------| | aim_add | Add an agent to the session (creates session if needed) | | aim_send | Send a message to a specific agent | | aim_broadcast | Send a message to all agents | | aim_set | Configure agent permissions, timeouts, or session settings | | aim_history | View or search conversation history | | aim_sessions | List all sessions with workspace info | | aim_status | Show current session status and config | | aim_check | Poll for new messages (used internally by sidecar) |

Workspace Path Formats

| Format | Example | |--------|---------| | Local | /home/user/projects/backend | | Local + alias | /home/user/projects/backend:api | | SSH | deploy@prod:/app/backend | | SSH + alias | deploy@prod:/app/backend:prod-api |

Configuration

Agent settings (via aim_set)

| Setting | Values | Default | |---------|--------|---------| | permission_mode | default, acceptEdits, bypassPermissions, plan | default | | timeout_ms | Any number >= 1000 | 300000 (5 min) |

Session settings (via aim_set)

| Setting | Values | Default | |---------|--------|---------| | break_timeout_ms | Any number >= 10000 | 120000 (2 min) |

The break timeout controls how long the sidecar polls for a response before giving up. Increase it for agents that take a long time to respond.

Architecture

AIM runs as an MCP server (stdio) with 8 tools. Your Claude Code session is the coordinator. Other agents are spawned via claude --print (local) or over SSH (remote).

~/.claude/aim/
└── sessions/
    └── <uuid>/
        ├── session.json      # agents, config, metadata
        ├── history.jsonl     # public message log
        ├── audit.jsonl       # full log including private messages
        └── check-state.json  # sidecar polling state

SSH agents

For SSH agents, AIM: 1. Probes the remote host for the claude binary path (interactive login shell, then common locations) 2. Finds the most recent Claude Code session in the remote workspace 3. Runs claude --print --resume <session> over SSH with BatchMode=yes

Requires passwordless SSH access (key-based auth) to the remote host.

License

MIT