add-skill-imap-read

Add IMAP Email Reader

Read-only email access for agent containers via IMAP. Supports multiple providers simultaneously.

Preflight

Before installing, verify NanoTars is set up:

[ -d node_modules ] && echo "DEPS: ok" || echo "DEPS: missing"
docker image inspect nanoclaw-agent:latest &>/dev/null && echo "IMAGE: ok" || echo "IMAGE: not built"
if grep -q "ANTHROPIC_API_KEY\|CLAUDE_CODE_OAUTH_TOKEN" .env 2>/dev/null || [ -f "$HOME/.claude/.credentials.json" ]; then echo "AUTH: ok"; else echo "AUTH: missing"; fi

If any check fails, tell the user to run /nanotars-setup first and stop.

Prerequisites

• For Gmail: 2-Step Verification enabled on the Google Account
• For Yahoo: Account Security settings accessible

Install

1. Check existing configuration:

   grep "^IMAP_READ_ACCOUNTS=" .env 2>/dev/null && echo "ALREADY_CONFIGURED" || echo "NEEDS_SETUP"
   ls plugins/imap-read/plugin.json 2>/dev/null && echo "PLUGIN_EXISTS" || echo "NO_PLUGIN"
   

   If ALREADY_CONFIGURED, ask the user if they want to add another account or reconfigure.

2. Gather account details for each email provider. Collect:

   • Provider name (e.g., "Gmail", "Yahoo", "Work")
   • IMAP host (auto-fill based on provider):
     • Gmail: imap.gmail.com
     • Yahoo: imap.mail.yahoo.com
     • Outlook/Hotmail: outlook.office365.com
     • Other: ask for the IMAP server address
   • Email address (username for IMAP login)
   • App password (NOT the regular account password)

   App Password Instructions

   Gmail:

   1. Go to https://myaccount.google.com/apppasswords
   2. You must have 2-Step Verification enabled
   3. Select "Other" as the app name, enter "NanoTars"
   4. Copy the 16-character password (spaces don't matter)

   Yahoo:

   1. Go to https://login.yahoo.com/account/security
   2. Click "Generate app password"
   3. Select "Other app", enter "NanoTars"
   4. Copy the generated password

   Outlook/Hotmail:

   1. Go to https://account.microsoft.com/security
   2. Under "Additional security", enable 2-Step Verification if not already
   3. Go to "App passwords" > Create a new app password
   4. Copy the generated password

3. Build IMAP_READ_ACCOUNTS JSON array and save to .env:

   sed -i '/^IMAP_READ_ACCOUNTS=/d' .env
   echo 'IMAP_READ_ACCOUNTS=[{"name":"Gmail","host":"imap.gmail.com","port":993,"user":"user@gmail.com","pass":"xxxx xxxx xxxx xxxx"}]' >> .env
   

   (Substitute actual account details. JSON must be on a single line.)

4. Test credentials before deploying:

   python3 -c "
   import imaplib, json
   accounts = json.loads('''THE_JSON_ARRAY_HERE''')
   for a in accounts:
       try:
           m = imaplib.IMAP4_SSL(a['host'], a.get('port', 993))
           m.login(a['user'], a['pass'])
           m.select('INBOX', readonly=True)
           _, data = m.search(None, 'UNSEEN')
           count = len(data[0].split()) if data[0] else 0
           print(f\"{a['name']}: OK - {count} unread emails\")
           m.close(); m.logout()
       except Exception as e:
           print(f\"{a['name']}: FAILED - {e}\")
   "
   

5. Plugin Configuration -- Ask the user which groups should have access to email reading:

   • All groups (default) -- every group's agent can read emails
   • Specific groups only -- e.g., only main

   If the user wants to restrict access, update plugins/imap-read/plugin.json after copying (step 6) to set "groups" to the list of group folder names:

   "groups": ["main"]
   

   If all groups (or the user doesn't care), leave as "groups": ["*"].

   Restricting access means only those groups' agents will have email reading tools. Other groups won't see the IMAP tools or credentials.

   Also ask about channel types. If the user wants this plugin available on all channel types (WhatsApp, Discord, etc.), leave "channels": ["*"]. To restrict, set "channels" to specific types (e.g., ["whatsapp"]). Most users will want the default.

6. Copy plugin files:

   cp -r ${CLAUDE_PLUGIN_ROOT}/files/ plugins/imap-read/
   

7. Rebuild and restart:

   npm run build
   nanotars restart  # or launchctl on macOS
   

Verify

Tell the user:

Email access is configured. Test it by sending a WhatsApp message like "check my email" or "how many unread emails do I have?"

Troubleshooting

• "IMAP_READ_ACCOUNTS not defined" in container: Check that plugins/imap-read/plugin.json exists with the correct containerEnvVars, and that .env has the variable set.
• Authentication failures: App passwords expire if the account password changes. Regenerate and re-run this skill.
• Gmail blocks access: Ensure 2-Step Verification is ON and you're using an app password.
• Timeout errors: Some corporate IMAP servers require VPN.

Existing Installation (Per-Group Credentials)

If this plugin is already installed and you want different credentials for a specific group (e.g., a work account for one group, personal for another):

1. Check which groups exist:

   ls -d groups/*/
   

2. Ask the user which group should get separate credentials.

3. Collect the new IMAP email accounts for that group.

4. Write to the group's .env file (creates if needed):

   echo 'IMAP_READ_ACCOUNTS=[{"name":"Work","host":"imap.gmail.com","port":993,"user":"work@company.com","pass":"app-password"}]' >> groups/{folder}/.env
   

   These values override the global .env for that group's containers only.

5. Restart NanoTars:

   nanotars restart
   

Remove

1. rm -rf plugins/imap-read/
2. Remove env vars from .env:

   sed -i '/^IMAP_READ_ACCOUNTS=/d' .env
   

3. Rebuild and restart.
4. Revoke app passwords in each provider's security settings.