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

"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

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

gem install parabot

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

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

# 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

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

parabot start                   # Launch Claude session
parabot message "analyze this"  # Send custom messages
parabot commands                # List 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"

• ✅ 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)

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

If you have Ruby and want gem management:

gem install parabot
parabot --version

Works in any Ruby project - no bundler conflicts!

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

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

# 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"]

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

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

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.

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

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

# 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

"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 projects ✅ Fixed! Parabot v1.0.0+ isolates its dependencies from your project's Gemfile.

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

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

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

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

MIT License - see LICENSE file for details.

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