bashcorrect

README

BashCorrect

AI-powered shell autocorrect and assistant. Hooks into your shell to fix failed commands and answer questions directly from the terminal.

Features

• Autocorrect — when a command fails, BashCorrect asks your AI provider for the fix, shows a colored diff, and prompts [y/N/edit]
• Direct queries — prefix any natural-language request with ? to get an AI answer in your terminal
• Inline buffer replacement — press Alt+Enter on any command to replace it with an AI suggestion before running
• Memory vault — create a deterministic local knowledge vault with structured pages and searchable markdown
• Multi-provider — switch between OpenAI, Anthropic, Gemini, and GitHub Copilot in one flag
• Multi-shell — bash, zsh, fish, and PowerShell 7+ (Linux, macOS, Windows)
• Single binary — no runtime dependencies; shell integration scripts are embedded and written on init

Installation

Requirements: Go 1.22+

go install github.com/Yoshiofthewire/bashcorrect@latest

Or build from source:

git clone https://github.com/Yoshiofthewire/bashcorrect
cd bashcorrect
make install

Cross-platform binaries (Linux, macOS, Windows — amd64 + arm64):

make dist   # outputs to dist/

Quick Start

1. Set up shell integration

bashcorrect init              # auto-detects your shell
# or specify explicitly:
bashcorrect init --shell bash
bashcorrect init --shell zsh
bashcorrect init --shell fish
bashcorrect init --shell powershell

This writes the integration script to ~/.config/bashcorrect/shell/ and appends a sourcing line to your rc file. Restart your shell or source the rc file.

If bashcorrect is not found after install, add your Go bin directory to PATH:

echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2. Configure a provider

Edit ~/.config/bashcorrect/config.toml (created automatically on first run):

active_provider = "openai"

[providers.openai]
api_key = "sk-..."
model   = "gpt-4o"

[providers.anthropic]
api_key = "sk-ant-..."

[providers.gemini]
api_key = "AIza..."

[providers.copilot]
# No key needed — auto-resolved from `gh auth login` or $GITHUB_TOKEN
model = "" # optional: leave empty for account-specific auto model selection

3. Use it

# Autocorrect — just run a broken command; BashCorrect triggers on non-zero exit
gti status
# → shows diff: - gti status / + git status
# → Run corrected command? [y/N/e(dit)]

# Direct query
? how do I recursively find files modified in the last 24 hours

# Summarize files via AI
? --summarize-files --file README.md

# Ask about specific files
? "find risks and suggest fixes" --file cmd/query.go --file cmd/vault_bootstrap_tools.go

# Alt+Enter — with cursor on any command in the buffer, press Alt+Enter
# to replace it with an AI suggestion before running

Commands

bashcorrect correct

bashcorrect correct --cmd <failed-command> --exit-code <N> [--stderr <output>]

Called automatically by the shell hook after a non-zero exit. Sends the failed command and exit code to the active provider, displays a colored diff, and prompts the user to accept, skip, or edit.

Flag	Description
--cmd	The failed command (required)
--exit-code	Exit code of the failed command (default 1)
--stderr	Captured stderr output to include as context

bashcorrect query

bashcorrect query <prompt> [flags]

Send a natural-language prompt to the active AI provider.

Flag	Description
--inline	Output only the extracted command (used by keybindings)
--cwd	Include current working directory as context
--history-lines N	Include last N lines of shell history as context
--file <path>	Include file content in prompt context (repeatable)
--summarize-files	Summarize the provided --file inputs (prompt optional)
--vault-path <path>	Override vault path used for memory context

Examples:

bashcorrect query "review for bugs" --file cmd/query.go --file README.md
bashcorrect query --summarize-files --file README.md

bashcorrect init

bashcorrect init [--shell bash|zsh|fish|powershell]
bashcorrect init bootstrap [--path <vault-path>] [--force]

Installs shell integration. Auto-detects the shell from $SHELL if --shell is omitted. Use init bootstrap to initialize only the AI memory vault (no shell hook installation).

bashcorrect vault

bashcorrect vault init
bashcorrect vault bootstrap
bashcorrect vault status
bashcorrect vault weather-location "Austin, TX"
bashcorrect vault new --type entity --title "GitHub Copilot CLI"
bashcorrect vault search "copilot"
bashcorrect vault get entity.github-copilot-cli
bashcorrect vault tools add hello --cmd "echo hi"
bashcorrect vault tools list
bashcorrect vault tools run hello

Manage a local memory vault inspired by wiki-style memory systems. The vault is stored by default at ~/.config/bashcorrect/vault and includes deterministic sections for entities, concepts, syntheses, sources, and reports.

On vault init, BashCorrect now automatically runs bootstrap setup by default:

• seeds IDENTITY.md, USER.md, and MEMORY.md
• keeps writable memory defaults in place
• creates TOOLS.md as a runnable tool registry
• removes BOOTSTRAP.md after bootstrap completes

Use bashcorrect vault init --no-bootstrap to skip this automation. Use bashcorrect vault bootstrap to rerun bootstrap on an existing vault. Use bashcorrect vault weather-location "<location>" to update location memory later without rerunning bootstrap.

Global flags

Flag	Description
--provider	Override active provider for this invocation
--model	Override model for this invocation
--config	Path to config file (default: $XDG_CONFIG_HOME/bashcorrect/config.toml)

Providers

Provider	Default model	How to authenticate
openai	gpt-4o	Set providers.openai.api_key in config
anthropic	claude-3-5-sonnet-20241022	Set providers.anthropic.api_key in config
gemini	gemini-1.5-pro	Set providers.gemini.api_key in config
copilot	auto (unset)	Auto-resolved from gh auth login → ~/.config/github-copilot/hosts.json, $GITHUB_TOKEN, or local gh copilot CLI fallback

Switch provider per-command:

bashcorrect query "explain this error" --provider anthropic

If GitHub's Copilot chat endpoint is unavailable for your token, BashCorrect will also try the local gh copilot CLI in non-interactive mode and capture its output.

Shell Integration Details

bash

• Autocorrect hook via PROMPT_COMMAND
• ? alias: ? what does chmod 755 mean
• Alt+Enter via bind -x '"\e\n":...'

zsh

• Autocorrect hook via add-zsh-hook precmd
• alias '?'='bashcorrect query'
• Alt+Enter via zle widget + bindkey

fish

• Autocorrect hook via fish_postexec event function
• abbr --add '?' 'bashcorrect query'
• Alt+Enter via bind \e\n

PowerShell (Linux / macOS / Windows)

Requires PowerShell 7+ (pwsh) and PSReadLine (included by default).

• Autocorrect hook wraps the existing prompt function, preserving any customisations
• bc? alias for queries (avoids conflict with built-in ? / Where-Object); override with $env:BASHCORRECT_ALIAS
• Alt+Enter via Set-PSReadLineKeyHandler -Chord 'Alt+Enter'
• Profile path: ~/.config/powershell/Microsoft.PowerShell_profile.ps1 (Linux/macOS) or Documents\PowerShell\Microsoft.PowerShell_profile.ps1 (Windows); override with $env:BASHCORRECT_PS_PROFILE

Configuration Reference

Default config (~/.config/bashcorrect/config.toml):

active_provider = "openai"
trigger_prefix  = "?"

[autocorrect]
auto_run  = false   # if true, run the fix without prompting
show_diff = true    # show before/after diff

[providers.openai]
api_key = ""
model   = "gpt-4o"

[providers.anthropic]
api_key = ""
model   = "claude-3-5-sonnet-20241022"

[providers.gemini]
api_key = ""
model   = "gemini-1.5-pro"

[providers.copilot]
api_key = ""        # leave blank to auto-resolve from gh CLI
model   = ""        # leave empty for Copilot auto-selection

Building

make build    # build ./bashcorrect
make install  # go install
make test     # go test ./...
make lint     # go vet + staticcheck
make dist     # cross-compile for all platforms → dist/

License

MIT