b3th
AI-powered CLI that stages, commits, pushes, proposes merge resolutions, and opens pull-requests for you.
✨ 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
.envfile, 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
.envloading worksb3th auto-loads the nearest
.envin your project tree (usingpython-dotenv’sfind_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
.envto your.gitignoreand 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
- Run
b3th resolveto generate<file>.resolvedfor each conflicted file. - Review the proposed merges; tweak if needed.
- Apply with
b3th resolve --applyto overwrite originals and remove the.resolvedfiles. - Commit your merged changes.
Releasing (GitHub Actions + Trusted Publisher)
poetry version patch(orminor/major) and commit.- Tag:
git tag -a v$(poetry version -s) -m "b3th v$(poetry version -s)" && git push origin v$(poetry version -s) - The workflow builds and uploads to PyPI automatically.
Contributing
- Fork & clone.
poetry install && pre-commit install- Create a branch:
git switch -c feat/your-idea - Run
pytestbefore pushing. - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.