---
name: transfer-pack
description: "Send a transfer packet to a remote Hermes agent with file delivery and notification support."
version: 1.2.0
metadata:
  hermes:
    tags: [transfer, agent-communication, scp, cron]
---

# Transfer Pack

Send a transfer packet (files + letter) to a remote Hermes Agent instance. The recipient agent reads the letter and responds via their configured notification platform.

## Prerequisites

- SSH key access to recipient agent's server
- `mcp_ssh` tool available (SSH-MCP)
- Hermes cron support on both agents (for notifications)

## Configuration

Before using, identify from context or AGENTS.md:

| Variable | Source |
|----------|--------|
| SENDER_NAME | Your agent name |
| RECIPIENT_NAME | Target agent name from AGENTS.md |
| RECIPIENT_SSH_HOST | Tailscale address from AGENTS.md |
| RECIPIENT_SSH_USER | SSH username for recipient server |
| RECIPIENT_NOTIFICATION | Notification platform from AGENTS.md (discord/telegram/slack/none) |
| USER_NAME | Human operator's name (for acknowledgment) |

## Procedure

### Step 1: Parse the prompt

Identify:
- The **topic** (succinct kebab-case keyword from the user's prompt)
- The **files to include** (from context — code, docs, configs, etc.)
- The **instructions for the recipient** (what they should do with the contents)

### Step 2: Create the transfer packet directory

```bash
mkdir -p /tmp/transfer-packs/YYYY-MM-DD-<topic>
```

Use today's date and the succinct topic. Example: `2026-05-08-agent-coordination`

### Step 3: Copy relevant files into the directory

Copy all files referenced in the prompt into the packet directory. Use `cp` or `write_file` as appropriate.

If no files needed, just create the LETTER.md.

### Step 4: Write LETTER.md

Write `LETTER.md` in the packet directory with this structure:

```markdown
# Transfer Packet: <Topic>

**From:** <SENDER_NAME> (Hermes Agent)
**To:** <RECIPIENT_NAME> (Hermes Agent)
**Date:** YYYY-MM-DD
**Topic:** <topic>

---

<Personal letter addressing the recipient. Explain:>
- What's in this packet
- Why it's being sent
- What the recipient should do with it
- Any specific instructions or context needed

**At the end, include this line:**
"Please inform <USER_NAME> that this transfer was successful and include a brief summary of what you received."
```

The letter MUST end with the instruction to inform the user of success.

### Step 5: Create the tarball

```bash
cd /tmp/transfer-packs && tar czf YYYY-MM-DD-<topic>.tar.gz YYYY-MM-DD-<topic>/
```

### Step 6: SCP the tarball to the recipient

```bash
scp -o StrictHostKeyChecking=no /tmp/transfer-packs/YYYY-MM-DD-<topic>.tar.gz <RECIPIENT_SSH_USER>@<RECIPIENT_SSH_HOST>:~/
```

### Step 7: Extract the tarball on the recipient server

Use SSH-MCP (`mcp_ssh_execute_command`):

```bash
cd ~ && tar xzf YYYY-MM-DD-<topic>.tar.gz
```

### Step 8: Create notification for the recipient

Check the recipient's `Notification` field in AGENTS.md:

| Notification | Action |
|--------------|--------|
| `discord` | Use `--deliver discord` |
| `telegram` | Use `--deliver telegram` |
| `slack` | Use `--deliver slack` |
| `none` | Skip cron notification, warn sender |

**If recipient has a notification platform:**

Use SSH-MCP to run:

```bash
hermes cron create \
  --name "transfer-ack-<topic>" \
  --deliver <platform> \
  --repeat 1 \
  1m \
  "New transfer packet from <SENDER_NAME>. Please read ~/YYYY-MM-DD-<topic>/LETTER.md and follow the instructions inside."
```

This creates a one-shot cron job that:
- Runs in ~1 minute
- Triggers the recipient agent with the notification prompt
- Delivers the response to the specified platform
- Auto-removes after running once (`--repeat 1`)

**If recipient has `Notification: none`:**

Skip the cron job. Inform the sender:
```
Recipient <RECIPIENT_NAME> has no notification platform configured.
Packet delivered to ~/YYYY-MM-DD-<topic>/LETTER.md but no automatic notification sent.
You may need to manually notify the recipient.
```

**Note:** The cron ticker runs at 60s intervals, so it may take 1-2 minutes for the job to fire.

### Step 9: Confirm to user

Report:
- Packet directory name
- Files included
- That the cron notification was created
- Expected delivery timeframe (~1-2 minutes)

## Cleanup

After confirming the transfer, clean up local temp files:

```bash
rm -rf /tmp/transfer-packs/YYYY-MM-DD-<topic> /tmp/transfer-packs/YYYY-MM-DD-<topic>.tar.gz
```

The recipient should clean up their copy after reading the letter.

## Pitfalls

- **Do NOT use `hermes -z` or `hermes chat -q`** — those output to stdout only, not Discord. Always use the cron mechanism with `--deliver <platform>`.
- **Do NOT try to message the recipient's Discord bot directly** — Discord bots cannot see messages from other bots.
- **The `--repeat 1` flag is required** — without it, the job runs indefinitely.
- **Schedule format:** Use `1m` (relative offset), not `now`. The cron ticker picks it up on the next tick.
- **SCP requires SSH key auth** — ensure `~/.ssh/authorized_keys` is set up on the recipient server for the sending agent's key.
- **Files must be in the tarball** — don't assume the recipient has access to your filesystem. Copy everything into the packet directory.
- **Hardcoded names** — always derive SENDER_NAME, RECIPIENT_NAME, and USER_NAME from context or AGENTS.md, never hardcode them.
- **Notification platform** — check AGENTS.md for the recipient's `Notification` field. Use the corresponding `--deliver` flag. If `none`, skip the cron job and warn the sender.

## Integration with agent-coordination

For agents using the `agent-coordination` repository:

1. Parse `~/.hermes/agent-coordination/AGENTS.md` (or equivalent path) to resolve recipient names to SSH hosts and users
2. Use `~/.hermes/agent-coordination/PERSONALITY.md` for shared behavioral context
3. The sender's name should match their entry in AGENTS.md