A Slack agent powered by Claude AI that reads your GitHub repo in real time — code, docs, issues, PRs, commits — and answers questions, tracks recent activity, and creates issues on request. Mention @bm in any channel to get started.
- Code intelligence — searches and reads your repo to answer with specific file paths and line numbers
- Issue and PR awareness — lists recent issues, PRs, and commits sorted by date
- Issue creation — drafts issues with a preview; creates only after ✅ reaction
- Thread conversations — follow up without re-mentioning the bot
- Persistent knowledge base — remembers corrections across conversations (Vercel KV)
- Repo index — auto-built topic map for fast navigation, rebuilt lazily on push
- Source-of-truth hierarchy — weights code over docs over KB when sources conflict
- Auto-correction — flags possibly stale knowledge entries on 👎, saves corrections directly to KB
- Live progress — shows what the agent is doing step by step with contextual emoji
- Recency-first — prefers recent commits, PRs, and issues over historical data
- Configurable trust —
.battle-mage.jsonin your repo lets you annotate paths as core, historic, vendor, or excluded
git clone <your-fork-url>
cd battle-mage
npm install
cp .env.example .env.local # Fill in credentials
npm run devSee the full setup guide for Slack app creation, GitHub PAT, Vercel deployment, and first-run testing.
| Guide | What it covers |
|---|---|
| Setup | Slack app, GitHub PAT, Vercel deploy, env vars |
| Usage | Asking questions, threads, issues, corrections, feedback |
| Architecture | Agent loop, tools, system prompt, design decisions |
| Contributing | Fork workflow, TDD, CI, branch protection |
| Logging | Structured JSON logs, event catalog, debugging |
| Troubleshooting | Common issues and fixes |
| Feature | Doc |
|---|---|
| Repo Index | docs/features/repo-index.md |
| Knowledge Base | docs/features/knowledge-base.md |
| Source-of-Truth Hierarchy | docs/features/source-hierarchy.md |
| Auto-Correction on 👎 | docs/features/auto-correction.md |
| Live Progress Updates | docs/features/progress-ux.md |
| Path Annotations (.battle-mage.json) | docs/features/config.md |
| Variable | Description |
|---|---|
SLACK_BOT_TOKEN |
Bot User OAuth Token (xoxb-...) |
SLACK_SIGNING_SECRET |
Slack app signing secret |
ANTHROPIC_API_KEY |
Claude API key |
GITHUB_PAT_BM |
Fine-grained PAT scoped to your target repo |
GITHUB_OWNER |
GitHub org or username |
GITHUB_REPO |
Repository name |
User @mentions @bm in Slack
→ Webhook received, ack'd within 3 seconds
→ Live progress: 🧠 → 🔍 → 👓 → ✏️
→ Claude reads code, issues, PRs via GitHub API
→ Answer posted in thread, progress message deleted
For the full architecture walkthrough, see docs/architecture.md.
npm test # 148 tests across 9 files
npm run test:watch # Watch mode
npm run typecheck # TypeScript strictTDD is mandatory for all new features. See docs/contributing.md.
MIT
