aim-marketplace

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