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

Install from PyPI (Recommended)

pip install gc-shell

Run the shell:

gc-shell

Development Setup

Clone the repository and install dependencies:

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

Run:

python main.py

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.

Usage

Start the shell with:

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 built with langgraph and langchain, and supports models such as Qwen via OpenRouter.. 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-openrouter
• 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