gc-shell 0.1.0

An intelligent macOS shell

🚀 Goutham Shell

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

Installation

# Clone the repository
git clone <repo-url>
cd goutham-shell

# Install in development mode
pip install -e .

# Launch the shell
goutham

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