gc-shell 0.1.3

An intelligent AI-powered shell for macOS

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

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

Optional production install

pip install .

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