lumby 0.1.0

Smart command wrapper with AI-powered failure diagnosis

Lumby

A CLI tool that wraps shell commands, streams output live, and provides AI-powered diagnosis when commands fail.

Named after Lumbridge in Old School RuneScape - where you respawn after death with knowledge of what killed you.

Installation

pip install lumby

Or install from source:

git clone https://github.com/RasmusGodske/lumby.git
cd lumby
pip install -e .

Usage

Lumby uses -- to separate its flags from the wrapped command:

# Basic usage - wrap any command
lumby -- php artisan test --parallel
lumby -- npm run build
lumby -- cargo build

# With configuration
lumby --log-level=debug -- make test
lumby --response-guide="Keep it under 2 sentences" -- pytest
lumby --config=./lumby.json -- ./vendor/bin/phpstan

What Happens

1. Command runs normally - You see output in real-time, just like running the command directly
2. On success - Lumby exits with the same exit code (0)
3. On failure - Lumby captures the output, sends it to Claude for diagnosis, and shows you a concise explanation of what went wrong

Example Output

$ lumby -- php artisan test --filter=UserTest

   FAIL  Tests\Feature\UserServiceTest::test_user_creation_validates_email
   Expected exception [InvalidArgumentException] was not thrown.

   Tests:    1 failed, 15 passed
   Duration: 2.34s

════════════════════════════════════════════════════════════════════
   Diagnosis
════════════════════════════════════════════════════════════════════

The test expects InvalidArgumentException when creating a user with
invalid email, but UserService::create() doesn't validate email format.
Add email validation before line 45 in app/Services/UserService.php.

════════════════════════════════════════════════════════════════════

Configuration

CLI Flags

Flag	Description
--config PATH	Path to JSON config file
--log-file PATH	Path to log file
--log-level LEVEL	Log level: debug, info, warning, error
--response-guide TEXT	Guide for AI response length/style
--prompt-file PATH	Path to custom prompt template
--verbose	Shortcut for detailed diagnosis

Config File

Create a lumby.json:

{
  "log_file": "/tmp/lumby.log",
  "log_level": "info",
  "response_guide": "Keep it under 3 sentences"
}

Use it:

lumby --config=./lumby.json -- npm test

Environment Variables

Variable	Description
LUMBY_LOG_FILE	Path to log file
LUMBY_LOG_LEVEL	Log level
LUMBY_RESPONSE_GUIDE	Response guideline
LUMBY_PROMPT_FILE	Path to prompt template

Configuration Priority

CLI flags > Config file > Environment variables > Defaults

Custom Prompts

Create a custom prompt template with these variables:

• {command} - The command that was run
• {exit_code} - The exit code
• {output} - The captured output
• {response_guide} - The response guideline

Example my-prompt.md:

Analyze this failed command:

Command: {command}
Exit code: {exit_code}

Output:
{output}

{response_guide}

Use it:

lumby --prompt-file=./my-prompt.md -- make build

Use Cases

In CI/CD Pipelines

Get immediate diagnosis when builds fail:

# GitHub Actions
- name: Run tests
  run: lumby -- npm test

Wrapping Test Runners

# In your test script
#!/bin/bash
lumby -- php artisan test "$@"

Development Workflow

# Quick iteration with diagnosis
lumby -- cargo build && ./target/debug/myapp

Requirements

• Python 3.11+
• Claude API access (via claude-agent-sdk)

Why "Lumby"?

The name comes from Lumbridge, the starting town in Old School RuneScape.

In OSRS, when your character dies, you respawn in Lumbridge, affectionately called "Lumby" by players. You wake up at the castle, slightly confused, but with the knowledge of what killed you. Maybe it was that level 80 dragon you weren't ready for. Maybe you forgot to bring food. Either way, you learn from the experience.

That's exactly what this tool does. When your command "dies" (fails), you respawn with a diagnosis of what went wrong, so you can try again, smarter this time.

Home teleport to Lumby.

License

MIT