A simple terminal wrapper that executes bash commands by default with colored output
See more demos in the gallery/ directory!
- Installation - Get started in under 1 minute
- Features - What can cc-bash do?
- Configuration - Customize your experience
- Why cc-bash? - What makes it different?
- Contributing - Help improve cc-bash
cc-bash bridges the gap between traditional shells and modern terminal experiences.
✅ No learning curve - It's just bash, with better UX
✅ Enhanced visibility - Colored output, clear status bar, persistent history
✅ Extensible - Aliases, snippets, workflows, plugins, themes
✅ Lightweight - Pure C, minimal dependencies (~3300 LOC)
✅ AI-ready - Python version with Claude SDK integration
| Feature | Plain Bash | Fish/Zsh | Warp | cc-bash |
|---|---|---|---|---|
| Bash compatibility | ✅ | ✅ | ✅ | |
| Colored output | Manual | Built-in | Built-in | ✅ |
| Status bar | ❌ | Plugin | Built-in | ✅ |
| History search | Ctrl+R | Ctrl+R | ✅ | ✅ |
| Tab completion | ✅ | ✅ | ✅ | ✅ |
| Command aliases | ✅ | ✅ | ✅ | ✅ |
| Parameterized templates | ❌ | ❌ | ❌ | ✅ (Snippets) |
| Multi-command workflows | ❌ | ❌ | ❌ | ✅ |
| Plugin system | ❌ | ✅ | ✅ | ✅ |
| Theme customization | ❌ | ✅ | ✅ | ✅ |
| AI integration | ❌ | Plugin | Built-in | ✅ (Python) |
| Resource usage | Minimal | Low | High | Minimal |
| Open source | ✅ | ✅ | ❌ | ✅ |
- Development workflows - Combine build, test, deploy commands into workflows
- System administration - Create snippets for common tasks with parameters
- Learning - Comments (#) let you annotate your command history
- AI pair programming - Use Python version with Claude for command suggestions
- Server management - Lightweight, runs over SSH with minimal dependencies
| Version | Language | AI Integration | Dependencies |
|---|---|---|---|
cc-bash |
C | No | None (pure POSIX) |
cc-bash-sdk.py |
Python | Yes (Claude SDK) | claude-agent-sdk, prompt_toolkit, rich |
Most users want the C version - it's fast, lightweight, and works everywhere.
# Install and run
git clone https://github.com/jcaldwell-labs/smartterm-prototype.git
cd smartterm-prototype && make && ./cc-bash
# Try it out
$ ls -la # Commands in cyan, output in white
$ grep -r "TODO" . # Colored grep output (automatic!)
$ # This is a note # Comments in yellow (not executed)
$ @help # Internal commands with @
$ @alias ll='ls -la' # Create shortcuts
$ ll # Use your alias
$ @quit # Exit (or Ctrl+D)What you get:
- Every command shows in color
- Status bar with directory, exit code, time
- History with Ctrl+R fuzzy search
- Tab completion for files and commands
- ⚡ Zero prefix - Type bash commands directly (no
!or$) - 🎨 Auto-colored output - PTY-based execution means ls, grep, etc. show colors
- 📊 Status bar - Current directory, last exit code, timestamp
- 🔍 Ctrl+R search - Fuzzy search through command history
- 📝 Persistent history - Saved to ~/.cc-bash-history
- 🔗 Aliases - Shortcuts like
alias gs='git status' - 📋 Snippets - Templates with params:
snippet find='find . -name "$1"' - 🔄 Workflows - Multi-command sequences:
workflow build='make clean && make' - 🔌 Plugins - Shell script hooks for custom behavior
- 🎨 Themes - Customize all colors via config
- 💬 Comments -
# notesdisplayed but not executed - ⌨️ Full line editing - Left/right arrows, delete, backspace
- 📑 Tab completion - Files, directories, commands
- 🚀 Minimal deps - Pure C, no ncurses or readline needed
Expand for detailed feature comparison
| Feature | Plain Bash | Fish/Zsh | Warp | cc-bash |
|---|---|---|---|---|
| Bash compatibility | ✅ | ✅ | ✅ | |
| Colored output | Manual | Built-in | Built-in | ✅ |
| Status bar | ❌ | Plugin | Built-in | ✅ |
| History search | Ctrl+R | Ctrl+R | ✅ | ✅ |
| Tab completion | ✅ | ✅ | ✅ | ✅ |
| Command aliases | ✅ | ✅ | ✅ | ✅ |
| Parameterized templates | ❌ | ❌ | ❌ | ✅ (Snippets) |
| Multi-command workflows | ❌ | ❌ | ❌ | ✅ |
| Plugin system | ❌ | ✅ | ✅ | ✅ |
| Theme customization | ❌ | ✅ | ✅ | ✅ |
| AI integration | ❌ | Plugin | Built-in | ✅ (Python) |
| Resource usage | Minimal | Low | High | Minimal |
| Open source | ✅ | ✅ | ❌ | ✅ |
# Build from source (< 1 minute)
git clone https://github.com/jcaldwell-labs/smartterm-prototype.git
cd smartterm-prototype
make
sudo make install
# Or install locally (no sudo)
make install PREFIX=$HOME/.local
export PATH="$HOME/.local/bin:$PATH"Alternative installation methods
brew tap jcaldwell-labs/cc-bash
brew install cc-bash
cp $(brew --prefix)/share/cc-bash/cc-bashrc.template ~/.cc-bashrc
mkdir -p ~/.cc-bash/pluginsyay -S cc-bash
# or: paru -S cc-bash
cp /usr/share/cc-bash/cc-bashrc.template ~/.cc-bashrc
mkdir -p ~/.cc-bash/pluginscurl -fsSL https://raw.githubusercontent.com/jcaldwell-labs/smartterm-prototype/master/install.sh | bash# Linux x86_64
curl -fsSL https://github.com/jcaldwell-labs/smartterm-prototype/releases/latest/download/cc-bash-linux-x86_64 -o cc-bash
chmod +x cc-bash
sudo mv cc-bash /usr/local/bin/
# Setup config
mkdir -p ~/.cc-bash/plugins
curl -fsSL https://raw.githubusercontent.com/jcaldwell-labs/smartterm-prototype/master/cc-bashrc.template -o ~/.cc-bashrc# Run cc-bash
cc-bash
# Try basic commands
$ ls -la
$ pwd
$ echo "Hello, cc-bash!"
# Try a note (displayed, not executed)
$ # This is my first note
# Get help
$ @help
# Exit
$ @quitcc-bash is configured via ~/.cc-bashrc. Edit with @edit and apply with @reload.
Quick examples below - See docs/CONFIGURATION.md for complete guide.
Aliases - Command shortcuts
# Define command shortcuts
alias ll='ls -la'
alias gs='git status'
alias gd='git diff'Usage: Type ll and it expands to ls -la
Snippets - Parameterized templates
# Define templates with $1, $2, etc. placeholders
snippet find-name='find . -name "$1"'
snippet grep-r='grep -r "$1" .'
snippet mkdir-cd='mkdir -p $1 && cd $1'Usage: @snippet find-name "*.c" → find . -name "*.c"
Workflows - Multi-step sequences
# Combine commands with && (stop on error) or ; (continue)
workflow build='make clean && make && make test'
workflow gitcheck='git status; git diff --stat'Usage:
@workflow- List all workflows@workflow build- Run the build workflow@workflow build --dry-run- Preview without executing
Themes - Customize colors
# Colors: black, red, green, yellow, blue, magenta, cyan, white
# Modifiers: bold, dim
theme.prompt=bold cyan
theme.error=bold red
theme.comment=green
theme.dim=dim
theme.header=bold white
theme.status=bold
theme.scroll=dimPlugins - Extend functionality
~/.cc-bash/plugins/<plugin-name>/
├── plugin.conf # Required: plugin manifest
├── config.conf # Optional: aliases/snippets/workflows
└── hooks/ # Optional: event hook scripts
├── on_startup.sh
├── on_cd.sh
└── on_post_command.sh
name=my-plugin
version=1.0
description=My custom plugin
# Event hooks (shell scripts)
hook.startup=hooks/on_startup.sh
hook.cd=hooks/on_cd.sh
hook.post_command=hooks/on_post_command.sh| Event | Environment Variables |
|---|---|
startup |
(none) |
shutdown |
(none) |
pre_command |
CCBASH_COMMAND |
post_command |
CCBASH_COMMAND, CCBASH_EXIT_CODE |
cd |
CCBASH_OLD_CWD, CCBASH_NEW_CWD |
See full plugin documentation for details.
For AI-powered assistance, use the Python version with Claude SDK integration.
Click to expand: Python setup and AI commands
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Run
python cc-bash-sdk.py| Command | Description |
|---|---|
@ask <question> |
Ask Claude anything |
@explain |
Have Claude explain the last command output |
@fix |
Have Claude suggest a fix for the last error |
@cmd <description> |
Generate a command from natural language |
› @cmd find files larger than 100MB
Generating command...
Suggested: find . -size +100M -type f
› some-command --wrong-flag
error: unknown flag --wrong-flag
› @fix
Asking Claude for fix...
╭─ Suggested Fix ───────────────────────────────────────╮
│ The flag --wrong-flag doesn't exist. Try using... │
╰───────────────────────────────────────────────────────╯
Keyboard shortcuts
| Key | Action |
|---|---|
Ctrl+R |
Fuzzy history search (type to search, Enter to use) |
Ctrl+C |
Cancel current input or search |
Ctrl+D |
Exit cc-bash |
Up/Down |
Navigate command history |
Left/Right |
Move cursor in input |
Tab |
Complete command/file (double-Tab for options) |
Esc |
Cancel search mode |
@ Commands reference
| Command | Shortcut | Description |
|---|---|---|
@help |
@h |
Show help |
@clear |
@c |
Clear screen |
@quit |
@q |
Exit cc-bash |
@edit |
@e |
Edit config file (~/.cc-bashrc) in $EDITOR |
@reload |
@r |
Reload configuration |
@alias |
- | List aliases (* = session only) |
@alias name=cmd |
- | Add session alias |
@alias save |
- | Save session aliases to config file |
@snippet [name args...] |
- | List snippets or run one with arguments |
@workflow [name] [--dry-run] |
- | List workflows, run one, or preview |
@theme |
- | Display current theme colors |
@hooks |
- | List registered event hooks |
@plugins |
- | List loaded plugins |
# Build cc-bash (default)
make
# Build and run
make run
# Build with debug symbols
make debug
# Clean
make clean
# Show all targets
make helpcc-bash takes a simple approach using ANSI escape codes instead of ncurses:
- Output stays visible - No TUI that hides when you type
- Readline for input - Command history, line editing
- ANSI colors - Works in any terminal
- Minimal dependencies - Just readline
An earlier POC used ncurses + readline integration. While the concept worked, the UX suffered:
- ncurses must suspend during readline input
- This causes the output area to disappear while typing
- Not the seamless experience we wanted
The current ANSI-based approach keeps all output visible at all times.
smartterm-prototype/
├── src/ # Source files
│ ├── cc-bash.c # C implementation (~3300 LOC)
│ └── cc-bash-sdk.py # Python + Claude SDK version
├── tests/ # Test files
│ ├── test_unit.c # Unit tests (240 tests)
│ └── test_cc_bash.sh # Static analysis tests
├── config/ # Configuration templates
│ └── cc-bashrc.template # Sample configuration
├── scripts/ # Utility scripts
│ └── install.sh # Installation script
├── docs/ # Documentation
├── gallery/ # Demo GIFs and screenshots
├── packaging/ # Package configs (Homebrew, AUR, Debian)
├── .github/ # GitHub Actions
│ └── workflows/
│ ├── ci.yml # CI pipeline
│ └── release.yml # Release automation
└── Makefile # Build configuration
~/.cc-bashrc # Configuration (aliases, snippets, workflows, themes)
~/.cc-bash-history # Command history
~/.cc-bash/plugins/ # Plugin directory
This project evolved from "smartterm-prototype":
- Original POC: Attempted ncurses + readline integration
- Problem discovered: ncurses suspend/resume causes output to disappear during input
- Library extraction: Created libsmartterm v1.0 (still available in lib/)
- Repurposed: Simplified to cc-bash using ANSI escape codes
- C version: Simple, working Claude Code-style bash wrapper
- Python + SDK: Added AI integration via Claude Agent SDK
See GitHub issue #14 for the repurposing discussion.
We welcome contributions! See CONTRIBUTING.md for guidelines.
Quick links:
- Good First Issues - Great for newcomers
- GitHub Discussions - Questions and ideas
- Code of Conduct - Community standards
Thank you to everyone who has contributed to cc-bash!
Want to see your name here? Check out our contribution guide!
MIT License - see LICENSE for details.
Need help? Check out:
- docs/SUPPORT.md - Common issues and solutions
- GitHub Issues - Bug reports and feature requests
- GitHub Discussions - Questions and community
cc-bash is part of the jcaldwell-labs portfolio:
| Project | Description |
|---|---|
| my-grid | ASCII canvas editor with vim-style navigation |
| boxes-live | Real-time ASCII box drawing |
| terminal-stars | Starfield animation for terminals |
| atari-style | Retro visual effects for terminal apps |
| Project | Description |
|---|---|
| my-context | Context tracking for development sessions |
| fintrack | Personal finance tracking CLI |
| Project | Description |
|---|---|
| adventure-engine-v2 | Multiplayer text adventure engine |
Inspired by Claude Code's terminal interface and Warp's modern terminal UX.