{"id":30779181,"url":"https://github.com/lostjared/mxdbg","last_synced_at":"2026-04-16T12:01:27.932Z","repository":{"id":299195817,"uuid":"1002293316","full_name":"lostjared/mxdbg","owner":"lostjared","description":"ELF x86_64 Debugger for Linux with AI (via ollama)","archived":false,"fork":false,"pushed_at":"2025-07-18T13:45:39.000Z","size":1427,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-05T06:09:28.702Z","etag":null,"topics":["ai","debugger","linux","x64"],"latest_commit_sha":null,"homepage":"https://lostsidedead.biz/mxdbg/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lostjared.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-15T06:26:07.000Z","updated_at":"2025-07-18T13:45:43.000Z","dependencies_parsed_at":"2025-06-30T14:39:21.514Z","dependency_job_id":"45c9ef89-dd95-405e-b9c2-8fde0c628bae","html_url":"https://github.com/lostjared/mxdbg","commit_stats":null,"previous_names":["lostjared/mxdbg"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lostjared/mxdbg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostjared%2Fmxdbg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostjared%2Fmxdbg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostjared%2Fmxdbg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostjared%2Fmxdbg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lostjared","download_url":"https://codeload.github.com/lostjared/mxdbg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostjared%2Fmxdbg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31884929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T11:36:10.202Z","status":"ssl_error","status_checked_at":"2026-04-16T11:36:09.652Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","debugger","linux","x64"],"created_at":"2025-09-05T06:06:57.453Z","updated_at":"2026-04-16T12:01:27.911Z","avatar_url":"https://github.com/lostjared.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mxdbg - ELF x86_64 Debugger with AI Integration\n\ncoded by Jared Bruni (jaredbruni@protonmail.com)\n\nA modern C++ debugger built with ptrace that integrates with Ollama for AI-powered code analysis and explanation.\n\n![image](https://github.com/user-attachments/assets/149d94fd-6cdd-48f5-9171-ad83a066f26d)\n![backtrace0x2](https://github.com/user-attachments/assets/6316ef35-e5d0-49b5-8465-148794326468)\n\n\n## Color Key\n- Cyan for AI\n- Red for machine code/disassembly\n- White for debugger text\n\n\n#  Not complete, some features still need to be implemented. This is a new project.\n\n## Features\n\n- **Process Control**: Launch or attach to processes with full debugging capabilities\n- **Register Manipulation**: Read and write 64-bit, 32-bit, 16-bit, and 8-bit registers\n- **Memory Operations**: Read and write process memory with byte-level precision\n- **Breakpoint Management**: Set, remove, and handle breakpoints\n- **Single Stepping**: Execute instructions one at a time with full control\n- **Disassembly**: View disassembled code using objdump integration\n- **AI Integration**: Get AI-powered explanations of disassembly and code behavior\n- **Interactive Shell**: Readline-based command interface with history\n\n## Dependencies\n\n### Required Dependencies\n\n- **CMake 3.20+**: Build system\n- **C++20 compatible compiler**: GCC 10+ or Clang 10+\n- **readline**: For interactive command line interface\n- **ollama_gen**: AI integration library for Ollama communication\n- **Standard Linux tools**: objdump, ptrace support\n\n### Installing ollama_gen\n\nThe project requires the `ollama_gen` library for AI integration. Install it by building from source. https://github.com/lostjared/ollama_gen\n\n\n## Environment Setup\n\n### Required Environment Variables\n\nTo use the AI integration features, you must export these environment variables to use with ollama\n\n```bash\nexport MXDBG_HOST=\"localhost\"     # Your Ollama server URL can included port\n                                  # example 192.168.1.50:1088 op just the ip 192.168.1.50 \nexport MXDBG_MODEL=\"llama2\"       # Your preferred Ollama model ex: codellama:7b\n```\n\n### Setting up Ollama\n\n1. Install Ollama on your system\n2. Start the Ollama service: `ollama serve`\n3. Pull a model: `ollama pull llama2` (or your preferred model)\n4. Set the environment variables as shown above\n\n## Building\n\n```bash\nmkdir build\ncd build\ncmake ..\nmake\n```\n\n### Installation\n\n```bash\nsudo make install\n```\n\n### Uninstall\n\n```bash\nsudo make uninstall\n```\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Launch a program for debugging\n./mxdbg /path/to/program\n\n# Attach to an existing process\n./mxdbg -p \u003cPID\u003e\n\n# Dump assembly of a binary\n./mxdbg -d /path/to/binary\n```\n\n### Command Line Options\n\n- `-p \u003cPID\u003e`: Attach to process with given PID\n- `-P \u003cPID\u003e`: Same as `-p` (long form)\n- `-R \u003cpath\u003e`: Launch executable at path\n- `-r \u003cpath\u003e`: Same as `-R` (short form)\n- `-A \u003cargs\u003e`: Additional arguments for the launched process\n- `-a \u003cargs\u003e`: Same as `-A` (short form)\n- `-d`: Dump assembly of executable\n- `-D`: Same as `-d` (long form)\n\n### Interactive Commands\n\nOnce in the debugger shell (`mx $\u003e`), you can use:\n\n## Available Commands\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| **Expression \u0026 Variables** | | |\n| `expr \u003ce\u003e` | | Evaluate expression |\n| `setval \u003cname\u003e \u003cvalue\u003e` | | Set variable to value |\n| `listval` | | List variables |\n| **Process Control** | | |\n| `run` | `r` | Run program (sets main breakpoint) |\n| `continue` | `c` | Continue process execution |\n| `step` | `s` | Execute single instruction |\n| `step N` | `s N` | Execute N instructions |\n| `next` | | Step over function calls |\n| `finish` | `step_out` | Step out of current function |\n| `until \u003caddr\u003e` | `run_until \u003caddr\u003e` | Run until specific address |\n| `status` | `st` | Show process status |\n| `start` | `restart` | Restart the program |\n| **Threading** | | |\n| `thread` | | Show current thread |\n| `thread \u003cid\u003e` | | Switch to thread context |\n| `threads` | | List all running threads |\n| `debug_thread \u003cid\u003e` | | Debug specific thread |\n| **Code Analysis** | | |\n| `cur` | `current` | Print current instruction |\n| `list` | | Display full disassembly |\n| `list_less` | | Display disassembly with pager |\n| `list_function \u003cname\u003e` | | Show specific function disassembly |\n| `base` | | Show base address and current PC |\n| `backtrace` | `bt`, `where` | Show call stack backtrace |\n| **Registers** | | |\n| `registers` | `regs` | Show all registers |\n| `register \u003cname\u003e` | `reg \u003cname\u003e` | Show specific register value |\n| `register32 \u003cname\u003e` | | Show 32-bit register |\n| `register16 \u003cname\u003e` | | Show 16-bit register |\n| `register8 \u003cname\u003e` | | Show 8-bit register |\n| `set \u003creg\u003e \u003cvalue\u003e` | | Set register to value |\n| **FPU/Float Registers** | | |\n| `get_fpu \u003cname\u003e` | | Get FPU register value |\n| `set_fpu \u003cname\u003e \u003cvalue\u003e` | | Set FPU register to value |\n| `list_fpu` | | List all FPU registers |\n| **Breakpoints \u0026 Watchpoints** | | |\n| `break \u003caddr\u003e` | `b \u003caddr\u003e` | Set breakpoint at address |\n| `break_if \u003caddr\u003e \u003ccondition\u003e` | | Set conditional breakpoint that only triggers when condition is true |\n| `function \u003cname\u003e` | | Set breakpoint at function |\n| `list_break` | `lb` | List all breakpoints |\n| `remove \u003caddr/index\u003e` | `rmv` | Remove breakpoint |\n| `watch \u003caddr\u003e \u003csize\u003e [type]` | | Set watchpoint (type: read/write/access) |\n| `watchpoints` | `wp` | List watchpoints |\n| **Memory Operations** | | |\n| `read \u003caddr\u003e` | | Read 8 bytes from memory address |\n| `read_bytes \u003caddr\u003e \u003csize\u003e` | | Read specific number of bytes |\n| `write \u003caddr\u003e \u003cvalue\u003e` | | Write value to memory address |\n| `write_bytes \u003caddr\u003e \u003cbytes\u003e` | | Write byte sequence to memory |\n| `hexdump \u003caddr\u003e \u003csize\u003e` | | Display memory as hexadecimal dump |\n| `as_bytes \u003cvalue\u003e` | | Convert value to byte representation |\n| `maps` | `memory_maps` | Show memory map |\n| `local \u003creg\u003e \u003coffset\u003e \u003csize\u003e` | | Read local variable on stack |\n| **Memory Search** | | |\n| `search int \u003cvalue\u003e` | | Search for 32-bit integer in memory |\n| `search int64 \u003cvalue\u003e` | | Search for 64-bit integer in memory |\n| `search string \u003ctext\u003e` | | Search for string in memory |\n| `search bytes \u003chex bytes\u003e` | | Search for byte pattern |\n| `search pattern \u003cpattern\u003e` | | Search with wildcards (e.g., 41??43) |\n| **Stack Analysis** | | |\n| `stack_frame` | | Analyze current stack frame |\n| **AI Features** | | |\n| `explain \u003cfunction\u003e` | | Explain function disassembly with AI |\n| `ask \u003cquestion\u003e` | | Ask the AI a question about the program |\n| `mode \u003clevel\u003e` | `user \u003clevel\u003e` | Set AI difficulty (beginner/programmer/expert) |\n| **File Information** | | |\n| `info files` | | Show open file descriptors |\n| **Utility** | | |\n| `find \u003ctext\u003e` | | Find text in disassembly using grep |\n| `shell \u003ccommand\u003e` | `sh \u003ccommand\u003e` | Execute shell command |\n| `clear` | | Clear the screen |\n| `debug_state` | | Show detailed debug state |\n| `help` | `h` | Show this help message |\n| `quit` | `q`, `exit` | Exit debugger |\n\n## AI Integration\n\nWhen `MXDBG_HOST` and `MXDBG_MODEL` are set, the debugger will:\n\n- Provide AI explanations when stepping through code\n- Analyze disassembly output with the `explain` command\n- Offer context-aware debugging assistance with the ask command\n\nExample AI integration:\n```bash\nmx $\u003e explain function\n# AI will analyze the program's disassembly and explain its behavior\n```\n\n## Project Structure\n\n```\nmxdbg/\n├── libmxdbg/           # Core debugger library\n│   ├── include/mxdbg/  # Public headers\n│   ├── process.cpp     # Process control and ptrace operations\n│   ├── debugger.cpp    # Main debugger logic\n│   └── pipe.cpp        # IPC utilities\n├── mxdbg/              # Main executable\n│   └── main.cpp        # Entry point and argument parsing\n└── tests/              # Test suite\n    ├── process_*.cpp   # Process control tests\n    ├── pipe_*.cpp      # IPC tests\n    └── register_*.cpp  # Register manipulation tests\n```\n\n## Supported Architectures\n\n- x86_64 Linux systems\n- Requires ptrace support in kernel\n\n## Register Support\n\n### 64-bit Registers\n`rax`, `rbx`, `rcx`, `rdx`, `rsi`, `rdi`, `rbp`, `rsp`, `rip`, `r8`-`r15`\n\n### 32-bit Registers  \n`eax`, `ebx`, `ecx`, `edx`, `esi`, `edi`, `ebp`, `esp`, `r8d`-`r15d`\n\n### 16-bit Registers\n`ax`, `bx`, `cx`, `dx`, `si`, `di`, `bp`, `sp`, `r8w`-`r15w`\n\n### 8-bit Registers\n`al`, `ah`, `bl`, `bh`, `cl`, `ch`, `dl`, `dh`, `sil`, `dil`, `bpl`, `spl`, `r8b`-`r15b`\n\n## Testing\n\nRun the test suite:\n```bash\ncd build/tests\nctest\n```\n\nIndividual tests can be run:\n```bash\n./tests/process_continue_test\n./tests/pipe_test\n./tests/register_test\n```\n\n**Build errors**: Ensure all dependencies are installed, especially ollama_gen and readline development packages.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flostjared%2Fmxdbg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flostjared%2Fmxdbg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flostjared%2Fmxdbg/lists"}