slacky - Read-only Slack search for fast context

Read-only Slack search for fast context, built for people and agents. slacky helps you search messages, open the right thread, and pull surrounding Slack context into JSON or copyable terminal output.

Requires a Slack user token with read scopes. macOS and Linux.

Install

brew install andyhtran/tap/slacky

To update:

brew update && brew upgrade slacky

Build from source

git clone https://github.com/andyhtran/slacky.git
cd slacky && go build -o slacky ./cmd/slacky

First-time setup

Use the bundled setup guide when creating a Slack app or importing an existing user token:

slacky skills get setup
slacky setup wizard
slacky auth status

If you already have a Slack user token with the required scopes:

slacky auth import
slacky auth status

auth import prompts for the token by default. For scripts, use --token-stdin, --token-file <path>, or --token-env <name> instead of putting tokens in command arguments.

To keep multiple credentials, store named profiles and switch between them:

slacky auth import --name work-token
slacky auth list
slacky auth switch work-token
slacky auth status --active

Named profiles use separate SQLite caches by Slack workspace and user. Check the exact active profile, credential source, storage label, and cache path with slacky auth status --active or slacky paths.

If slacky auth status shows expires_at, Slacky refreshes rotating OAuth credentials before live Slack API commands when possible. For explicit diagnosis, run slacky auth refresh [--profile <name>].

When Slack app installation is blocked but you can already access Slack in a browser, auth import-session --wizard can walk you through importing an advanced browser session using an xoxc token plus the Slack cookie named d. Use OAuth or user-token import when available. For browser-session troubleshooting, --user-agent or SLACKY_BROWSER_USER_AGENT can override the fallback browser User-Agent.

Search Slack

Search live Slack results:

slacky search "from:@someone has:link"
slacky search "in:#general release"
slacky find "customer escalation"
slacky find "paddle recommendations"

Re-find cached context instantly with zero Slack API calls. This is useful offline, during rate limits, or when you already fetched the conversation before:

slacky search --local "release notes"
slacky search --local "in:#general launch checklist" --json --compact
slacky find --local "customer escalation" --json --compact

Get context

Fetch messages, threads, surrounding context, or archive links:

slacky thread --channel C123 --ts 1717440000.000000
slacky context --channel C123 --ts 1717440000.000000
slacky open https://workspace.slack.com/archives/C123/p1717440000000000 --mode thread

Resolve channels and people:

slacky channels general
slacky user person@example.com
slacky user @someone

Use with agents

slacky skill install ships a small discovery stub for agents. The full runtime guidance is embedded in the slacky binary and updates with each brew upgrade slacky.

slacky skill install
slacky skills get core
slacky agent-context --json
slacky schema --json

Then prompt naturally:

use slacky to find the launch thread and summarize the decision

Agents should prefer --json for stable output and check source plus cache_notice before treating cached data as fresh. For search-heavy or synthesis workflows, use --json --compact to get IDs, timestamps, dates, excerpts, permalinks, and follow-up commands without rendered human text.

Safety and storage

Slack API calls are read-only. The default OAuth path uses user-token scopes and does not request permissions to send messages, mutate channels, change users, manage files, create webhooks, or change workspace settings. Browser-session import is an advanced fallback that uses the user's existing Slack web session, so treat those credentials like browser cookies.

slacky stores its own files under ~/.slacky/: auth metadata, profile-scoped SQLite caches, small state files, logs, and CLI-owned skill storage. Legacy unnamed auth uses ~/.slacky/cache/index.db; named auth uses ~/.slacky/cache/profiles/<profile>--<team_id>--<user_id>/index.db. Set SLACKY_HOME to override this for isolated runs. Use slacky cache prune --older-than 90 --dry-run before deleting old cached messages. Auth files are written with 0600 permissions, and secrets are redacted from status, doctor, schema, and agent-context output.

Run slacky --help, slacky schema --json, or slacky skills get core for the full command surface.

Build commands

just build
just test
just ci

License

MIT