Bgpt is an AI-powered terminal assistant that converts natural language into shell scripts, explains what each command does, and runs commands with built-in safety checks. It supports Gemini, OpenAI, Anthropic, and local Ollama models so developers, DevOps engineers, and power users can automate terminal workflows faster and more safely.

Bgpt is a customizable AI-powered shell assistant. It converts natural-language requests into shell commands, applies safety checks, and executes commands with confirmation and timeout controls.

• Multi-provider AI: gemini, openai, anthropic, local (Ollama)
• Safety pipeline with risk scoring, blocking rules, warnings, and confirmation
• Redesigned terminal UX with profile-based customization
• Agentic decision mode (auto decides run vs confirm based on risk)
• Interactive chat mode and one-shot mode
• Command history with execution metadata
• Setup wizard and diagnostics command

pip install bgpt-primecodez

After installation, run the CLI with:

bgpt --help

git clone https://github.com/primecodez01/Bgpt.git
cd Bgpt
python -m venv .venv
source .venv/bin/activate
pip install -e .

If you need all providers and extras:

pip install -r requirements.txt

bgpt --setup

bgpt "find all python files larger than 50MB"

bgpt --chat

bgpt --explain "ls -la | grep py"

Bgpt reads API keys from either:

• Environment variables
• System keyring (when saved by setup wizard)

Supported environment variables:

• GEMINI_API_KEY
• OPENAI_API_KEY
• ANTHROPIC_API_KEY

Optional model overrides:

• BGPT_GEMINI_MODEL
• BGPT_OPENAI_MODEL
• BGPT_ANTHROPIC_MODEL
• BGPT_LOCAL_MODEL

Preferred workflow: use bgpt --setup to pick provider + model and persist it in config.

Bgpt now supports user-level terminal customization persisted in ~/.bgpt/config.json.

• default
• sunset
• matrix
• midnight
• minimal

• arrow (default)
• classic
• minimal

• Compact mode on/off
• Timestamp display on/off
• Tips on/off
• Command preview lines (3-30)

bgpt config set --profile matrix --prompt-style classic
bgpt config set --compact --timestamps --tips
bgpt config set --preview-lines 20
bgpt config set --timeout 120
bgpt config set --provider openai --safety-level high
bgpt config set --model-provider openai --model gpt-4o-mini
bgpt config set --theme hacker
bgpt config set --agentic --hide-details --agentic-risk low
bgpt config show

/profile matrix
/style classic
/theme hacker
/compact on
/timestamps off
/tips off
/preview 18
/provider gemini
/model gemini-2.5-flash
/model openai gpt-4o-mini
/agentic on
/details off
/agentic-risk low
/safety medium
/timeout 90
/config

Before execution, Bgpt performs:

1. Syntax validation
2. Command parsing and operation classification
3. Safety scoring (low/medium/high)
4. Hard-block checks for dangerous patterns
5. Confirmation flow for risky commands

Commands can be blocked outright if they match critical destructive patterns.

Config file path:

~/.bgpt/config.json

Example:

{
 "provider": "gemini",
 "theme": "default",
 "safety_level": "medium",
 "auto_execute": false,
 "agentic_mode": false,
 "show_command_details": true,
 "agentic_auto_execute_max_risk": "low",
 "save_history": true,
 "command_timeout": 60,
 "enabled_plugins": ["git", "mcp"],
 "models": {
 "gemini": "gemini-2.5-flash",
 "openai": "gpt-4o-mini",
 "anthropic": "claude-3-5-sonnet-latest",
 "local": "tinyllama"
 },
 "ui": {
 "profile": "default",
 "prompt_style": "arrow",
 "compact_mode": false,
 "show_timestamps": true,
 "show_tips": true,
 "command_preview_lines": 12
 }
}

# Chat mode
bgpt --chat
# One-shot generation and execution flow
bgpt "show top 10 processes by memory"
# Diagnostics
bgpt --doctor
# Show history
bgpt --history
# Setup local Ollama model
bgpt setup-local

Current plugin registry includes:

• git
• docker
• system
• mcp

Manage plugins:

bgpt plugins list
bgpt plugins install git
bgpt plugins enable git
bgpt plugins disable git
bgpt plugins uninstall git

To prepare local/offline usage:

bgpt setup-local

This checks Ollama availability and attempts to set up a lightweight model.

• Run bgpt --doctor
• Verify API keys are configured
• Switch provider: bgpt config set --provider gemini

• Increase timeout: bgpt config set --timeout 180

• Set explicit model override (BGPT_*_MODEL)
• Try another provider

• Install textual dependency:

pip install textual>=0.50.0

Run editable install and checks:

pip install -e .
python -m bgpt.main --help

• ai-cli
• terminal-assistant
• natural-language-to-shell
• shell-automation
• command-generation
• devtools
• productivity
• llm-tools
• agentic-cli
• command-safety
• python-cli
• mcp
• ollama
• openai
• anthropic
• gemini

• MIT (current): simple permissive license, best for fast adoption
• Apache-2.0: permissive plus explicit patent grant
• GPL-3.0: strong copyleft for derivative work
• AGPL-3.0: copyleft including network/SaaS use

Recommended default for this project: MIT or Apache-2.0.

MIT