Kappa
VS Code extension designed to help you when decompiling a codebase.
- ✨ AI Prompt Builder: Craft high-quality prompts to guide AI in decompiling a function.
- 🤖 Agent Mode: Automatically decompile a given function, until it reache 100% match.
- 🐸 Integration with decomp.me: Create a new scratch in one click.
- 🔌 Automated Code Fixes: Use plugins to automatically update the code’s AST, eliminating repetitive tasks and correcting common errors.
📚 Learn how this project was developed on Substack
⚙️ Extension setup
Make sure to follow the Kappa Setup walkthrough to get the extension working on your project.
✨ AI Prompt Builder
Click on "Build prompt to decompile it" to create a context-aware prompt for decompiling an assembly function. It automatically analyzes your codebase to provide the AI with accurate context for the task.
The prompt includes:
- Real examples from your codebase: Functions that have already been decompiled (found via Git history)
- Function signatures of dependencies used in the target assembly
- Clear instructions and formatting rules for the AI
🤖 Agent Mode
https://github.com/user-attachments/assets/f8f5c135-fd9b-494f-92fd-a69044318567
Click on "Start agent to decompile it" to have VS Code Copilot automatically decompile the assembly function.
Note: Make sure to have the "Agent" mode selected on GitHub Copilot before clicking on the code lens.
🎨 Commands
Compare a symbol from two object files
Kappa bundles objdiff into the extension. You can call it directly from the command palette by running Compare a symbol from two object files.
Scatter Chart
You can plot a scatter chart to visualize clusters of functions with similar assembly code by running Show chart.
objdiff
You can call objdiff from the Copilot Chat to explain the diffs from a given function.
#objdiff explain the differences on this function.
The current object file is at `sa3/build/bu_bu.o`.
The target object file is at `sa3/expected/bu_bu.o`
🐸 Integration with decomp.me
Create a new scratch on decomp.me instantly by clicking the code lens that appears above assembly functions. It automatically includes the type definitions from your code base which are used by the function and aren't on the context.
🔌 Kappa Plugins
Kappa plugins are scripts that transform the Abstract Syntax Tree (AST) of C/C++ code blocks. They can be used to:
- Fix common decompilation errors
- Avoid repetitive tasks
Example Kappa Plugin Case
For instance: When decompiling Sonic Advance 3 using AI, it kept messing up by using raw numbers instead of the proper Q notation. So, we can ApplyQNotationPlugin that catches assignments to Vec32 using a raw number and replaces it with the Q format.
// Before: Raw decompiled code
player.x = 256;
// After: ApplyQNotationPlugin transformation
player.x = Q(1);
Check more examples on ./example-kappa-plugins.
How to use the plugins
- Add the plugins in a folder called
.kappa-plugins from the workspace root.
- Select a function
- Run the action
Run Kappa Plugins
Contributing
