segcatch

Code Generating Agents Seg Fault Detection

A Go-based process wrapper that captures and reports crash information from C++ applications, making it accessible to AI coding agents like Claude Code.

The Problem

When AI coding agents run C++ programs that crash, critical debugging information is often lost. For example, when a program segfaults, the shell displays:

zsh: segmentation fault  ./my_program

However, AI agents typically only see:

(program output before crash)

The signal information, exit codes, and crash details are not passed through, leaving the AI agent unable to diagnose the issue effectively.

The Solution

segcatch is a lightweight wrapper that:

1. Captures all crash information: Signal type, exit codes, and program output
2. Formats it clearly: Presents crash data in an easy-to-read format
3. Optionally provides detailed debugging: Uses lldb/gdb to generate backtraces showing exactly where and why the crash occurred

Example Output

Without debug mode:

Process terminated by signal: segmentation fault (11)
Description: Invalid memory access (null pointer or bad address)
Exit code: N/A (killed by signal)
Program: ./my_program

With debug mode (--debug):

Process terminated by signal: segmentation fault (11)
Description: Invalid memory access (null pointer or bad address)
Exit code: N/A (killed by signal)
Program: ./my_program

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Running under debugger for detailed backtrace...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Process 12345 stopped
* thread #1, queue = 'com.apple.main-thread', stop reason = EXC_BAD_ACCESS (code=1, address=0x0)
    frame #0: 0x0000000100000538 my_program`main + 80
...

Installation

Prerequisites

• Go 1.16 or later
• lldb (macOS) or gdb (Linux) for debug mode

Install with go install (recommended)

go install github.com/13rac1/segcatch@latest

Note: requires the Go Bin in your PATH:

export PATH=${PATH}:`go env GOPATH`/bin

Build from source

git clone https://github.com/13rac1/segcatch.git
cd segcatch
go build

Manual installation

# After building, copy the binary to PATH
sudo cp segcatch /usr/local/bin/

Usage

Basic usage (capture signals and exit codes)

segcatch ./your_program [args...]

With debugging (get detailed backtraces)

segcatch --debug ./your_program [args...]

JSON output (machine-readable format)

segcatch --json ./your_program [args...]

Output JSON with backtrace:

segcatch --debug --json ./your_program [args...]

Example JSON output:

{
  "exit_code": -1,
  "signal": "segmentation fault",
  "signal_number": 11,
  "description": "Invalid memory access (null pointer or bad address)",
  "program": "./my_program",
  "args": ["arg1", "arg2"],
  "backtrace": "frame #0: 0x100000538 my_program`main at main.cpp:42\n...",
  "success": false
}

Examples

Run a program that might crash:

segcatch ./segfault_example

Run with arguments:

segcatch ./my_app --config config.json input.txt

Get detailed crash information:

segcatch --debug ./my_app

Help

segcatch --help    # Basic usage information
segcatch --prompt  # AI agent usage guide (detailed)

The --prompt flag shows a concise guide specifically designed for AI coding agents, including output format details, interpretation tips, and example JSON structure.

How It Works

1. Process Monitoring: Spawns and monitors the target process
2. Signal Detection: Captures Unix signals (SIGSEGV, SIGABRT, SIGBUS, etc.)
3. Output Streaming: Passes through stdout/stderr in real-time
4. Crash Analysis: On crash, formats the signal information clearly
5. Optional Debugging: Re-runs the program under lldb/gdb to capture backtrace

Supported Signals

• SIGSEGV (segmentation fault): Invalid memory access
• SIGABRT (abort trap): Program aborted
• SIGILL (illegal instruction): Invalid CPU instruction
• SIGFPE (floating point exception): Arithmetic error
• SIGBUS (bus error): Memory alignment or hardware error
• And more...

Platform Support

• macOS: Full support with lldb
• Linux: Full support with gdb
• Windows: Process monitoring works, debugger integration not supported

Use with Claude Code

When working with C++ projects in Claude Code, wrap your test commands with segcatch:

# Instead of:
./my_tests

# Use:
segcatch --debug ./my_tests

# Or with JSON for programmatic parsing:
segcatch --debug --json ./my_tests

# View AI agent usage guide:
segcatch --prompt

This ensures Claude receives complete crash information and can provide accurate debugging assistance. The --json flag is particularly useful for automated workflows where the output needs to be parsed programmatically.

For AI agents: Run segcatch --prompt to see a concise usage guide with output format details and interpretation tips.