{"id":30420656,"url":"https://github.com/macabeus/kappa","last_synced_at":"2025-10-29T11:34:02.889Z","repository":{"id":295314620,"uuid":"988683147","full_name":"macabeus/kappa","owner":"macabeus","description":"🐸 Your decompiler buddy who lives on VS Code","archived":false,"fork":false,"pushed_at":"2025-08-14T21:57:03.000Z","size":13515,"stargazers_count":18,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-14T23:27:12.074Z","etag":null,"topics":["decompilation","vscode-extension"],"latest_commit_sha":null,"homepage":"https://marketplace.visualstudio.com/items?itemName=macabeus.kappa","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/macabeus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","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-05-22T23:20:10.000Z","updated_at":"2025-08-14T21:57:06.000Z","dependencies_parsed_at":"2025-06-14T20:28:58.417Z","dependency_job_id":"d2579bf0-b345-45bb-8c94-5db9ef168b3d","html_url":"https://github.com/macabeus/kappa","commit_stats":null,"previous_names":["macabeus/kappa"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/macabeus/kappa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macabeus%2Fkappa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macabeus%2Fkappa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macabeus%2Fkappa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macabeus%2Fkappa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/macabeus","download_url":"https://codeload.github.com/macabeus/kappa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macabeus%2Fkappa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271606604,"owners_count":24788981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["decompilation","vscode-extension"],"created_at":"2025-08-22T08:19:47.402Z","updated_at":"2025-10-29T11:34:02.883Z","avatar_url":"https://github.com/macabeus.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kappa\n\n\u003cimg src=\"./media/branding/logo.png\" align=\"right\" height=\"130px\" /\u003e\n\n[![GitHub Stars](https://flat.badgen.net/github/stars/macabeus/kappa?icon=github)](https://github.com/macabeus/kappa)\n[![Visual Studio Marketplace Downloads](https://flat.badgen.net/vs-marketplace/d/macabeus.kappa?icon=visualstudio)](https://marketplace.visualstudio.com/items?itemName=macabeus.kappa)\n\nYour decompiler buddy who lives on VS Code.\n\n- **✨ AI Prompt Builder:** Craft high-quality prompts to guide AI in decompiling a function.\n- **🤖 Agent Mode:** Automatically decompile a given function, until it reache 100% match.\n- **🐍 Integration with popular decompilation toolings:** Create a scratch on [decomp.me](https://decomp.me/) in one click, call [m2c](https://github.com/matt-kempster/m2c), [decomp-permuter](https://github.com/simonlindholm/decomp-permuter) and [objdiff](https://github.com/encounter/objdiff) from VS Code easily.\n- **🔌 Automated Code Fixes:** Use plugins to automatically update the code’s AST, eliminating repetitive tasks and correcting common errors.\n\n\u003e [📚 Learn how this project was developed on Substack](https://gambiconf.substack.com/p/development-journey-on-game-decompilation)\n\n## ⚙️ Extension setup\n\n\u003cimg alt=\"Walkthrough\" src=\"./media/readme/walkthrough.png\" /\u003e\n\nMake sure to follow the Kappa Setup walkthrough to get the extension working on your project.\n\n\u003e :warning: This extensions runs only on single-root workspaces. Open a folder or workspace first to use it.\n\n## ✨ AI Prompt Builder\n\n\u003cimg alt=\"Build prompt\" src=\"./media/readme/build-prompt.gif\" /\u003e\n\nClick on \"Build prompt\" 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.\n\nThe prompt includes:\n\n- Real examples from your codebase: Functions that have already been decompiled (found via Git history)\n- Function signatures of dependencies used in the target assembly\n- Clear instructions and formatting rules for the AI\n\n## 🤖 Agent Mode\n\nhttps://github.com/user-attachments/assets/f8f5c135-fd9b-494f-92fd-a69044318567\n\nClick on \"Start agent\" to have VS Code Copilot automatically decompile the assembly function.\n\n\u003e **Note:** Make sure to have the \"Agent\" mode selected on GitHub Copilot before clicking on the code lens.\n\n## 🎨 Commands\n\n### Compare a symbol from two object files\n\nKappa bundles [`objdiff`](https://github.com/encounter/objdiff) into the extension. You can call it directly from the command palette by running `Compare a symbol from two object files`.\n\n### Scatter Chart\n\n\u003cimg alt=\"Scatter Chart\" src=\"./media/readme/scatter-chart.png\" /\u003e\n\nYou can plot a scatter chart to visualize clusters of functions with similar assembly code by running `Show chart`.\n\n## 🔖 Language Model Tools\n\n### `objdiff`\n\nYou can call [`objdiff`](https://github.com/encounter/objdiff) from the Copilot Chat to explain the diffs from a given function.\n\n#### Example\n\n- Calling `#objdiff` on the ask mode to explain the differences.\n\n```markdown\n#objdiff explain the differences on this function.\nThe current object file is at `sa3/build/bu_bu.o`.\nThe target object file is at `sa3/expected/bu_bu.o`\n```\n\n- Calling `#objdiff` on the agent mode to fix the differences for a function.\n\n```markdown\nCall #objdiff comparing the function `sub_805ECC4` with the expected assembly function, and fixes the gaps.\n\nThe current object file path is at `sa3/build/bu_bu.o` and the target object file path is at `sa3/expected/bu_bu.o`.\n\nMake your changes and compile calling `make` to check if it's working.\n\nStop only when there are no more differences.\n```\n\n## 🐍 Integrations\n\n### m2c\n\nDecompile assembly functions using [m2c](https://github.com/matt-kempster/m2c) by clicking \"Decompile with m2c\" code lens above assembly functions.\n\n### decomp-permuter\n\n\u003cimg alt=\"Permute a function\" src=\"./media/readme/decomp-permuter.png\" /\u003e\n\nGenerate code variations using [decomp-permuter](https://github.com/simonlindholm/decomp-permuter) by clicking \"Permute it\" above C functions. Compare different permutations in the side panel to find better variants. Score zero means that this variant compiles to an assembly that matches with the target one.\n\n### decomp.me\n\n\u003cimg alt=\"Create Scratch\" src=\"./media/readme/create-scratch.gif\" /\u003e\n\nCreate a new scratch on [decomp.me](https://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.\n\n## 🔌 Kappa Plugins\n\n\u003cimg alt=\"Kappa Plugins\" src=\"./media/readme/kappa-plugins.gif\" /\u003e\n\n**Kappa plugins** are scripts that transform the Abstract Syntax Tree (AST) of C/C++ code blocks. They can be used to:\n\n- Fix common decompilation errors\n- Avoid repetitive tasks\n\n### Example Kappa Plugin Case\n\nFor instance: When decompiling [Sonic Advance 3](https://github.com/SAT-R/sa3) using AI, it kept messing up by using raw numbers instead of the proper Q notation. So, we can [`ApplyQNotationPlugin`](./example-kappa-plugins/ApplyQNotationPlugin.js) that catches assignments to `Vec32` using a raw number and replaces it with the Q format.\n\n```cpp\n// Before: Raw decompiled code\nplayer.x = 256;\n\n// After: ApplyQNotationPlugin transformation\nplayer.x = Q(1);\n```\n\nCheck more examples on [`./example-kappa-plugins`](./example-kappa-plugins).\n\n### How to use the plugins\n\n1. Add the plugins in a folder called `.kappa-plugins` from the workspace root.\n2. Select a function\n3. Run the action `Run Kappa Plugins`\n\n## Contributing\n\n- [Creating new plugins to use with the VS Code extension](./docs/create-your-own-kappa-plugin.md)\n- [Developing the VS Code extension itself](./docs/developing-kappa-vscode-extension.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacabeus%2Fkappa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacabeus%2Fkappa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacabeus%2Fkappa/lists"}