ShellBuddy
Open-Source Developer Tools
ShellBuddy
Ambient AI coach for your terminal: contextual command suggestions without breaking your flow.
💡 hint: try z ai-systems (faster navigation via zoxide)
$ ls -la
💡 hint: try eza -la --git --icons (modern tree view with git status)
$ shellbuddy /tip "how to find large files over 100MB"
→ find . -type f -size +100M -exec ls -lh {} + | awk '{print $9, $5}'
The Problem
Most developers know modern CLI tools exist (zoxide, ripgrep, fd, eza, bat, fzf), but when muscle memory takes over during high-pressure debugging or systems coding, we revert back to archaic shell habits.
Switching contexts to search Google or query a browser-based chat LLM breaks concentration. ShellBuddy bridges this gap by acting as a quiet, ambient coach inside your terminal session.
Key Features
Ambient Context Awareness
Runs as a lightweight tmux status strip or background daemon. It monitors commands you type in real-time and offers inline alternative hints without blocking execution.
Two-Tier Intelligence
Sub-millisecond regex heuristics fire instantly for high-frequency patterns. Complex situational suggestions are handed off to a local or configured LLM backend.
Offline Knowledge Base
Includes a compiled kb.json engine generated from developer cheat-sheets, manpages, and best practices. Operates completely offline with zero latency.
Interactive /tip Utility
Ask for quick shell recipes directly from your prompt using plain English: shellbuddy /tip "compress folder to tar.zst".
Architecture & Design
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
┌────────────────────────────────────────────────────────┐
│ Interactive Terminal / tmux │
└───────────────────────────┬────────────────────────────┘
│
stdin command stream / /tip queries
▼
┌────────────────────────────────────────────────────────┐
│ ShellBuddy Daemon │
├────────────────────────────┬───────────────────────────┤
│ Tier 1: Instant Regex │ Tier 2: Knowledge Base │
│ (sub-millisecond rule) │ (kb_engine.py / JSON) │
└────────────────────────────┼───────────────────────────┘
▼
┌────────────────────────────────────────────────────────┐
│ Modular Backend Connectors │
│ (Local Ollama / Llama.cpp / Custom Endpoints) │
└────────────────────────────────────────────────────────┘
- Core Engine (
app/,kb_engine.py): Written in clean, modular Python with zero unnecessary dependencies. - Compiled KB (
kb.json): Deterministically built from structured rule definitions usingkb_builder.py. - Desktop Companion (
app/): Electron-based visual companion interface for visual exploration and configuration management.
Quickstart & Installation
Clone and install ShellBuddy into your local environment:
1
2
3
4
5
6
7
8
9
10
11
12
# Clone the repository
git clone https://github.com/bhargavachary/shellbuddy.git
cd shellbuddy
# Install into active environment
make install
# Run the test suite
make test
# Launch ambient mode
shellbuddy --ambient
Contribute or Explore Source
ShellBuddy is open source and published under the MIT license. Pull requests, issues, and custom knowledge base contributions are welcome.