Amiberry Autonomous Troubleshooting

Debug and fix Amiberry bugs through iterative edit-build-run-test-fix cycles with minimal user interaction.

Bug to investigate

$ARGUMENTS

Environment

Amiberry source is at the current working directory (or a nearby amiberry/ directory). The MCP server (amiberry-mcp-server) provides tools for runtime control.

Determine the platform before building:

• •macOS: Build natively with cmake
• •Linux / WSL2: Build with cmake (use wsl -e prefix if on Windows host)

Build Commands

# Configure (first time or after CMake changes)
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DUSE_IPC_SOCKET=ON

# Build (subsequent changes)
cmake --build build -j$(nproc)

On Windows host targeting WSL2:

wsl -e bash -c "cd ~/amiberry && cmake --build build -j$(nproc)"

Troubleshooting Workflow

Phase 1: Understand the Bug

1. •Read the bug description / issue carefully
2. •Identify which subsystem is likely involved (graphics, input, audio, CPU emulation, chipset, config, GUI, etc.)
3. •Search the codebase for relevant code:
   • •Use Grep to find related functions, variables, error messages
   • •Use Glob to find relevant source files
   • •Read the code to understand the current behavior
4. •Form a hypothesis about the root cause

Phase 2: Reproduce

1. •

   Launch Amiberry with appropriate config:

   • •Use launch_and_wait_for_ipc to start Amiberry and wait for IPC readiness
   • •Specify a model (A500, A1200, etc.) or config file as needed
   • •This automatically enables logging
2. •

   Verify it's running:

   • •Use health_check to confirm process + IPC + emulation status
3. •

   Set up the reproduction scenario:

   • •Use runtime_load_config to load specific configurations
   • •Use runtime_insert_floppy to insert disk images
   • •Use send_key to navigate menus or trigger actions
   • •Use runtime_set_config to change specific options
4. •

   Observe the behavior:

   • •Use runtime_screenshot_view to see what's on screen
   • •Use tail_log to monitor log output
   • •Use runtime_get_fps to check performance
   • •Use runtime_get_cpu_regs / runtime_get_custom_regs for hardware state
5. •

   If it crashes:

   • •Use get_crash_info to detect the crash and analyze signals + log patterns
   • •Use get_process_info for exit code and signal details

Phase 3: Fix

1. •Make code changes using Edit tool on the Amiberry source files
2. •Keep changes minimal - fix only what's broken, don't refactor surrounding code
3. •Kill the running instance: Use kill_amiberry
4. •Rebuild:
   bash

   cmake --build build -j$(nproc)
   

5. •Check build output for errors. If build fails, fix and retry.

Phase 4: Verify

1. •

   Restart with same config: Use restart_amiberry or launch_and_wait_for_ipc

2. •

   Run the same reproduction steps from Phase 2

3. •

   Check results:

   • •runtime_screenshot_view - does the screen look correct?
   • •tail_log - are there still errors/warnings?
   • •get_crash_info - did it crash again?
   • •health_check - is everything still running?
4. •

   If NOT fixed: Go back to Phase 3 with new hypothesis

5. •

   If fixed: Clean up and report findings

Phase 5: Report

Summarize:

• •What the bug was (root cause)
• •What was changed (files and line numbers)
• •How to verify the fix
• •Any side effects or concerns

Available MCP Tools Reference

Process Lifecycle

Workflow

Observation

Emulation Control

Debugging

Media & Display

Amiga Keycodes (common)

To send a keypress, call send_key twice: once with state=1 (press), then state=0 (release).

Key Source Directories

Tips

• •Always use --log (handled automatically by launch_and_wait_for_ipc) for log output
• •Use tail_log frequently to catch errors early
• •If the screen looks wrong, pause_emulation + runtime_screenshot_view gives a stable frame
• •For timing-sensitive bugs, use runtime_set_config to change CPU speed or floppy speed
• •For crashes, the signal name in get_crash_info tells you a lot: SIGSEGV = null pointer/bad memory, SIGABRT = assertion/abort, SIGBUS = alignment
• •Build with Debug type (-DCMAKE_BUILD_TYPE=Debug) for better crash info
• •If you need to test multiple configs, use kill_amiberry + launch_and_wait_for_ipc between each