Slack Agent

Read-only Slack client using browser token authentication. No Slack app required.

Quick Start

# 1. Install
uv sync

# 2. Get your Slack credentials (see below)

# 3. Use it
python
>>> from slack_agent import SlackClient
>>> client = SlackClient(token="xoxc-...", cookie="xoxd-...")
>>> client.get_unread_channels()

Get Your Credentials

1. Open Slack in browser and log in
2. Open DevTools (F12)
3. Cookie: Application → Cookies → copy d value
4. Token: Console → paste this:

   JSON.parse(localStorage.localConfig_v2).teams[Object.keys(JSON.parse(localStorage.localConfig_v2).teams)[0]].token

---

Features

List All Conversations

convos = client.get_all_conversations()
# Returns: {"channels": ["C1", "C2"], "ims": ["D1"], "mpims": ["G1"]}

Get Unread Messages

# Get unread conversation IDs with mention counts
unreads = client.get_unreads()
for u in unreads:
    print(f"{u.channel_id}: {u.mention_count} mentions")

# Get full channel info for unreads
channels = client.get_unread_channels()
for ch in channels:
    print(f"Unread in: {ch.name}")

Read Messages

# Read channel/DM history
messages = client.get_channel_history("C123ABC", limit=20)
for msg in messages:
    print(f"{msg.user}: {msg.text}")

# Read thread replies
thread = client.get_thread("C123ABC", thread_ts="1234567890.123456")

Search Messages

results = client.search_messages("quarterly report", limit=10)
for msg in results:
    print(msg.text)

Get User/Channel Info

user = client.get_user_info("U123ABC")
print(f"{user.name} ({user.real_name})")

channel = client.get_channel_info("C123ABC")
print(f"{channel.name} (private: {channel.is_private})")

Find Group DM by Members

# Find a group DM containing specific people (case-insensitive)
mpim_id = client.find_conversation_by_members(["shiv", "mihir"])
if mpim_id:
    messages = client.get_channel_history(mpim_id)

Get Recent Activity

# Most recent message from each conversation, sorted by time
activity = client.get_recent_activity(limit=10)
for channel, message in activity:
    print(f"[{channel.name}] {message.text[:50]}...")

---

Environment Variables (Optional)

Instead of passing credentials directly, use a .env file:

cp .env.example .env
# Edit .env with your SLACK_TOKEN and SLACK_COOKIE

import os
from dotenv import load_dotenv
from slack_agent import SlackClient

load_dotenv()
client = SlackClient(
    token=os.environ["SLACK_TOKEN"],
    cookie=os.environ["SLACK_COOKIE"],
)

---

Claude Code Agent

This repo includes a starter agent for Claude Code that lets you interact with Slack using natural language.

Setup

1. Install the package in editable mode:

   uv sync
   uv pip install -e .

2. Copy the agent to your Claude agents directory:

   # For global access (all projects)
   mkdir -p ~/.claude/agents
   cp agents/slack-agent.md ~/.claude/agents/
   
   # Or for project-specific access
   mkdir -p .claude/agents
   cp agents/slack-agent.md .claude/agents/

3. Edit the agent file and replace /PATH/TO/slack_agent with your actual repo path:

   # Example: if you cloned to ~/projects/slack_agent
   sed -i '' 's|/PATH/TO/slack_agent|/Users/yourname/projects/slack_agent|g' ~/.claude/agents/slack-agent.md

4. Set up your credentials (see Quick Start above)

Usage

Once installed, just ask Claude Code about Slack:

> Check my Slack unreads
> What did [person] say yesterday?
> Summarize the latest thread in #channel-name
> Find messages about "topic"

The agent will automatically be invoked when Claude detects Slack-related requests.

---

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v