Metadata-Version: 2.4
Name: gc-shell
Version: 0.1.4
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, AI‑powered interactive shell for macOS. It combines normal terminal command execution with custom macOS‑specific utilities and an AI planner that can intelligently choose the right tool for user requests.

## 🚀 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


### 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
```

## ⚙️ 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.

## 🧠 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.

## 🤝 Contributing

We welcome contributions to make `gc-shell` even better!
1. Fork the repository.
2. Create a new branch (`git checkout -b feature/amazing-feature`).
3. Make your changes.
4. Run linting (`ruff check .`).
5. Commit your changes (`git commit -m 'Add amazing feature'`).
6. Push to the branch (`git push origin feature/amazing-feature`).
7. Open a Pull Request.

## 📝 Changelog

### [0.1.4] - Current
- Refactored `executor.py` to a class-based architecture for better state management.
- Integrated AI tools with the new Executor class.
- Added comprehensive execution flow documentation in `architecture.md`.
- Fixed linter warnings and unused imports.

### [0.1.3] - Previous
- Initial release with AI planner and macOS app registry integration.

## 📁 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
- `architecture.md` — detailed architecture and execution flow documentation
- `pyproject.toml` — package metadata and dependencies

