Skip to main content

b3th

AI-powered CLI that stages, commits, pushes, proposes merge resolutions, and opens pull-requests for you.
CI badge

✨ Features

Command What it does
b3th sync Stage → commit → push in one shot. b3th asks an LLM for a succinct commit subject + body, then runs git add --all, git commit, and git push -u origin <branch>.
b3th prcreate Pushes the current branch (if needed), summarises commits + diff, and opens a GitHub pull-request, returning the PR URL.
b3th prdraft Opens a draft pull-request (marked “Draft” on GitHub) after generating the title/body with the LLM.
b3th stats Shows commit count, unique files touched, and line additions/deletions for a given time-frame (e.g. --last 7d).
b3th summarize Uses an LLM to produce a one-paragraph summary of the last N commits (default 10).
b3th resolve Scans for Git merge conflicts, builds a per-file prompt, asks the LLM for a merged version, writes <file>.resolved; --apply overwrites originals with the suggestions.

(The legacy b3th commit still works but prints a deprecation warning and delegates to sync.)

Under the hood, b3th leverages Groq’s Chat Completions API for language generation and the GitHub REST API for PR creation.


Quick Install

1 · Prerequisites

  • Python ≥ 3.9
  • Git in your PATH.
  • Poetry (preferred) or plain pip. Install Poetry → curl -sSL https://install.python-poetry.org | python3 -

2 · Install the package

Option A – From PyPI (when published)
pipx install b3th         # keeps deps isolated
# or
pip install --user b3th

Important: Installing the package is not enough.
You still must provide credentials (see “Set up your secrets” below) via:

  • exported environment variables, or
  • a project-level .env file, or
  • a TOML config file (see examples below).
Option B – From source (recommended for contributors)
git clone https://github.com/bethvourc/b3th.git
cd b3th
poetry install

3 · Set up your secrets

You can provide credentials in either your shell environment, a project .env, or a TOML config file.

A) Environment variables or project .env (simplest)

Put this in your environment (e.g. export in shell init) or in a project-level .env:

# <repo>/.env   (project-level)
GROQ_API_KEY="sk_live_xxx"        # https://console.groq.com/keys
GITHUB_TOKEN="ghp_xxx"            # PAT with repo scope → https://github.com/settings/tokens
# Optional
# GROQ_MODEL_ID="llama-3.3-70b-versatile"

How .env loading works

b3th auto-loads the nearest .env in your project tree (using python-dotenv’s find_dotenv(usecwd=True)).
It does not automatically read ~/.env. If you prefer user-level credentials, either export them in your shell or use the TOML option below.

B) TOML config file (good for user-level/global setup)

Create:

~/.config/b3th/config.toml

On macOS/Linux with XDG:

$XDG_CONFIG_HOME/b3th/config.toml

Or point to a custom file via:

B3TH_CONFIG=/path/to/config.toml

Example contents:

[github]
token = "ghp_xxx"

[groq]
api_key = "sk_live_xxx"

Precedence: environment variables (including values loaded from the project .env) take priority over TOML.

Security tip: Add .env to your .gitignore and avoid committing secrets.

4 · (Dev only) Install Git hooks

poetry run pre-commit install   # auto-format & lint on each commit

CLI Usage

# One-shot stage → commit → push
poetry run b3th sync                   # interactive
poetry run b3th sync -y                # non-interactive

# Create a pull-request into 'main'
poetry run b3th prcreate               # interactive
poetry run b3th prcreate -b develop -y # specify base branch, skip confirm

# Create a draft pull-request to 'main'
poetry run b3th prdraft               # interactive confirm
poetry run b3th prdraft -b develop -y # specify base branch, skip confirm

# Git statistics (last 7 days)
poetry run b3th stats --last 7d

# Summarise last 15 commits
poetry run b3th summarize -n 15

# Generate conflict suggestions (writes *.resolved files)
poetry run b3th resolve

# Accept suggestions and overwrite originals
poetry run b3th resolve --apply

Sync Demo

$ b3th sync
Proposed commit message:
feat(utils): support .env loading

Load environment variables automatically from the nearest project .env
so users don't need to export them manually each session.

Proceed with commit & push? [y/N]: y
🚀 Synced! Commit pushed to origin.

Stats Demo

$ b3th stats --last 7d
Commits:    14
Files:      6
Additions:  +120
Deletions:  -34

Summarize Demo

$ b3th summarize -n 10
Introduce a comprehensive stats command, improve README instructions,
and fix a minor UI colour bug—enhancing insight, onboarding, and UX.

Resolve Demo

# Create .resolved files next to conflicted originals
$ b3th resolve
🔍 Detecting conflicts & asking the LLM…
💡 Generated 2 *.resolved file(s).
Inspect the *.resolved files. Run again with --apply to accept.

# Overwrite originals with merged suggestions
$ b3th resolve --apply
✅ Originals overwritten with LLM suggestions.

Conflict-Resolver Workflow

  1. Run b3th resolve to generate <file>.resolved for each conflicted file.
  2. Review the proposed merges; tweak if needed.
  3. Apply with b3th resolve --apply to overwrite originals and remove the .resolved files.
  4. Commit your merged changes.

Releasing (GitHub Actions + Trusted Publisher)

  1. poetry version patch (or minor/major) and commit.
  2. Tag: git tag -a v$(poetry version -s) -m "b3th v$(poetry version -s)" && git push origin v$(poetry version -s)
  3. The workflow builds and uploads to PyPI automatically.

Contributing

  1. Fork & clone.
  2. poetry install && pre-commit install
  3. Create a branch: git switch -c feat/your-idea
  4. Run pytest before pushing.
  5. Open a PR—b3th’s CI enforces ≥ 85 % coverage.

License

Licensed under the Proprietary License – see LICENSE for details.

Metadata

Release files for b3th 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for b3th 0.1.3
File Size Uploaded Provenance Actions
b3th-0.1.3.tar.gz 21.8 kB With provenance Details for b3th-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for b3th 0.1.3
File Interpreter ABI Platform Actions
b3th-0.1.3-py3-none-any.whl Python 3 none any Details for b3th-0.1.3-py3-none-any.whl

Total release size: 46.7 kB

Release files / b3th-0.1.3.tar.gz

Download URL b3th-0.1.3.tar.gz
Size 21.8 kB
Tags Source
SHA-256 checksum
How to use checksums
8ab0490e993f7c2dc56b25bc986e243ff480a2e90413e029edd2a77c694f790e
BLAKE2b-256 checksum
How to use checksums
2f26b8d006f746fe770055c3ad7db7d0ffc8cabd664bd69953dc27e2861189d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 1, 2025.

Transparency log

Release files / b3th-0.1.3-py3-none-any.whl

Download URL b3th-0.1.3-py3-none-any.whl
Size 24.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f938e5162b340047d489a537a9b608f9905d0667d4610586a1b6c42abda99a12
BLAKE2b-256 checksum
How to use checksums
8fa25d4627f7953b18d927b01a9683920bae1fe72f0aba6500d02fc755fe72a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 1, 2025.

Transparency log

Security for b3th 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for b3th-0.1.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 1, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page