🤖 Parabot Ruby CLI

AI-powered Test-Driven Development assistant with seamless tmux integration

Parabot is a modern Ruby CLI tool that connects your development workflow with Claude AI, providing intelligent test execution, project analysis, and TDD guidance across multiple programming languages.

🤖 Why "Parabot"?

"Para" + "bot" = Parallel + Robot/Bot

Parabot's core function as an AI assistant that works alongside (parallel to) your development workflow:

Key aspects of the "parallel" concept:

  • Parallel Terminal Sessions - Runs Claude in a separate tmux pane alongside your coding
  • Parallel Workflow - Works with your existing TDD process without interrupting it
  • Parallel Analysis - Analyzes test results while you continue coding
  • Parallel Intelligence - Provides AI assistance that complements your development skills

What Parabot Does

  • 🔄 Runs your tests and sends results to Claude for analysis
  • 🧠 Provides AI guidance for test-driven development
  • 🖥️ Integrates with tmux for seamless terminal workflow
  • 🌐 Supports multiple languages (Ruby, Elixir, JavaScript, TypeScript, Kotlin, Shell)
  • ⚙️ Highly configurable with YAML configuration files you can add new and customize existing languages
  • 🚀 Works anywhere - various installation methods

🚀 Quick Installation

gem install parabot

Option 2: Installation Script

curl -sSL https://raw.githubusercontent.com/AlexParamonov/parabot/main/scripts/install | bash

Option 3: Manual Download

curl -L https://github.com/AlexParamonov/parabot/releases/latest/download/parabot -o parabot
chmod +x parabot && sudo mv parabot /usr/local/bin/

Requirements: Ruby 3.0+ on Linux or macOS


Quick Start

# Initialize parabot in your project
parabot init

# Start Claude AI session in tmux
parabot start

# Run tests with AI analysis
parabot test

# Send custom message to Claude
parabot "analyze this code for potential issues"

# Check version
parabot --version

🎯 Core Features

🔬 Intelligent Test Execution

parabot test                    # Run all tests
parabot test spec/user_spec.rb  # Run specific file
parabot test --language ruby    # Force language detection

🤖 AI Integration

parabot start                   # Launch Claude session
parabot message "analyze this"  # Send custom messages
parabot commands                # List custom commands

📋 Custom Commands

Define shortcuts in .parabot.yml:

commands:
  review: "review my latest changes and provide suggestions"
  debug: "help me debug this failing test"
  optimize: "suggest performance improvements"

Use them directly:

parabot review    # Sends review message to Claude
parabot debug     # Sends debug message to Claude

Add more context to your commands:

parabot review spec/user_spec.rb
parabot review and analyze changes in the last commit
parabot review "let's review the last 5 commits"

🛠️ Installation Details

Installation Script Features

  • Automatic platform detection (Linux/macOS)
  • Smart installation paths (/usr/local/bin, ~/bin, ~/.local/bin)
  • Ruby version validation (ensures 3.0+)
  • Permission handling (chooses location based on access)

Manual Installation Options

System-wide installation:

sudo cp parabot /usr/local/bin/

User installation:

mkdir -p ~/.local/bin
cp parabot ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

Verify installation:

parabot --version

For Ruby Developers

If you have Ruby and want gem management:

gem install parabot
parabot --version

Works in any Ruby project - no bundler conflicts!


⚙️ Configuration

Initialize Configuration

parabot init  # Creates .parabot.yml with sensible defaults

If you want to specify project languages instead of reling on auto-detection, you can use the -l or --language option:

parabot init -l ruby,typescript

Configuration Hierarchy

  1. ./.parabot.yml (project-specific)
  2. ~/.config/parabot/.parabot.yml (user-wide)
  3. ~/.parabot.yml (global)

Example Configuration

# Test commands per language
test_command:
  ruby: bundle exec rspec
  elixir: mix test --trace
  javascript: npm test

# Custom AI commands
commands:
  review: "review my latest changes and provide suggestions"
  debug: "help me debug this failing test"
  commit: "create a logical git commit message"

# Language-specific settings
languages:
  ruby:
    file_extensions: [".rb", ".rake"]
    project_files: ["Gemfile", "Rakefile"]
  elixir:
    file_extensions: [".ex", ".exs"]
    project_files: ["mix.exs"]

🌐 Multi-Language Support

Language Auto-Detection Default Test Command
Ruby Gemfile, *.rb bundle exec rspec
Elixir mix.exs, *.ex mix test --trace
JavaScript package.json, *.js npm test
TypeScript tsconfig.json, *.ts npm test
Kotlin build.gradle.kts, *.kt ./gradlew test
Shell *.sh, *.bash bats

Language Detection Process

Parabot detects the programming language of your project using multiple methods: Auto-detection:

  • Based on test command parameters like test flies, directories, and glob patterns.
  • Based on project files like Gemfile, mix.exs, package.json, etc.

User forced:

  • parabot test --language ruby
  • language option in .parabot.yml

🖥️ Tmux Integration

How It Works

Parabot automatically finds Claude sessions by:

  1. Looking for sessions named "claude" (case-insensitive)
  2. Scanning for Claude processes in any tmux session
  3. Creating new sessions if needed

Session Management

parabot start     # Start Claude in new tmux pane
parabot message   # Send message to active Claude session

No tmux? Parabot allows you to add own adapters and reference them in configuration file. You can also use --dry-run mode to see what would happen without needing tmux.


🔧 Command Reference

Core Commands

parabot init                    # Initialize project configuration
parabot start                   # Start Claude AI session
parabot test [files...]         # Run tests with AI analysis
parabot message "text"          # Send message to Claude
parabot commands                # List available custom commands
parabot doctor                  # Diagnose configuration issues
parabot version                 # Show version information

Global Options

--dry-run                       # Show what would happen
--language, -l LANG             # Force language detection
--config, -c FILE               # Use specific config file
--help, -h                      # Show help

Examples

# Test specific files with language override
parabot test --language ruby spec/user_spec.rb spec/auth_spec.rb

# Dry-run to see what would happen
parabot --dry-run test

# Dry-run to see what would happen
parabot --dry-run start

# Custom configuration file
parabot --config ~/.custom-parabot.yml test

🐛 Troubleshooting

Common Issues

"Ruby version too old"

ruby --version  # Check current version
# Install Ruby 3.0+ using rbenv, asdf, or system package manager

"Command not found"

# Check if installation directory is in PATH
echo $PATH
# Add to PATH if needed:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

"Tmux not found"

# Install tmux
sudo apt install tmux    # Ubuntu/Debian
brew install tmux        # macOS
# Or use dry-run mode: parabot --dry-run test

Bundler conflicts in Ruby projectsFixed! Parabot v1.0.0+ isolates its dependencies from your project's Gemfile.


🏗️ Development

Setup

git clone https://github.com/AlexParamonov/parabot.git
cd parabot
bundle install

Testing

bundle exec rspec              # Run all tests
bundle exec rake fast          # Fast test subsets

Building & Distribution

gem build parabot.gemspec                # Build gem
./scripts/build-distribution             # Build standalone executable
./scripts/install                       # Test installation script

🤝 Contributing

  1. Fork the repository
  2. Create feature branch: git checkout -b feature/amazing-feature
  3. Add tests for new functionality
  4. Ensure all tests pass: bundle exec rspec
  5. Submit pull request

📄 License

MIT License - see LICENSE file for details.


🆚 Why Parabot Ruby CLI?

vs Manual Testing:

  • ✅ Automatic AI analysis of test results
  • ✅ Contextual guidance for failures
  • ✅ Multi-language support

vs Shell Scripts:

  • ✅ Robust error handling
  • ✅ Cross-platform compatibility
  • ✅ Extensible architecture
  • ✅ Comprehensive testing

vs Other AI Tools:

  • ✅ TDD-focused workflow
  • ✅ Seamless terminal integration
  • ✅ Project-aware context
  • ✅ No bundler conflicts

Ready to supercharge your TDD workflow? Install parabot and start building better software with AI assistance! 🚀

gem install parabot
parabot init && parabot start