Metadata-Version: 2.4
Name: gc-shell
Version: 0.1.2
Summary: An intelligent AI-powered shell for macOS
Author: Goutham Reddy
License: MIT
Project-URL: Homepage, https://github.com/GouthamReddy05/GC-Shell
Project-URL: Repository, https://github.com/GouthamReddy05/GC-Shell
Project-URL: Issues, https://github.com/GouthamReddy05/GC-Shell/issues
Keywords: shell,terminal,cli,ai,langchain,langgraph,macos
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: rich>=13.0
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-groq>=0.3.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: python-dotenv>=1.0.0

# 🚀 Goutham Shell

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

## Installation

```bash
# 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](https://console.groq.com/keys) for the AI features.
> Sign up for free at [groq.com](https://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:

```bash
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](https://github.com/Textualize/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

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

## License

MIT
