joe-swarm

Summary

OpenClaw Joe is a shell-based agent swarm orchestrator for personal productivity automation. It coordinates autonomous agents for messaging (Gmail), scheduling (Google Calendar), and persistent memory (Open Brain), driven via tmux sessions, codex/Claude endpoints, cron jobs, and shell scripts. Internal workflows use heartbeat checks, code review, and integration with GitHub CI.

Included Assets

• Agent Protocol & State

  • AGENTS.md: Agent workspace and execution protocol
  • SOUL.md: Agent identity and boundaries
  • MEMORY.md: Open Brain/Telegram/DB technical context
  • memory/: Daily log files and heartbeat state

• Automation & Scheduling

  • skills/calendar/: Google Calendar integration
    • calendar.sh: Shell CLI for calendar read/create/update/delete
    • SKILL.md: Usage guidelines and boundary enforcement

• Messaging

  • skills/gmail/: Gmail integration
    • gmail.sh: Shell CLI for inbox management
    • scan-emails.py, send-email.py: Python scripts for scanning and sending
    • SKILL.md: Use-case guidance, boundaries, and API rules

• Persistent Memory

  • skills/open-brain-capture.sh: Capture thoughts/action items to Open Brain
  • skills/open-brain-tasks.sh: Manage tasks via Open Brain MCP API

• Obsidian Vault Sync

  • obsidian/README.md: Personal business vault integration (meetings, logs)

• Self-improving Agent Tools

  • skills/self-improving-agent/.clawhub/origin.json: Version metadata

How to Use

1. Prepare Your Workspace

   • Read SOUL.md (who Joe is) and MEMORY.md (context, DB info).
   • Review daily logs in memory/YYYY-MM-DD.md for continuity.
   • All operations are sandboxed: workspace scripts only interact with allowed APIs and shells.

2. Agent Operations & Protocols

   • Follow action/heartbeat/triage routines as described in AGENTS.md.
   • Use the CLI scripts to interact with Gmail and Calendar:
     • ./skills/gmail/scripts/gmail.sh unread — check unread Gmail
     • ./skills/calendar/scripts/calendar.sh today — list today's events
     • ./skills/open-brain-capture.sh "thought text" — store a memory

3. Automation & Scheduling

   • Cron or heartbeat loops run common routines (inbox, calendar, tasks).
   • Scripts support both manual triggering and automation.

4. Memory & Logs

   • All key agent actions, states, and logs persist in memory/ and the SQL database.
   • Messages sent/received and decisions made are captured for long-term recall.

5. Team Vault & Search

   • Obsidian vault (obsidian/) can be searched or updated via provided CLI.
   • Links between logs, tasks, and business context are maintained for traceability.

Notes

• Actions requiring external access are sandboxed; outbound operations beyond the workspace require explicit user permission and are mediated via specific tools.
• Calendar and email usage are strictly governed by skill boundaries—scripts must only act on direct user request or in designated agent heartbeats (see individual SKILL.md for precise rules).
• All environment secrets (OAuth tokens, DB keys) are expected via environment files not included in the repo.
• Joe is designed for persistence, reliability, and respectful handling of sensitive tasks—see SOUL.md for the full conduct and responsibility code.