gc-shell 0.1.1

An intelligent AI-powered shell for macOS

🚀 Goutham Shell

A custom interactive shell for macOS that combines the power of a standard terminal with personalized built-in commands.

Installation

# 1. Clone the repository
git clone <repo-url>
cd gc-shell

# 2. Create a .env file with your Groq API key
echo 'GROQ_API_KEY=your_key_here' > .env

# 3. Install the shell
pip install .

# 4. Launch it!
gc-shell

Note: You need a Groq API key for the AI features. Sign up for free at groq.com, create an API key, and paste it in the .env file.

Development Mode

If you're working on the code and want changes to take effect immediately:

pip install -e .

Quick Start

$ goutham
🚀 Welcome to Goutham Shell v0.1.0
   Type help for commands, exit to quit.

💡 No app registry found. Run scan to discover installed applications.

goutham ~ ❯ scan
🔍 Scanning for applications...
✓ Found 142 applications
✓ Registry saved to ~/.goutham/apps.json

goutham ~ ❯ open chrome
▶ Opening Google Chrome...

goutham ~ ❯ running
┌──────────────────────────────┐
│   Running Applications       │
├────┬─────────────────────────┤
│  # │ Application             │
├────┼─────────────────────────┤
│  1 │ Finder                  │
│  2 │ Google Chrome           │
│  3 │ Terminal                │
└────┴─────────────────────────┘

goutham ~ ❯ ls -la
total 32
drwxr-xr-x  8 user staff 256 Jun 26 12:00 .
...

Features

System Commands

All standard terminal commands work transparently — they're forwarded to your system's zsh shell:

• ls, pwd, cat, grep, echo
• git status, git commit, git push
• python app.py, node server.js
• docker ps, npm run dev
• Pipes (|), redirection (>), chaining (&&)

Custom Commands

Command	Description
scan	Scan /Applications and build the app registry
open <app>	Open an application by name (fuzzy matching)
close <app>	Close a running application
apps	List all registered applications
running	List currently running GUI applications
tree [path]	Display a directory tree (--depth N)
preview <file>	Preview a file with syntax highlighting (--lines N)
mkp <dir>	Create nested directories (like mkdir -p)
search <pattern>	Find files by glob pattern (--path <dir>)
help	Show all available commands
exit / quit	Exit the shell

App Management

On first run, use scan to discover installed applications. Then use open and close with fuzzy name matching — no need to type the full name:

goutham ~ ❯ open chrome      # Opens "Google Chrome"
goutham ~ ❯ open code        # Opens "Visual Studio Code"
goutham ~ ❯ close spotify    # Closes "Spotify"

The open command is smart — paths, URLs, and flags are forwarded to the system open:

goutham ~ ❯ open .               # Opens current dir in Finder
goutham ~ ❯ open https://x.com   # Opens URL in default browser
goutham ~ ❯ open -a Safari       # System open with flags

Architecture

Goutham Shell is a wrapper shell — it intercepts custom commands while forwarding everything else transparently to zsh.

User Input → Command Parser → Custom Command? → Execute Handler
                                    ↓ No
                            Forward to zsh via subprocess

Key design decisions:

• Shell state is maintained in-process: cd updates current_directory so subsequent commands run in the right place.
• No hardcoded paths: All app paths come from the scanned registry at ~/.goutham/apps.json.
• shell=True forwarding: Preserves pipes, redirection, globbing, and chaining — users get the full power of zsh.

Requirements

• macOS 10.15+
• Python 3.9+
• Rich (installed automatically)

Configuration

All configuration is stored in ~/.goutham/:

File	Purpose
apps.json	Application registry (generated by scan)

Project Structure

goutham-shell/
├── main.py          # Entry point
├── shell.py         # Interactive REPL loop
├── executor.py      # Command routing & shell state
├── commands/
│   ├── apps.py      # open, close, apps, running
│   └── files.py     # tree, preview, mkp, search
├── registry/
│   └── scanner.py   # macOS app scanner
├── ai/              # Phase 5+ (AI commands)
├── utils/
├── pyproject.toml
└── README.md

Roadmap

• Phase 1 — Interactive shell skeleton
• Phase 2 — System command forwarding with persistent state
• Phase 3 — Custom built-in commands (app management)
• Phase 4 — File utility commands
• Phase 5 — AI commands (ai explain, ai generate, ai summarize)
• Phase 6 — LangGraph agent workflows

License

MIT