Metadata-Version: 2.4
Name: gc-shell
Version: 0.1.3
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

# gc-shell

`gc-shell` is an intelligent interactive shell for macOS that combines normal terminal command execution with custom application and filesystem utilities.

## Overview

This project provides a shell wrapper that:

- forwards normal commands to the system shell (`zsh`)
- maintains shell state such as the current working directory
- supports macOS application discovery and fuzzy app launch/close
- offers built-in file utilities like tree, preview, search, and recursive directory creation
- integrates with an AI planning layer to choose the right tool for user requests

## Key Features

- `scan` — discover installed macOS applications and save a registry
- `open <app>` — open an application, folder, or file by name
- `close <app>` — close a running macOS application
- `apps` — list registered applications
- `running` — list currently running GUI applications
- `tree [path] [--depth N]` — display a directory tree
- `preview <file> [--lines N]` — preview a text or source file
- `mkp <dir>` — recursively create directories
- `search <pattern> [--path <dir>]` — search files by glob pattern
- `cd` / `clear` / `help` — standard shell navigation and help commands

## Installation

### Prerequisites

- macOS
- Python 3.9 or newer
- Git

### Local setup

```bash
git clone https://github.com/GouthamReddy05/GC-Shell.git
cd GC-Shell
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
pip install -e .
```

### Run the shell

```bash
gc-shell
```

### Optional production install

```bash
pip install .
```

## Configuration

If AI features require a Groq key, create a `.env` file in the project root with:

```bash
echo 'GROQ_API_KEY=your_key_here' > .env
```

The shell loads environment variables via `python-dotenv` during startup.

## Usage

Start the shell with:

```bash
gc-shell
```

Then enter commands as you would in a normal terminal. Custom commands are handled by `gc-shell`; all other commands are forwarded to `/bin/zsh`.

## AI Integration

The shell includes an AI planner powered by `langgraph` and `langchain-groq`. The AI layer selects available tools for requests such as opening resources, changing directories, searching files, or running shell commands.

## Requirements

- macOS
- Python 3.9+
- `rich`
- `prompt_toolkit`
- `langchain-core`
- `langchain-groq`
- `langgraph`
- `python-dotenv`

## Project Structure

- `main.py` — application entry point
- `shell.py` — REPL loop and prompt handling
- `executor.py` — command routing and shell state management
- `commands/` — custom command implementations
- `registry/` — macOS application scanner and registry loader
- `AI/` — AI planner, tool registry, and prompts
- `pyproject.toml` — package metadata and dependencies

