CodeSentinel

Inspiration

Every engineering team knows the feeling: the codebase was clean six months ago, but now PRs take longer, onboarding new developers is painful, and nobody can explain why. The answer is almost always invisible — dead code accumulating like dust, circular dependencies creating hidden coupling, module boundaries slowly eroding. We kept seeing teams rely on CI dashboards that nobody checks, or run specialized tools that require expert knowledge to interpret. Meanwhile, Slack is where these same teams actually discuss code quality, triage issues, and make decisions. We asked: why not bring the analysis to where the conversation already happens?

What it does

CodeSentinel is an AI-powered Slack agent that analyzes codebases for four categories of health problems. Dead code detection finds functions, classes, and modules that are defined but never referenced anywhere. Circular dependency analysis uses depth-first search to map import cycles and assess their impact on tree-shaking and initialization order. Coupling metrics measure fan-out per module and identify tightly coupled clusters that make refactoring risky. Architectural drift detection checks for layer boundary violations — UI components importing directly from data layers, business logic leaking into presentation code, and shared modules breaching their intended scope.

Results are delivered as rich Block Kit messages inside Slack threads, with severity-coded findings (critical, warning, info), exact file paths and line numbers, clear explanations, and specific fix suggestions. A full health scan runs all four analyses and produces an overall score from 0 to 100. An AI-powered summary via LLM integration provides an executive overview of the results. CodeSentinel also exposes all six analysis tools through a standalone MCP server, so the same capabilities are available in Claude Desktop, Cursor, or any MCP-compatible client.

How we built it

We built CodeSentinel on Bolt for Node.js with Slack's Agent Builder framework. The architecture follows a clean pipeline: an intent parser classifies natural language messages into one of five analysis types using keyword-based NLP with support for GitHub and GitLab URL extraction. The analysis engine then routes to the appropriate analyzer module. Each analyzer produces structured findings with severity, file location, reason, and suggestion fields.

The Block Kit builder transforms these findings into rich Slack messages with headers, divider blocks, context blocks for file locations, and action buttons for re-scanning. The MCP server uses the official Model Context Protocol SDK with Zod schemas to expose the same six tools to any MCP-compatible client. For AI summaries, we implemented a multi-provider LLM layer that supports Deepseek, OpenAI, and Anthropic, using an OpenAI-compatible client with configurable base URLs.

The Slack app itself uses Socket Mode for development simplicity, with an assistant view configuration that includes four suggested prompts for common analysis types. The manifest handles bot scope configuration, event subscriptions for assistant threads and app mentions, and interactivity for Block Kit actions.

Challenges we ran into

The Slack manifest validation was more strict than expected. We went through four rounds of fixes: removing an unsupported short_description field, cutting suggested prompts to the maximum of four, renaming prompt to message in each prompt object, removing invalid bot scopes that are actually user-token-only scopes, and adding the missing app_mentions:read scope that the app_mention event requires. Each error required a full manifest re-paste into the Slack developer console.

Another challenge was designing the MCP server schemas to be both useful for AI agents and compliant with the protocol specification. We needed Zod schemas that provided enough context for an LLM to understand what each tool does, while keeping the input parameters simple enough for natural language invocation. We solved this with detailed descriptions on each tool and parameter, plus a pre-built explanation template system for the explain_finding tool.

Accomplishments that we're proud of

We're proud of the end-to-end integration across three hackathon-required technologies. Slack AI capabilities are used for intent understanding, assistant view rendering, and suggested prompt interactions. The MCP server provides genuine utility — six tools that work from any MCP client, not just Slack. The analysis results are presented through carefully designed Block Kit layouts that are scannable, actionable, and visually clear.

The health score system is particularly satisfying — it weights findings across all four categories into a single 0-100 number that gives an instant snapshot of codebase health, with category breakdowns below. We also built the entire project to be extensible: adding a new analyzer requires creating a single file and registering it in the engine, and it automatically becomes available in both Slack and the MCP server.

What we learned

We learned the nuances of Slack's Agent Builder platform deeply — from manifest validation rules to the assistant thread lifecycle. The distinction between bot scopes and user token scopes caught us off guard, and we gained a thorough understanding of which events require which permissions.

On the MCP side, we learned that tool descriptions are critical for LLM utilization. A well-described tool with clear parameter schemas makes the difference between an AI agent that can use your tool effectively and one that ignores it. We also learned that the MCP SDK's Zod integration makes schema validation straightforward but requires careful type design.

What's next for CodeSentinel

The most impactful next step is real AST-based analysis. Currently the analyzers use pattern matching and demo data to demonstrate the concept. Integrating ts-morph for TypeScript and tree-sitter for multi-language support would make CodeSentinel work on real codebases with accurate results. Beyond that, we plan to add GitHub App integration for automatic analysis on pull requests, historical health score trending to track whether codebases are improving over time, custom architecture rule configuration via Slack commands, and team health dashboards in Slack Canvas.

Built With

• block
• bolt
• context
• for
• javascript
• kit
• model
• node.js
• protocol
• slack