Shelly

An intelligent CLI assistant that analyzes your command-line history to provide smart, AI-powered suggestions for failed commands. Shelly helps you debug and fix errors without leaving your terminal, boosting productivity with advanced repository organization and AI-assisted development features.

Features

🔍 Core Error Analysis

• Smart Error Analysis: Uses AI to analyze command failures and suggest fixes
• Multi-Shell Support: Works with bash, zsh, tcsh
• Real-time History Access: Reliably gets the last command from your shell
• Command Suggestions: Suggests similar commands when you mistype
• Cross-Platform: macOS and Linux support

🏗️ Repository Organization

• AI-Powered Scaffolding: Complete project structure generation
• GitHub Integration: Automated templates, workflows, and issue templates
• Repository Setup: Automated GitHub repository configuration with best practices
• Package Enhancement: Automatic @juspay/ prefix and metadata optimization
• File Organization: Smart file placement and cleanup with --move option
• Configuration Setup: ESLint, Prettier, Commitlint, and more

🧠 Memory Bank System

• AI Context Management: Persistent project context for AI assistants
• Organized Documentation: Structured project knowledge base
• Neurolink Integration: Advanced AI content generation
• Development Continuity: Seamless context across development sessions
• Team Collaboration: Shared project understanding

Getting Started

Choose your installation method based on your needs:

🚀 For End Users (Recommended)

If you want to use Shelly as a command-line tool, install it globally:

npm install -g @juspay/shelly

📖 Next Steps: Follow the Quick Start Guide for complete setup instructions including shell integration and API configuration.

🛠️ For Developers & Contributors

If you want to contribute to the project or run it locally for development:

# Clone and navigate to project directory
git clone https://github.com/juspay/shelly.git

📖 Next Steps: Follow the Complete Setup Guide for detailed local development instructions.

Usage

Important: Shelly uses a dual CLI architecture with two distinct usage modes:

1. Error Analysis Mode: shelly (no arguments) - Analyzes the last failed command from your shell history
2. Repository Management Mode: shelly <command> - Uses specific commands like organize, memory, init, status

These are handled by different internal systems, so the commands work differently.

🔍 Error Analysis (Core Feature)

After setup, simply run shelly after any failed command:

$ grp "hello" file.txt
grp: command not found

$ shelly
Analyzing previous command: "grp "hello" file.txt"

Maybe you meant: grep "hello" file.txt

--- Neurolink Analysis ---
The error "grp: command not found" indicates that the shell could not find the 'grp' command.
The correct command is likely 'grep' which is used for searching text patterns in files.
--------------------------

Did you mean one of these?
- grep
- git
- gcc

🏗️ Repository Organization

Transform any project into a publication-ready repository:

# Organize current project with full scaffolding
shelly organize

# Force overwrite existing files
shelly organize --force

# Only add missing files, preserve existing ones
shelly organize --update

# Move misplaced files to correct directories
shelly organize --move

# Organize a specific directory
shelly organize --directory /path/to/project

# Check repository organization status
shelly status

# Initialize a brand new project
shelly init my-new-project
shelly init my-project --template typescript --directory ~/projects

🧠 Memory Bank Management

Create and maintain AI-assisted development context:

# Initialize Memory Bank for the current project
shelly memory init

# Force reinitialize existing Memory Bank
shelly memory init --force

# Check Memory Bank status and files
shelly memory status

# List all Memory Bank files with details
shelly memory list

# View specific Memory Bank file content
shelly memory show projectbrief.md
shelly memory show current/activeContext.md

# Update all Memory Bank files with latest project state
shelly memory update

# Update only a specific file
shelly memory update --file progress.md

🚀 GitHub Repository Setup

Configure your GitHub repository with industry best practices for publishing and collaboration:

# Full GitHub setup commands
shelly github setup                    # Interactive setup with confirmation
shelly github setup --force           # Skip confirmation prompts
shelly github setup --dry-run         # Preview changes without applying
shelly github setup --directory /path # Setup specific repository

# Shortcut commands (same functionality)
shelly gh                              # Shortcut for github setup
shelly gh --force                      # Quick forced setup
shelly gh --dry-run                    # Quick dry run

# Complete repository setup (GitHub + organize)
shelly setup                           # Run both GitHub setup AND organize
shelly setup --force                   # Skip all confirmations
shelly setup --github-only            # Only GitHub setup, skip organize
shelly setup --organize-only          # Only organize, skip GitHub setup

Prerequisites:

• Set your GitHub token: export GITHUB_TOKEN=your_token_here
• Admin access to the target repository
• Repository must be a Git repository with GitHub remote
• Required scopes: repo, admin:repo_hook, write:packages (for classic tokens)

What it configures:

• ✅ Repository merge settings (disable merge commits, disable squash merge, allow rebase only)
• ✅ Branch management (auto-delete branches, suggest PR updates, disable auto-merge)
• ✅ Branch protection ruleset "release" (restrict deletions, require linear history, require PR, block force pushes)
• ✅ GitHub Copilot code review (if available)
• ✅ GitHub Actions workflow permissions and fork PR approval settings
• ✅ NPM token setup guidance for automated publishing
• ✅ GitHub Pages configuration with docs folder structure

🔧 Advanced Error Analysis Options

Debug Mode

Enable detailed logging for troubleshooting:

SHELLY_DEBUG=true shelly

Analyze Specific Commands

You can analyze specific commands directly:

shelly "your-failed-command"
# Or for local setup: node src/main.js "your-failed-command"

Shell Override

Force detection of a specific shell:

SHELL_OVERRIDE=bash shelly

Supported Platforms and Shells

Supported Shells

• ✅ Bash - Full support with real-time history access
• ✅ Zsh - Full support with real-time history access (default on macOS Catalina+)
• ✅ Tcsh/Csh - Full support with direct alias integration
• 🔄 Fish - Partial support with fallback mode

Platform Support

• macOS: Fully supported (Zsh/Bash/Tcsh)
• Linux: Fully supported (Bash/Zsh/Tcsh)

How It Works

Shell Integration Mechanisms

Bash/Zsh: Uses the fc command with dynamic function generation for real-time history access.

Tcsh: Uses history 2 command with direct alias definition for reliable access to command history.

Fallback Mode: Reads shell history files directly from disk and uses process tree analysis to detect shell type.

Analysis Process

1. Shell Integration: Captures your last command directly from shell memory or history
2. Command Analysis: Analyzes the failed command and its error output
3. AI-Powered Suggestions: Uses advanced analysis to suggest corrections and alternatives

Features in Detail

🔍 Error Analysis

• AI Analysis: Intelligent error interpretation and suggestions using NeuroLink
• Command Correction: Suggests likely intended commands for typos
• History Context: Uses command history for better analysis
• Pattern Recognition: Learns from common error patterns and user corrections

🏗️ Repository Organization

• Smart Scaffolding: Creates complete project structure with industry best practices
• GitHub Templates: Automated issue templates, PR templates, and workflow setup
• Repository Configuration: Automated GitHub settings for merge policies, branch protection, and publishing
• Configuration Management: ESLint, Prettier, Commitlint, and semantic-release setup
• Package Optimization: Enhances package.json with @juspay/ scoping and metadata
• File Classification: Intelligent file organization with --move option
• Project Templates: Support for different project types (React, TypeScript, CLI tools)
• GitHub Pages Setup: Automated documentation site configuration

🧠 Memory Bank System

• Project Context: Maintains comprehensive project understanding for AI assistants
• Structured Documentation: Organized into project, technical, and current state files
• AI Integration: Seamless integration with Cline and other AI development tools
• Neurolink Content: Advanced AI-generated documentation using Google Vertex AI
• Development Continuity: Preserves context across development sessions and team changes
• Knowledge Management: Central repository for project decisions and evolution

🐚 Shell Integration

• Multi-shell Support: Native support for bash, zsh, and tcsh
• History Access: Retrieves commands from shell history or live session
• Process Tree Analysis: Intelligently detects your current shell
• Alias Generation: Automatic shell integration setup

Troubleshooting

📚 Detailed Troubleshooting Guide: For comprehensive installation and runtime troubleshooting, including native module build issues, see the Complete Troubleshooting Guide.

Common Issues

"Could not retrieve the last command from history"

This usually means the shell integration isn't set up correctly.

Solutions:

# For Bash - ensure history is enabled
echo 'HISTSIZE=1000' >> ~/.bashrc
echo 'SAVEHIST=1000' >> ~/.bashrc

# For Zsh - check history settings
echo 'HISTSIZE=1000' >> ~/.zshrc
echo 'SAVEHIST=1000' >> ~/.zshrc

# For Tcsh - ensure history is enabled
echo 'set history = 1000' >> ~/.tcshrc
echo 'set savehist = 1000' >> ~/.tcshrc

"shelly: command not found"

Cause: The alias wasn't set up correctly or shell config wasn't reloaded.

Solutions:

1. Check that you added the correct line to your shell configuration file
2. Restart your terminal or run source ~/.bashrc (or equivalent for your shell)
3. For global installation, ensure the package is installed: npm list -g @juspay/shelly
4. For local development, ensure you're using the correct commands from the Complete Setup Guide

Commands not being analyzed

Ensure you're running shelly immediately after the failed command. The tool analyzes the most recent command in your shell history.

Tcsh Path Issues

Cause: The absolute path in the tcsh alias is incorrect.

Solution: Use pwd in the project directory to get the correct path and update your alias.

Debug Information

Enable debug mode to see detailed information about what the tool is doing:

SHELLY_DEBUG=true shelly

Quick Reference

Command Summary

Error Analysis:

shelly                    # Analyze last failed command
shelly "command"          # Analyze specific command

Repository Organization:

shelly organize           # Organize repository structure
shelly organize --force   # Overwrite existing files
shelly organize --update  # Only add missing files
shelly status            # Check organization status

GitHub Setup:

shelly gh                 # Quick GitHub setup (shortcut)
shelly github setup       # Full GitHub setup
shelly gh --dry-run       # Preview changes

Complete Setup:

shelly setup              # GitHub setup + organize
shelly setup --force      # Skip all confirmations

Memory Bank:

shelly memory init        # Initialize project memory
shelly memory status      # Check memory status
shelly memory update      # Update all memory files

Project Initialization:

shelly init project-name  # Create new project

One-Time Setup Commands

Bash:

echo 'eval "$(shelly --alias)"' >> ~/.bashrc && source ~/.bashrc

Zsh:

echo 'eval "$(shelly --alias)"' >> ~/.zshrc && source ~/.zshrc

Fish:

echo 'shelly --alias | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish

Usage Workflow

1. Run a command (it may fail)
2. Type shelly
3. Get AI-powered analysis and suggestions
4. Apply the suggested fix

Configuration

The tool automatically detects your shell and adapts its behavior accordingly. No additional configuration is required for basic usage.

Contributing

Contributions are welcome! Please feel free to submit issues and enhancement requests.

Uninstallation

Remove Shell Integration

Remove the eval "$(shelly --alias)" line from your shell configuration file and reload your shell.

License

MIT License