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

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

gc-shell

⚙️ Configuration

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

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