Home

Slackzilla

Slackzilla is a full-stack Slack bot with a React-based web dashboard, HTTP API, server telemetry, administrative controls, and a repository-aware AI assistant. It also supports automated GitHub deployments, feedback management, and modular slash commands.

Features

• 25 modular slash commands defined in bot/data/commands.json.
• 9 tools for the AI assistant: getStatus, runApiCommand, runTerminalCommand, getCommands, getReleaseInfo, runCommand, getLogs, getErrors, and getRoutes.
• 17 public API endpoints, 11 admin endpoints, and 21 admin controls
• Generated Slack app manifest support.
• Public status, metrics, logs, commands, and AI APIs.
• Admin sessions with signed cookies, PBKDF2 password verification, CSRF protection, secure API access, and rate limiting.
• Feedback filtering, read/unread status, replies, and deletion.
• CPU, memory, disk, network, bot, command, and server request telemetry.
• React pages for the dashboard, status, commands, API reference, AI assistant, documentation, logs, sitemap, and admin workflows.
• GitHub push webhook validation with HMAC-SHA256 and branch filtering.
• Repository-aware (RAG) AI assistant with lexical & deterministic retrieval, model generation, image asset discovery, and tools execution lists.
• Embedded xterm.js terminal with registered local/backend commands, virtual directory navigation, logs, API requests, version history, RAG diagnostics, and browser storage inspection.

Architecture

The backend uses Node's built-in http module rather than Express. API modules are explicit handlers imported and registered in server/server.js. Persistent runtime data is currently stored through the JSON-backed adapter in server/database/store.js; an external database is not required.

Check docs to see full navigation and overview of slackzilla

• Setup
• Architecture
• API
• Terminal
• RAG Assistant
• Security
• Webhook
• Server Setup
• POST command docs
• Extension Guides

Requirements

• Node.js with npm (make sure all dependencies are installed with npm ci before running)
• A Slack app with Socket Mode enabled.
• Git for deployment features.
• Linux and systemd for the production service files. (Admin controls relies on bot service file being active too stop & start the bot, but you can still run the bot npm start on windows)
• An AI provider key for model-backed AI answers. (optional, bcs these are needed for the /ai page, /api/ask endpoint and /sz-ask command)

Setup

To run the project locally, clone the repository, install dependencies, and configure environment variables and then run the bot and dashboard by executing the following command. For more information, see the Setup Guide.

npm start

Dashboard Pages

Path	Purpose
/	Public bot and server dashboard.
/status	Runtime, CPU, memory, disk, and network telemetry with charts.
/commands	Command reference and trusted command runner.
/logs	ANSI-aware live log viewer.
/terminal	Restricted xterm.js terminal for diagnostics and registered tools.
/ai	Repository-aware AI questions, sources, and related visual assets.
/api	API endpoint reference.
/docs	Dynamically generated documentation.
/admin/login	Admin login and session creation.
/admin	Authenticated controls, feedback management, and server activity.
/admin/logs	Authenticated log viewer, deletion, rotation, and restoration.
/admin/errors	Authenticated error log viewer and stream.
/admin/events	Authenticated server event stream.

Unknown browser routes return the React NotFound page with HTTP status 404.

ALL API Routes

Public endpoints:

GET  /api/status
GET  /api/status/stream
GET  /api/telemetry
GET  /api/telemetry/stream
GET  /api/metrics
GET  /api/logs
GET  /api/logs/stream
GET  /api/logs/download
GET  /api/commands
GET  /api/commands/:id
POST /api/commands/:id
GET  /api/ask
POST /api/ask
GET  /api/routes
GET  /api/release
GET  /api/session
POST /api/terminal
POST /webhook

Admin endpoints require a valid session cookie and CSRF protection for state-changing requests:

GET  /api/admin/summary
GET  /api/admin/summary/stream
GET  /api/admin/events
GET  /api/admin/feedback
GET  /api/admin/feedback/:id
POST /api/admin/feedback/:id
POST /api/admin/control
GET  /api/admin/errors
GET  /api/admin/errors/stream
GET  /api/admin/log-archives

See the API documentation for details on request and response formats, query parameters, and error codes.

Embedded Terminal

The dashboard Terminal page is a restricted browser terminal, not an operating-system shell. It never executes arbitrary host commands, reads the server filesystem, or forwards unrestricted network requests. Local commands run in the browser; registered backend commands use the bounded POST /api/terminal endpoint.

The terminal includes:

• Local utilities: help, ver, history, time, terminal, refresh, and cls/clear.
• Public backend commands: status, uptime, version, logs, api, docs, rag, and command.
• Administrative commands: sudo status, sudo controls, sudo inspect, sudo execute, and sudo logout, protected by the existing administrator session, CSRF, re-authentication, confirmation, and rate limits.
• Virtual contexts: command, api, logs, and storage; api exposes get and post contexts, while storage exposes browser session and local contexts.

Examples:

version --help
version v0.9.6-beta --verbose
logs --tail 50
api get /api/status
api post /api/example --body '{"example":true}'
rag sources --type jsx,json --search terminal --limit 20
cd storage/session

dir lists the current virtual context without changing it. cd, cd .., relative paths such as cd ../local, exit, and idle Ctrl+C use the shared context stack. Storage values are shown only after administrator authentication; session cookies and CSRF secrets are not printed, and the protected terminal-state key cannot be deleted. See the Terminal Guide and Terminal Extension Guide.

RAG Assistant

The /ai page and /api/ask endpoint retrieve relevant repository text before asking the configured AI model to answer. Retrieval excludes priv/, .env files, logs, dependencies, build output, and Git metadata. Related image assets are identified by filename and can be displayed without reading their binary contents. The assistant can use registered Slack command tools, public terminal commands, and internal /api/ GET/POST requests through separate guarded tools. RAG API calls cannot use external URLs or credential headers; endpoint-level authentication, CSRF, confirmation, and rate limits remain authoritative.

The rag sources terminal command supports comma-separated --type, path --search, and bounded --limit filters. rag:use-tool can invoke the same RAG tool definitions, including runTerminalCommand and runApiCommand, without exposing administrative terminal commands or arbitrary shell execution.

See the RAG documentation for details on retrieval scoring, model generation, image assets, and command execution.

Slack Commands

Commands are defined in bot/data/commands.json and implemented in bot/cmds/. To add a command:

1. Add its metadata to bot/data/commands.json.
2. Add the implementation to bot/cmds/.
3. Register it using the existing command module pattern.
4. Run npm run validate-commands.
5. Run npm run generate-manifest if the Slack manifest changed.
6. Restart the bot.

Utility commands support a <command> help form with usage examples. It also has a dedicated api endpoint.

See Command Endpoints for details on command metadata, request and response formats, and error codes.

GitHub Deployment Webhook

The dashboard accepts signed push events at POST /webhook. It verifies X-Hub-Signature-256 with WEBHOOK_SECRET, requires a push event, checks payload.ref against BRANCH, records deployment state, and runs server/deploy.sh.

Read the webhook guide before exposing the endpoint publicly.

Production

For Linux deployment:

npm ci
npm run build
sudo cp server/slackzilla.service /etc/systemd/system/
sudo cp server/slackzilla-webhook.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now slackzilla.service slackzilla-webhook.service

Use a reverse proxy for HTTPS and set COOKIE_SECURE=true. Restart the appropriate service after code or environment changes.

Scripts

Command	Purpose
npm start	Build, lint, and start the bot and dashboard concurrently.
npm test	Run all tests, validate the manifest and commands, and lint the client.
npm run test:single	Run all tests without validation or linting.
npm run bot	Start only the Slack bot.
npm run server	Start only the dashboard server.
npm run dev	Start the Vite client development server with hot reloading.
npm run build	Build the React client for production.
npm run preview	Preview the production build of the client.
npm run build:preview	Build the client and preview the production build.
npm run lint	Lint the client code.
npm run generate-manifest	Generate manifest.json for the bot.
npm run validate-manifest	Validate the manifest against its schema.
npm run validate-commands	Validate command metadata against its schema.
npm run stats	Generate command usage statistics.
npm run rag	Debug RAG retrieval and responses using a supplied query.
npm run rag:use-tool	Run the RAG tool integration script.
npm run release	Append release notes to the changelog.
npm run update	Generate the manifest and append release notes.
npm run all	Run tests, update the manifest and release notes, and start the project.

See Testing for more details.

License

no need for credits, but if your using this code in a project, i'd love to see what you do with it so if you make something cool with it, please share it with me!

Contributing

Contributions are NOT accepted. if you have any issues, bugs or feature requests, please open an issue on the repository or reach out to me on the Slackzilla Server and ill try to help you out.