feat: Add Slack integration support

[grimesp]

Slack Integration Feasibility Analysis

Overview

Exploring what it would take to add Slack support to the assistant CLI alongside the existing Google services (Gmail, Calendar, Sheets, Drive).

Current Architecture Assessment

What's Reusable (60-70% of auth.py)

• Multi-account system: Token storage per account, active account tracking, account switching
• Config management: JSON-based config in ~/.config/assistant/
• Directory structure: tokens/ folder pattern works for any provider
• CLI patterns: Typer commands, Rich display utilities, client/commands separation

What's Google-Specific (needs abstraction)

• OAuth flow: Uses google_auth_oauthlib.InstalledAppFlow
• Credentials object: google.oauth2.credentials.Credentials
• Token refresh: Google's refresh mechanism
• Email discovery: Queries Gmail API to get account email
• Scopes: Hardcoded Google URLs in SCOPES list

Slack API Overview

Authentication Model

Slack uses Bot Tokens (xoxb-...) rather than user OAuth for most use cases:

• Bot tokens are tied to the app, not a specific user
• Simpler than user OAuth - no refresh tokens needed
• Tokens don't expire (unless revoked)
• Requires creating a Slack App at api.slack.com

Key Bot Token Scopes

Scope	Purpose
chat:write	Post messages in channels the bot is in
chat:write.public	Post to any public channel
channels:read	List public channels
channels:history	Read message history
groups:read	List private channels bot is in
im:read / im:write	Direct messages
users:read	List workspace users
files:read / files:write	Upload/download files
reactions:read / reactions:write	Emoji reactions

Python SDK Options

1. slack-sdk (official) - Low-level API wrapper
2. slack-bolt - Higher-level framework with built-in OAuth handling

Proposed Slack Commands

# Channels
assistant slack channels                    # List channels
assistant slack channels --private          # Include private channels

# Messages
assistant slack send <channel> "message"    # Send message
assistant slack send @user "message"        # DM a user
assistant slack history <channel>           # View recent messages
assistant slack history <channel> --limit 50

# Users
assistant slack users                       # List workspace users
assistant slack users --online              # Show online only

# Files
assistant slack upload <file> --channel <channel>
assistant slack files                       # List recent files
assistant slack download <file_id>

# Status (optional)
assistant slack status                      # Show your status
assistant slack status "Working" :laptop:   # Set status

Implementation Approach

Option A: Separate Auth System (Recommended)

Keep Slack auth completely separate from Google auth:

~/.config/assistant/
├── credentials.json          # Google OAuth app credentials
├── config.json               # Active accounts (both providers)
│   {
│     "google_active": "user@gmail.com",
│     "slack_active": "workspace-name"
│   }
├── tokens/                   # Google tokens
│   └── token_user_at_gmail_com.json
└── slack/                    # Slack tokens
    └── token_workspace-name.json

Pros: Minimal changes to existing code, cleaner separation
Cons: Some code duplication in auth patterns

Option B: Abstract Auth Layer

Refactor auth.py to support multiple providers:

class AuthProvider(ABC):
    @abstractmethod
    def login(self) -> str: ...
    @abstractmethod
    def get_credentials(self, account: str): ...

class GoogleAuth(AuthProvider): ...
class SlackAuth(AuthProvider): ...

Pros: Cleaner architecture, easier to add more providers later
Cons: Larger refactor, risk of breaking existing functionality

Slack App Setup Requirements

Users would need to:

1. Create a Slack App at https://api.slack.com/apps
2. Add Bot Token Scopes (channels:read, chat:write, etc.)
3. Install the app to their workspace
4. Copy the Bot Token (xoxb-...) to config

Simpler than Google OAuth - no browser flow needed, just paste the token.

Effort Estimate

Component	Effort	Notes
Slack auth module	Medium	New slack_auth.py or extend auth.py
Slack client	Medium	API wrapper using slack-sdk
Slack commands	Medium	Typer commands following existing patterns
CLI integration	Low	Add slack_app to cli.py
Documentation	Low	README, CLAUDE.md updates
Total	~2-3 days	Following existing patterns

Key Decisions Needed

1. Auth approach: Separate (Option A) vs Abstract (Option B)?
2. Token storage: Manual paste vs OAuth flow?
   • Manual: User pastes bot token from Slack admin
   • OAuth: Full browser-based flow (more complex, better UX)
3. Scope of features: Start minimal (send/read messages) or comprehensive?
4. Multi-workspace: Support multiple Slack workspaces like multi-account Google?

Dependencies

# pyproject.toml additions
dependencies = [
    # ... existing ...
    "slack-sdk>=3.0.0",
]

Risks & Considerations

1. Different auth model: Slack bot tokens don't expire but can be revoked
2. Rate limiting: Slack has strict rate limits (1 msg/sec per channel)
3. Bot limitations: Bots can't do everything users can (e.g., no email integration)
4. Workspace permissions: Admins may restrict which apps can be installed

Verification Plan

1. Create test Slack app with minimal scopes
2. Test slack channels listing
3. Test slack send to a test channel
4. Test slack history reading messages
5. Test multi-workspace switching (if implemented)

Recommendation

Start with Option A (Separate Auth) and manual token paste for simplicity:

• Lowest risk to existing functionality
• Fastest path to working Slack commands
• Can refactor to Option B later if adding more providers

Minimal viable feature set:

1. slack channels - list channels
2. slack send - post messages
3. slack history - read messages
4. slack users - list users