ISHU

Ishu is an always-on engineering assistant that lives in Slack, remembers every conversation, and can query code, logs, metrics, and GitHub all from a single thread.

Comment

Ishu collapses the daily context-switching between Elasticsearch, MongoDB, GitHub, the IDE, and analytics dashboards into one Slack conversation. Support can ask about user-facing behavior without touching a terminal. Engineers can ask whether a feature exists, how it works, or whether something is a bug — even in codebases they don't know well. It also queries logs and metrics, opens GitHub PRs and issues, searches Slack history in real time, and posts scheduled ops reports.

For the Slack Agent for Good track, Ishu is aimed at under-resourced nonprofit, civic-tech, and open-source teams that do not have dedicated SREs or 24/7 on-call. A single volunteer can check public status pages, query logs, search Slack history for prior incidents, file GitHub issues, open fixes as PRs, and post plain-language impact updates — all from the same Slack thread. This democratizes platform-engineering skills and helps small teams keep critical public services online.

The bot is built for the Slack Agent Builder Challenge and satisfies all three mandatory technology requirements: Slack AI capabilities, MCP server integration, and the Real-Time Search API. It runs in Socket Mode (no public ingress required), uses Cloudflare Workers AI with Kimi K2.7 or Kimi 2.6, persists state to an object-storage bucket (e.g. HuggingFace Hub buckets or local filesystem), and ships with Docker, docker-compose, and Kubernetes manifests.

Core features Feature What it does Slack AI Assistant panel Open Ishu directly from Slack's native assistant UI with suggested prompts, status updates, and live progress messages while tools run. Real-Time Search API Answer questions about Slack history using assistant.search.context. MCP server integration Dynamically discover and invoke tools from external Model Context Protocol servers. Code Q&A Clone repos, search files by name or content, browse directories, read/edit code, open PRs/issues, comment on existing issues/PRs, search GitHub issues/PRs, fetch PR diffs for review, and look up public model registry metadata (e.g. HuggingFace Hub models/datasets/Spaces). Data & ops queries Query Elasticsearch, MongoDB, AWS Athena, Plausible analytics, public status pages, and DuckDB/Sizzle storage stats. Resumable sessions + memory recall Every Slack thread is an independent, persistent session backed by a bucket; prior interactions from the same thread and related past threads are automatically recalled into the system prompt so the assistant remembers context across conversations. Users can also explicitly save facts with /ishu remember , recall recent memories with /ishu memory [limit], and remove remembered facts with /ishu forget <text Auditable artifacts Every response uploads a markdown response, a JSONL session trace, and a rendered HTML trace viewer for step-by-step auditing. Runtime metrics The bucket server exposes a /metrics endpoint and /ishu metrics reports live operational counters: messages handled, LLM calls, tool calls, tool errors, sessions, thread map entries, memory, feedback, audit events, and response artifacts. Hot skill reload Privileged users can run /ishu reload to pick up new or edited skill Markdown files in skills/ without restarting the bot. Request correlation IDs Every Slack message and GitHub webhook gets a short correlation ID that is persisted into the session JSONL and included in error logs, making it easy to trace a failure back to the originating message. Scheduled tasks Weekly ops report, post-deploy impact monitor, and proactive public-status monitoring with restart-safe incident state and recovery alerts; also callable on demand via weekly_report/deploy_report tools and /ishu report slash commands. Tiered access control Basic / elastic / privileged tiers, guest refusal, tiered Linux-user sandboxed bash, and local credential proxies. App Home + slash command Home tab overview and/ishu help Message shortcut Select any Slack message and choose Ask Ishu for a threaded, context-aware reply. File attachments Share text files, logs, CSVs, JSON, or code snippets in a thread; Ishu reads them as context (requires the files:read scope). Channel welcome When Ishu is invited to a channel, it posts a brief intro pointing to /ishu help, @-mentions, and the Slack AI assistant panel. Inline feedback + emoji reactions Every response includes 👍 / 👎 buttons so users can flag helpful/unhelpful replies; after a 👎, a Regenerate response button asks Ishu to retry with a different approach. Users can also react with emoji 👍 / 👎 / 🔄 / ❓ for feedback, reset, or help. Resilient GitHub API calls GitHub read/write operations retry transient 5xx / 429 errors with exponential backoff and honor GitHub's Retry-After header, so PR/issue writes succeed during brief GitHub outages or rate-limit windows. Self-correcting tool calls Malformed JSON is reported back to the model as a parse error so it can retry instead of silently failing. Start over reset Tapping "Start over" or reacting with 🔄 on any reply clears the thread session so the next message begins fresh. GitHub-only bot mode The same codebase can run as a credential-poor GitHub bot that replies to @ishu mentions on issues and PRs, with no Slack tokens or production database access. Slack app creation helper npm run slack-manifest-url outputs a one-click URL that pre-fills manifest.json at api.slack.com/apps, speeding up sandbox provisioning. Submission readiness npm run prepare-submission checks that required deliverable files exist, forbidden files are not tracked by git, and SUBMISSION.md has no unchecked checklist items or placeholders. Architecture flowchart TD subgraph Slack A[App Home] B[Assistant Panel] C[@-mentions / DMs] D[Slash /ishu] end

A --> E[src/slack.ts]
B --> E
C --> E
D --> E

E --> F[src/agent.ts]
F --> G[Cloudflare Workers AI]
F --> H[Skills Markdown]
F --> I[Tool Registry]

I --> J[Built-in tools]
I --> K[MCP servers]

J --> J1[read/write/edit]
J --> J2[bash]
J --> J3[memory]
J --> J4[open_pr / create_issue / commit_to_pr / get_pr_diff]
J --> J5[es_query / mongo_query / athena_query / sizzle_query / plausible_query]
J --> J6[search_code / clone_repo / list_files]
J --> J8[hf_hub_info]
J --> J7[search_slack]

F --> L[Bucket storage]
L --> M[session JSONL]
L --> N[thread-map.json]
L --> O[memory.json]
L --> P[response artifacts]

F --> Q[Credential proxies]
Q --> R[ES proxy :9201]
Q --> S[HF proxy :9202]
Q --> T[Plausible proxy :9203]

F --> U[Scheduled tasks]
U --> V[Weekly report]
U --> W[Deploy monitor]

Runtime flow:

A Slack message arrives via Socket Mode (app_mention, DM, channel/group/MPIM mention, or assistant_thread_started). src/slack.ts validates the user, resolves their access tier, strips bot mentions, suppresses duplicate/out-of-order events, and routes thread follow-ups back to the active session. src/agent.ts lazily restores the thread session from the bucket, builds the system prompt + skills, and runs a ReAct loop with the LLM. Tool calls are parsed from blocks; malformed JSON is reported back to the model so it can self-correct. The final response is uploaded to the bucket as markdown + JSONL, and a Slack message with Block Kit links is posted. Tech stack Node.js 22+ with TypeScript and ESM @slack/bolt v4 for Socket Mode + Slack AI Assistant Cloudflare Workers AI for Kimi K2.7 (default) or Kimi 2.6 @modelcontextprotocol/sdk for MCP client support Object storage buckets (e.g. HuggingFace Hub buckets or local filesystem) for persistent artifacts Docker + docker-compose and Kubernetes for deployment Mandatory technology compliance Requirement Implementation File(s) Slack AI capabilities Bolt Assistant with threadStarted, threadContextChanged, and userMessage handlers; native assistant panel with status and suggested prompts. src/slack.ts, manifest.json MCP server integration Dynamic MCP client over stdio/SSE/Streamable HTTP; MCP tools are registered with mcp__ names and flow through the same ReAct loop. src/mcp/client.ts, src/tools/registry.ts Real-Time Search API search_slack tool calls assistant.search.context with either a Slack AI action_token or a configured SLACK_USER_TOKEN. src/tools/slack-search.ts, src/context.ts Getting started in a Slack sandbox Create a Slack app from manifest.json at api.slack.com/apps — or run npm run slack-manifest-url to generate a one-click app-creation URL from the command line. Install the app to your developer sandbox. Copy the bot token (xoxb-...) and app-level token (xapp-...). Configure a Cloudflare Workers AI token and account ID. Run locally: cp .env.example .env

fill in SLACK_BOT_TOKEN, SLACK_APP_TOKEN, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN

npm install npm run build node dist/app.js --check npm run diagnose npm run verify-cloudflare npm run verify-slack npm run verify-github npm run verify npm run slack-manifest-url # optional one-click Slack app-creation URL npm run fill-submission npm run prepare-submission npm start npm run verify-slack also compares the installed bot token's actual scopes with the scopes declared in manifest.json and generates a Socket Mode connection URL via apps.connections.open, catching stale app installs or missing connections:write scope before the bot starts Socket Mode.

Slack AI Assistant + Real-Time Search: open the Assistant panel and ask Search Slack for recent deployment discussions and summarize what changed. MCP integration: with an MCP filesystem server configured, ask List the files in /tmp and tell me which ones were modified today. Code + GitHub + public model registry: in a channel, mention the bot: @ishu look up the task for sentence-transformers/all-MiniLM-L6-v2 on HuggingFace Hub. Search existing issues before filing a bug: @ishu search issues in my-org/my-repo for "login error" Then ask it to open a draft PR: @ishu open a draft PR in my-org/my-repo that adds a hello-world script. Reply in the same thread without another @-mention to refine the PR, or ask it to comment on an existing issue/PR. Data query (Elasticsearch / MongoDB / Athena / Plausible): How many 5xx errors did we see in the last hour? File attachments: upload a .log or .txt file to a thread and ask @ishu summarize this file to show Slack file-reading. Message shortcut: select any message, choose Ask Ishu, and watch it reply in the thread. Inline feedback + regenerate + emoji reactions: after any response, click 👍 or 👎; after a 👎, tap Regenerate response to ask Ishu to retry. You can also react with 👍 / 👎 / 🔄 / ❓ for feedback, reset, or help. Scheduled reports on demand: /ishu report weekly and /ishu report deploy Public status page and impact monitoring on demand: /ishu statuspage https://status.cloudflare.com/api/v2/status.json and /ishu impact Live diagnostics, demo prompts, LLM ping, identity, audit log, skill reload, thread info, and memory management: /ishu diagnose, /ishu demo, /ishu tools, /ishu version, /ishu ping, /ishu whoami, /ishu audit (privileged), /ishu reload (privileged), /ishu thread, /ishu remember , /ishu memory [limit], and /ishu forget Agent for Good — public service monitoring: Check the status page for status.cloudflare.com and tell me if any public services nonprofits rely on are degraded. Trace viewer: on any Ishu reply, click View trace and show the HTML timeline of every turn, tool call, and result. Start over: after a few turns, click Start over and continue with a fresh session. Cross-thread memory recall: ask a question in one channel, then in a different channel ask something related (e.g., "What was that staging DB hostname again?") and watch the prior answer surface automatically in the system prompt. Or explicitly save a fact with /ishu remember staging DB host is db-staging.example.com and later ask in another thread: "What was the staging DB host?" GitHub-only bot mode: open a GitHub issue/PR, mention @ishu, and watch it reply by posting a comment — no Slack workspace needed. Status / help: /ishu status Deployment notes Socket Mode means no public URL is required for Slack events. The artifact bucket server serves response markdown and JSONL traces on BUCKET_HTTP_PORT. A production-ready Dockerfile, docker-compose.yml, k8s/ manifests, and a separate k8s/github-only/ overlay for the credential-poor GitHub bot pod are included. manifest.json requests all required OAuth scopes and bot events.

Built With

Share this project:

Updates