npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

garbanzo-bot

v3.4.0

Published

Multi-platform community lore and operations with cross-platform bridging.

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

garbanzo-botgarbanzo-bot

Keywords

Readme

Garbanzo

Multi-platform community lore and operations with cross-platform and cross-community bridging.

Website: https://garbanzobot.com | Docker Hub: https://hub.docker.com/r/jjhickman/garbanzo

Garbanzo Logo

Quality Gate Docker Hub Docker Pulls License

Garbanzo brings AI-driven moderation and enrichment to communities where they already operate. It can answer questions, summarize busy threads, remember owner-approved facts, call local integrations, moderate with human review, and bridge conversations across communities and messaging platforms, including Discord, WhatsApp, Telegram, and Matrix today.

Why Garbanzo

  • Runs anywhere with inspectable state: SQLite by default, optional Postgres, operator-controlled Qdrant, and explicit-only shared memory. See RAG federation.
  • One core pipeline spans multiple messaging platforms (WhatsApp, Discord, Slack, Telegram, Matrix, and more), with optional bridging for mapped communities across platforms. See bridging.
  • Multi-provider AI routing covers OpenAI, Anthropic, Gemini, Bedrock, OpenRouter, and any OpenAI API-compatible model provider, providing fallback and resiliency. See configuration.
  • WhatsApp support includes browser login and outbound safety designed around the Baileys account-risk model. See the outbound safety ADR.
  • The persona model shapes the whole bot: a markdown file defines who your bot is, how it talks, and what it cares about, and every surface follows it, including its name, replies, and prompts. Locale, provider order, integrations, and groups are configuration too. See customization.

What It Does

  • Community lore - your community memory: mention-gated chat, context compression, session summaries, curated facts, optional auto-extracted facts, semantic recall, shared facts, and read-only RAG federation. Memory, configuration
  • Community workflows - introductions, welcomes, summaries, event reminders, polls, profiles, recommendations, release notes, feedback, and owner digests. Architecture, customization
  • Integrations - weather, transit, venues, news, books, web search, D&D dice/lookups, character PDFs, speech transcription, and language detection. Configuration
  • Band features - an optional feature set adds songs, rehearsals, availability, setlists, practice agendas, idea capture, audio transcription, sections, and lyrics. Band deployment
  • Moderation and safety - mention gating, feature allowlists, prompt sanitization, owner alerts, rate limits, retry queues, and WhatsApp outbound controls. Security
  • Operations - health and readiness endpoints, /admin, Prometheus metrics, Grafana dashboards, HTTP health-check monitors, backups, release pinning, Compose, Helm, and systemd. Monitoring, backups

See It In Action

Real interactions from communities powered by Garbanzo:

| Capability | Screenshot | |---|---| | Help and command discovery | | | First-time introduction welcome | | | Local weather planning | | | Transit alerts | | | Local recommendations | |

Quick Start

Node.js 20+ is required either way. Docker Compose is only needed for the full-stack door below.

Quick start (no Docker)

npx garbanzo-bot setup

The wizard collects your AI provider keys, your messaging platform, and (for Discord) walks through the developer portal to gather a bot token, an owner user ID, and at least one channel to enable. Configuration and data live in ~/.garbanzo. To run the bot and keep it running:

npm install -g garbanzo-bot
garbanzo start

Check your environment with garbanzo doctor (Node version, config files, provider keys, optional binaries) and install a service that survives reboots with garbanzo service install (systemd on Linux, launchd on macOS). Prefer working from a checkout? The git-clone path works the same: clone, npm ci, npm run setup, then npm run build && npm start.

This path skips the monitoring stack, the RabbitMQ bridging transport, and container isolation, and defaults to keyword-only memory (VECTOR_STORE=none) instead of Qdrant semantic memory. See docs/QUICKSTART.md for the full walkthrough, including updates, backups, running as a service, and enabling Qdrant.

Full stack (Docker)

git clone https://github.com/jjhickman/garbanzo-bot.git
cd garbanzo-bot

cp .env.example .env
cp .env.discord.example .env.discord
cp config/discord-channels.example.json config/discord-channels.json

In .env, set:

COMPOSE_PROFILES=discord
AI_PROVIDER_ORDER=openai,anthropic
MONITORING_TOKEN=<pin-a-token-if-using-admin-or-monitoring>

In .env.discord, set DISCORD_BOT_TOKEN, DISCORD_OWNER_ID, and the channel config values used by config/discord-channels.json. Add at least one provider key in .env.

docker compose up -d
docker compose logs -f discord
curl "http://127.0.0.1:${DISCORD_HEALTH_PORT:-3002}/health"

In an allowed Discord channel, mention the bot. For example, if the persona is Garbanzo:

@garbanzo summarize what I missed today
@garbanzo is the train running on time?

For the guided wizard: npm run setup.

Optional WhatsApp instance:

cp .env.whatsapp.example .env.whatsapp
# In .env: COMPOSE_PROFILES=discord,whatsapp
# In .env.whatsapp: set OWNER_JID and WhatsApp options.
docker compose up -d
docker compose logs -f whatsapp
curl "http://127.0.0.1:${WHATSAPP_HEALTH_PORT:-3001}/health"

This door adds the full stack this project supports: Prometheus/Grafana monitoring, the RabbitMQ bridging transport for larger topologies, Qdrant semantic memory, and per-container isolation. See docs/BRIDGING.md and docs/MONITORING.md.

Platform setup details live in docs/PLATFORMS.md.

Platforms & Bridging

  • Discord - default runtime using the official Gateway API, opt-in channels, owner escalation, welcomes, scheduled recaps, reminders, and band-mode roles.
  • WhatsApp - fully supported through Baileys v7, browser login, linked-device auth persistence, group config, and anti-ban outbound safety.
  • Slack - Events API support plus a local demo mode for pipeline checks.
  • Telegram - grammY-based long-polling bot, privacy-mode-off recommended setup, MarkdownV2 formatting, and voice-note transcription.
  • Matrix - matrix-bot-sdk over /sync long polling, room config keyed by room ID with alias resolution at setup, and audio transcription. Encrypted rooms aren't supported; invite the bot into unencrypted rooms only.

Bridging connects mapped communities across platforms into a single conversation while keeping each bot instance independent. Transports scale from a simple two-instance setup to a message broker for larger topologies, and instances can share one account or stay fully isolated. Setup, topology options, and rate-safety details live in docs/BRIDGING.md.

Memory & Knowledge

  • Conversation context keeps recent chat available to the model.
  • Session memory summarizes inactive stretches and stores long-horizon recall.
  • Curated facts are owner-managed through !memory; optional auto-extraction stays local and capped.
  • Shared facts are explicit only: !memory share <id> writes a namespaced fact to the shared Qdrant collection for peer instances.
  • RAG federation searches read-only Qdrant sources such as runbooks or archives at prompt time without writing to them.

See docs/RAG_FEDERATION.md, docs/BRIDGING.md, and docs/CONFIGURATION.md.

AI Routing

Set AI_PROVIDER_ORDER to choose failover order across OpenAI, Anthropic, Gemini, Bedrock, and OpenRouter, and point simple queries at any OpenAI API-compatible model provider, local or remote. Native tool calling is controlled by AI_TOOL_CALLING; when enabled, providers can call Garbanzo integrations during a reply.

See docs/CONFIGURATION.md.

Deployment

Compose is the default release path:

APP_VERSION=3.4.0 docker compose pull
APP_VERSION=3.4.0 docker compose up -d

Production overlay:

APP_VERSION=3.4.0 docker compose -f docker-compose.yml -f docker-compose.prod.yml pull
APP_VERSION=3.4.0 docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Kubernetes operators can install one bot instance per Helm release:

helm install garbanzo ./deploy/helm/garbanzo --set platform=discord --set instanceId=discord-main

See deploy/helm/README.md. Native Node deployments can use scripts/garbanzo.service with the same layered env files.

Monitoring & Backups

MONITORING_TOKEN gates /metrics, /admin, Prometheus scrapes, and the Grafana admin password fallback. With COMPOSE_PROFILES=discord,monitoring or discord,whatsapp,monitoring, the dashboard has a $job picker for all instances or one service at a time. Monitoring services should watch /health/ready on the configured port for each messaging instance.

Nightly off-machine backup guidance covers credentials, database state, verification, retention, and restore: docs/BACKUPS.md. Monitoring setup and metrics are in docs/MONITORING.md.

Customizing For Your Community

Garbanzo is configurable first. The default persona is a Boston meetup WhatsApp community bot.

  • Persona identity comes from docs/PERSONA.md and optional platform persona files.
  • Locale behavior comes from env values for weather, transit, venue search, news, web search, and language settings.
  • Discord channels live in config/discord-channels.json; WhatsApp groups live in config/groups.json.
  • Feature allowlists, mention requirements, owner controls, provider order, vector memory, and bridge identity are env/config choices.

See docs/CUSTOMIZATION.md, docs/CONFIGURATION.md, and docs/PLATFORMS.md.

Development

npm run dev          # Hot reload
npm run setup        # Interactive setup wizard
npm run typecheck    # Type-check only
npm run lint         # ESLint
npm run test         # Vitest
npm run check        # Secrets, deps audit, typecheck, lint, tests
npm run build        # Compile to dist/
npm run start        # Run dist/

Architecture: docs/ARCHITECTURE.md. Project principles: docs/PHILOSOPHY.md.

Docs

Getting started: QUICKSTART.md, CONFIGURATION.md, PLATFORMS.md, CUSTOMIZATION.md, PERSONA.md

Operations: BRIDGING.md, RAG_FEDERATION.md, MONITORING.md, BACKUPS.md, SECURITY.md, RELEASES.md, BAND_FEATURES.md, POSTGRES_MIGRATION_RUNBOOK.md, ADR-0001-whatsapp-outbound-safety.md

Design and development: ARCHITECTURE.md, PHILOSOPHY.md, ROADMAP.md, AWS.md, SCALING.md, CHANGELOG.md, CONTRIBUTING.md, AGENTS.md

Contributing - Support - License

Contributions are welcome through pull requests. See CONTRIBUTING.md. Before pushing, run:

npm run check
npm run gh:dependabot

Support funds provider integrations, AI workflow improvements, and release maintenance:

  • Patreon: https://www.patreon.com/c/garbanzobot
  • GitHub Sponsors: https://github.com/sponsors/jjhickman

Garbanzo is licensed under Apache License 2.0. See LICENSE_FAQ.md.