Gabe Autonomous Slack Agent

Gabe is a focused autonomous agent that inhabits a dedicated Slack user account and collaborates inside a set of shared TrustedWork workspaces. The project bundles opinionated defaults so you can:

• bootstrap a Slack App with Bot + Socket Mode permissions
• run an always-on agent that triages mentions, channel messages, and DM requests
• enforce a lightweight "trust mesh" via workspace allow-lists and volition tracking

Why this exists: the earlier prototype generated by ChatGPT 4o only created placeholders. This version fills in the missing plumbing, adds tests, and documents the full setup so you can launch Gabe confidently.

✨ Features

• Socket Mode Slack bot that runs anywhere (local dev or server)
• Workspace allow-list to keep the agent scoped to trusted orgs
• Volition core that remembers recent orders and prevents duplicate actions
• Structured logging with correlation IDs for easier debugging
• Extensible command router for future skills

🧱 Project layout

├── config/
│   └── .env.example         # copy to .env with your Slack secrets
├── notebooks/
│   └── ep1_gabe_autonomous_slack_init.ipynb
├── src/
│   ├── gabe_bot.py          # entrypoint and Slack event handlers
│   ├── utils.py             # config loading + logging helpers
│   └── volition_core.py     # stateful volition/trust mesh logic
├── tests/
│   └── test_volition_core.py
├── requirements.txt
└── README.md

🚀 Quick start

1. Clone the repo

   git clone https://github.com/twdevjim/gabe-autonomous-slack-agent.git
   cd gabe-autonomous-slack-agent

2. Create and activate a virtualenv (recommended)

   python3 -m venv .venv
   source .venv/bin/activate

3. Install dependencies

   pip install -r requirements.txt

4. Copy the env template and populate secrets

   cp config/.env.example .env

   Fill in:

   • SLACK_BOT_TOKEN – Bot User OAuth token (xoxb-...)
   • SLACK_APP_TOKEN – App-level token (xapp-...) with Socket Mode enabled
   • SLACK_SIGNING_SECRET – verifies events from Slack
   • GABE_HOME_CHANNEL – optional channel ID for heartbeat announcements
   • TRUSTED_WORKSPACE_IDS – optional comma list of workspace/team IDs Gabe may serve

5. Run the bot

   python -m src.gabe_bot

   The bot starts a Socket Mode client, posts a heartbeat to the home channel (if configured), and listens for mentions or DMs.

🛠 Slack app configuration checklist

Inside https://api.slack.com/apps:

1. Create a new app From scratch using the dedicated Gabe Slack account.
2. Enable Socket Mode and create the App-level token (scope: connections:write).
3. Under OAuth & Permissions, add bot scopes:
   • app_mentions:read
   • channels:history
   • chat:write
   • commands
   • groups:history
   • im:history
   • im:read
   • im:write
   • mpim:history
4. Install the app to each TrustedWork workspace where Gabe must operate.
5. If you want slash commands (e.g., /gabe), add them under Slash Commands pointing to https://slack.com and handle them in src/gabe_bot.py.

You can find workspace IDs by opening Slack in a browser → View source → search for team_id, or by invoking auth.test via the Slack Web API.

🧠 Volition & trust mesh

VolitionCore keeps track of the agent’s recent orders. It prevents duplicate execution, throttles rapid-fire commands, and annotates responses with a short memory trail. The current implementation stores state in-memory; extend it to Redis or a database for multi-process deployments.

🧪 Testing

Run the included tests to ensure the volition logic behaves:

pytest

To run lint checks (optional but recommended):

ruff check src

🧭 Extending Gabe

• Add new command handlers in src/gabe_bot.py inside register_routes().
• Persist volition state by subclassing InMemoryVolitionStore in volition_core.py.
• Integrate external tools by calling APIs inside the VolitionCore.handle_intent method.

🔒 Security hygiene

• Never commit the real .env file; use the provided template.
• Rotate Slack tokens periodically and restrict scopes to the bare minimum.
• If you use GitHub Actions or another CI platform, inject secrets via environment variables, not plaintext files.

📚 Troubleshooting

Symptom	Fix
invalid_auth on startup	Re-issue the Bot token and update .env.
Bot connects but doesn't respond	Ensure the bot was invited to the channel and has chat:write scope.
team_not_in_required_teams warnings	Update TRUSTED_WORKSPACE_IDS with the workspace ID or leave it blank.

Happy hacking with Gabe! Ship improvements back via PRs so the ecosystem can benefit.