Skip to content

Home

Build powerful Discord bots, without the boilerplate.

Grace Framework is an opinionated, extensible Discord bot framework built on top of discord.py. It comes with the tools you need to rapidly build scalable, feature-rich Discord bots with minimal boilerplate.

  • Quick to start — generate a full-featured bot in seconds
  • Modular architecture — clean separation of features via extensions (cogs)
  • Database integration — opt-in, per-project persistence backed by SQLModel and Alembic migrations
  • Built-in generators — scaffold extensions, models, and migrations with a single command

Quickstart

Requirements: Python 3.12+

pip install grace-framework

Using a virtual environment is strongly recommended:

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install grace-framework

Scaffold a new bot project:

grace new my-awesome-bot
cd my-awesome-bot

Set your bot token in .env:

DISCORD_TOKEN=your token here

grace run

Add --watch during development to enable hot reload:

grace run --watch

Where to go next

  • Guides

    Step-by-step tutorials covering installation, models, extensions, configuration, and more.

    Start with Installation

  • Reference

    Complete API documentation for every class and function in the framework.

    Browse the Reference

  • Examples

    Full walkthroughs demonstrating common patterns and use cases.

    View Examples

  • Source Code

    Browse the source, open issues, and contribute on GitHub.

    View on GitHub

Inspiration

Grace Framework was inspired by the evolution of our community Discord bot, Grace, which grew to support modular extensions, database integrations, and rapid feature development — it began to resemble a standalone framework. Recognizing its potential, we extracted its architecture into Grace Framework, making its ease-of-use and flexibility available to developers everywhere.

Contributing

We welcome everyone to contribute! Whether it's fixing bugs, suggesting features, or improving the docs — every bit helps.

Please read the CONTRIBUTING.md and follow the code of conduct.

License

Released under the MIT License.