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 (Upstash Redis via the Vercel Marketplace)
- 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 |
| Observability | Structured JSON logs, Sentry integration, event catalog, debugging |
| Telemetry | Incident response: stable event vocabulary + Sentry query recipes (failure rate, recovery funnel, duplicate suppression) |
| Evals | Judge-lite output-contract rubric harness |
| 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 |
| Hybrid Retrieval (lexical + semantic) | docs/features/hybrid-retrieval.md |
| Path Annotations (.battle-mage.json) | docs/features/config.md |
| Adaptive Effort Routing | docs/features/effort-routing.md |
| Message Splitting (long replies) | docs/features/message-splitting.md |
| Issue Creation (batch + bulk confirm) | docs/features/issue-creation.md |
| Incremental Code Index | docs/features/code-index.md |
| Passive KB Learning | docs/features/passive-kb-learning.md |
| Behavior Evals (record/replay) | docs/features/behavior-evals.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 |
UPSTASH_REDIS_REST_URL |
Upstash Redis endpoint (Vercel Marketplace integration; legacy KV_REST_API_* also read) |
UPSTASH_REDIS_REST_TOKEN |
Upstash Redis token |
CRON_SECRET |
Bearer token for the cron routes (recovery sweep + code-index tick) |
UPSTASH_VECTOR_REST_URL |
Optional — Upstash Vector index (built-in embedding model) for hybrid retrieval |
UPSTASH_VECTOR_REST_TOKEN |
Optional — token for the Vector index; without the pair, search degrades to lexical-only |
SENTRY_DSN |
Optional — structured log capture and error tracking (see docs/observability.md) |
User @mentions @bm in Slack
→ Webhook received, ack'd within 3 seconds
→ Live progress: 🧠 → 🔍 → 👓
→ Claude reads code, issues, PRs via GitHub API
→ Progress message edited in place to become the answer (long answers continue in extra replies)
For the full architecture walkthrough, see docs/architecture.md.
npm test # Unit tests — fast, no API calls
npm run test:watch # Watch mode
npm run typecheck # TypeScript strict
npm run eval # Agent-quality evals against real APIs — see docs/evals.mdTDD is mandatory for all new features. See docs/contributing.md.
The eval harness runs pattern-based rubric checks (no narration, no markdown tables, length limits, reference accuracy) against live runAgent output — opt-in, requires API keys, costs a few cents per run.
MIT