Thanks for helping. Bug reports, fixes, new platforms and better guides for agents are all welcome.
Never put any part of a game in an issue, a pull request, a test or a screenshot: no ROMs, disc images or executables, and no code, assembly or assets taken from them. That includes the C your agents matched. It comes from the game, and it belongs to you and the game's owner, not to this repository. Sam's request from decomp.wtf still stands: only use decompdecomp on games you own, and respect the rules of the decomp projects you work with.
Before you attach a log (~/Decomp-RetroReversing/.decomp/logs/decomp.log), read it, and cut out any code or assembly.
Open an issue with the bug report form. It asks for your version, your system, the console and compiler, what you did, what you expected and what happened, and the part of the log around it, if it helps (see above). Your answers label the issue (its console and system).
The name of the game is fine to mention. Many bugs only show up on one game, and the name helps a lot.
decompdecomp is Python 3.12+, managed with uv.
git clone https://github.com/n-delic/decompdecomp && cd decompdecomp
uv sync
uv run decomp # the development copy, in its own window (projects in ~/Decomp-RetroReversing-dev, or $DECOMP_HOME)
uv run pytest -q # the tests (parallel by default)
uv run pytest tests/test_ps2.py -q # one file
uv run pytest -q -n 0 # one process, when debugging a worker or its output
uv run ruff check src tests projects # the linterThere are about 10,000 tests, so pytest runs them across all cores (pytest-xdist, configured in
pyproject.toml). Modules that build a demo ROM share projects/<demo>/build/, so tests/conftest.py keeps them
on one worker; everything else spreads across the rest. -n 0 turns parallelism off. pytest --durations=25
shows what is still slow. Tests that need a real compiler or decompiler skip when it isn't installed.
A checkout is a separate app, "decompdecomp dev": its own folder (~/Decomp-RetroReversing-dev), port and window. It never
replaces the decompdecomp you have installed, and never touches its projects in ~/Decomp-RetroReversing. For an experiment, give
it a scratch folder: DECOMP_HOME=/some/scratch/folder DECOMP_TRAY=0 uv run decomp. The tests already use a folder
of their own.
Compilers and tools (objdiff, dtk, wibo, Ghidra, m2c, decomp-permuter and the period compilers) are pinned with
checksums in src/decompnet/toolchains.toml, and the app installs them in Setup. splat is a Python dependency
(pyproject.toml). Many tests skip when a compiler isn't installed, and that's fine. The homemade demo games in
projects/demo-* are built by their own scripts. The N64 demo (projects/demo-rom) also needs ld.lld and
llvm-objcopy on your PATH (Debian and Ubuntu: apt install lld llvm).
docs/CONVENTIONS.md has the house rules, and AGENTS.md how the code is laid out. Read them first. In short:
- Match the code around you: plain-English docstrings and comments that say why.
- Every change in behaviour comes with a test in
tests/. A test that needs a real game or a proprietary compiler skips when it isn't there; use or extend a demo game instead. - Don't add a dependency for a few lines. capstone, pyelftools and httpx are already there.
- Errors shown to users or agents are sentences they can act on.
uv run ruff check src tests projectspasses. There's no formatter: don't reformat code you didn't change.
Some things we won't merge:
- Anything that weakens the judge. A match means the bytes are identical after linking (ROM mode), or objdiff says 100% (fork mode).
- Downloading a proprietary compiler without the user agreeing to it in Setup, or taking tools from PATH instead of the pinned ones.
- Letting agents edit a project's build setup. They're limited to source and header files on purpose.
- Links to the decomp.wtf website. That domain isn't ours. Keep the internal names (
decomp,decompnet,.decomp.wtf.json): existing installs depend on them.
Not sure what to work on? ROADMAP.md lists what's planned and why, and has a table of which feature works on which platform: every — in it is a gap to fill.
decompdecomp is one pipeline for every console: whatever helps agents on one console should work on all of them, in ROM mode (N64, PS1, PS2, PS3, PSP, GBA) and project mode (GameCube, Wii, PC, Xbox, DS, public decomps) alike. When you add a feature:
- Build the shared part where every console uses it:
app/andnetwork.pyfor the engine,rom/andforks/for each mode,arch/for what depends on the processor. - Put only what really differs in
consoles/<id>/, through a part of the connector (consoles/__init__.py) with a default that says plainly when a console can't do it yet. - A console or mode that can't have it yet: say why in the code, add an item to ROADMAP.md, and mark its column with "—" in the table. Don't leave it unsaid.
Each console has a folder: src/decompnet/consoles/<id>/. Everything decompdecomp knows about that console is in
it. The rest of the app never asks "is this a PS2 game?". It asks the project's console, consoles.get(platform),
through one file: the connector, consoles/__init__.py.
| Folder | Console | Mode | Its files |
|---|---|---|---|
consoles/n64/ |
Nintendo 64 | ROM | rom.py the ROM file and its header · code.py code the game loads later, compressed code · guides/ |
consoles/ps1/ |
PlayStation | ROM | exe.py the game's program (PS-X EXE) and the disc's BOOT line; its discs and overlays through the PS2's readers · guides/ |
consoles/ps2/ |
PlayStation 2 | ROM | elf.py the game's program · disc.py, chd.py disc images · overlays.py code in the disc's other files · syscalls.py kernel calls · symtab.py, mdebug.py, stabs.py, cheader.py, debuginfo.py the game's own debug symbols · guides/ |
consoles/ps3/ |
PlayStation 3 | ROM | elf.py the decrypted program, its descriptor and .opd · split.py the program's function list, calls and prologues · imports.py, nids.py imports and kernel calls named · symbols.py its own symbols · guides/ (the processor: arch/ppc64.py) |
consoles/gba/ |
Game Boy Advance | ROM | header.py the cartridge header · split.py luvdis and the candidate finder, its editing and joining · candidates.py, luvdis_run.py · export.py, export_build.py · guides/ |
consoles/gc_wii/ |
GameCube, Wii | PROJECT | scratch.py a dtk-template project for the game · guides/ |
consoles/ps4/ |
PlayStation 4 | PROJECT | scratch.py reads decrypted Orbis ELF segments and function maps; project_template/ builds strict objdiff targets with public clang; guides/ |
consoles/pc/ |
Windows PC | PROJECT | scratch.py Ghidra finds the functions, decompdecomp cuts them out of the .exe · project_template/ · guides/ |
consoles/xbox/ |
Xbox | PROJECT | scratch.py the XBE (or disc) made a Windows program, then the PC path · kernel import names · guides/ |
consoles/nds/ |
Nintendo DS | PROJECT | scratch.py a ds-decomp project for the ROM, a CodeWarrior version per source file · project_template/ · guides/ |
Each folder's __init__.py makes its console: the facts and the parts the app calls. Start there. Its docstring
lists its files.
Around them:
| Where | What |
|---|---|
consoles/__init__.py |
The connector: the Console class (every fact and part, one line each) and the list of consoles. |
consoles/public.py |
Consoles only public decomps cover: a name, a processor, m2c's target, guides. |
consoles/template/ |
The package to copy for a new console. |
arch/ |
What depends only on the processor: mips.py, ppc.py, x86.py, arm.py (relocations, disassembly, hand-written assembly, which readers exist). |
rom/ |
ROM mode, shared: split.py (splat), match.py (the MIPS judge: link and compare), link.py (what every judge shares), export.py. |
forks/, app/forkengine.py |
PROJECT mode and public decomps, shared: the project's build, objdiff. |
A console works in one of two modes:
- ROM: decompdecomp splits the game with splat and judges each function by linking it at its real address and comparing the bytes. The console reads its file and says its compilers. The judge reads MIPS today.
- PROJECT: decompdecomp makes the community's kind of project for the game (a git tree with
objdiff.json), and objdiff judges each function in the project's own build. The console makes the project.
- Open
consoles/<id>/__init__.py. Its docstring says which file does what. - Change the part you need in that folder. A fact about the processor, not the console (how MIPS code is read),
goes in
arch/<processor>.py. Something every console of a mode needs goes inrom/orforks/. - Run its tests:
uv run pytest tests/test_consoles.py -q -k <id>, and its own file (tests/test_ps2.py, ...). - When a feature reaches the console, tick its column in ROADMAP.md's table. A feature you build for one console should reach the others too (see "Every console gets every feature" above).
-
Copy the template.
cp -r src/decompnet/consoles/template src/decompnet/consoles/<id>. Rename the class and the object at the end of its__init__.py. -
Pick its mode. ROM if a splitter reads its programs (splat for MIPS; luvdis for GBA). PROJECT if the community has a project layout and a delinker for it, judged by objdiff (see
consoles/gc_wii/andconsoles/pc/). -
Fill in its facts. Each is one line in the
Consoleclass:Fact What it is id,aliasesWhat project configs store. Keep it once projects exist; old ids go in aliases.name,shortWhat the app shows, and where space is short. statusBETAuntil its conformance test passes and a real game rebuilt byte for byte; thenRECOMMENDED.arch,big_endianIts processor, an id in arch/.mode,layoutROM or PROJECT, and what a project of it is ("splat", "dtk-template"). compilersIts compilers ( Compiler(id, name, built, guess)). The first is the default.packsMore toolchains Setup offers for it, with what each is for (a proprietary compiler pack). guides,compiler_guideGuides agents read first; the one every helper gets up front. compiler_familyIts compilers' family ("mwcc") when a project names no toolchain: the permuter's weights. m2cm2c's target for drafts ("mipsee-gcc"), or "" when m2c can't read its code. ramWhere its programs live: words in this range are read as pointers. demo,demo_toolsIts demo game's folder in projects/, and the tools building it needs.own_featuresEXPORT(a tree that rebuilds the game),REBUILD_CHECK(the project's rebuild check).as_flags,image_ext,asm_preambleROM mode's export: assembler flags, the image's extension. -
Fill in the parts it needs. The rest keep their default, which does nothing or says it can't:
Part What it does sniff(head, file)Says whether a file is this console's game, from its first bytes. Be strict. import_game(...)Starts a project from the user's copy. The mode's way by default. read_game(file, name)ROM: the program to split, with its header's facts (title, sha1, compiler guess). default_compiler(info, splat_guess)Which compiler built the game. default_flags(compiler, gp)A compiler's flags for a game of this console. add_code(config, ...)ROM: code splat misses (segments loaded later, overlays), added before it splits. split_game(workdir, picked, symbols, log)ROM: split the program into functions and data (splat by default; GBA uses luvdis). target_from_row,target_from_split,target_object,link_functionROM: a function's target, its object for diffs, and the link-and-compare judge. function_asm,parse_function,function_insns,function_meta,function_status,target_archROM: how a function's assembly, instruction count, row metadata, status and Thumb/ARM mode are kept. instruction_size,function_from_row,split_function,function_at,join_saved_functionsROM: cutting, adding and joining functions at the console's instruction size (GBA: 2-byte Thumb). export_project(net, slug, out, log)ROM: write and check a tree that rebuilds the game. find_gp(image, program, segments)ROM: $gpas the game sets it.debug_info(program, known),debug_brief(known)The game's own symbols and types, and their lines in a brief. release_key(rom)What every release (region) of one game shares, from its header (N64, GBA: the game code without its region letter): other releases are found by it. None: by identical code. after_import(net, slug, chosen),on_start(net, slug)Work a new project gets once; work each project gets at start. create_project(root, game, compiler),game_info(game)PROJECT: makes the project; says which game a file is. tool_args()PROJECT: points the project's configure step at the pinned tools. identity(path),check_rebuild(fp, version),read_data(fp, name, length),upload_name(data)PROJECT: rooms' game check, the rebuild check, data the objects lack, an upload's file name. file_compiler(fp, source),set_file_compiler(fp, source, compiler)PROJECT: a compiler per source file, when the project's build allows it: then try_compilerswitches it (DS, Windows PC).compiler_configPROJECT: the files (globs in the project) file_compilerandfile_rangesread: the project's page reads them again only when one changed. None named: every second.asm_reason(code)Why a function can't come from a compiler. The processor's check, with this console's facts. up_front_guide(compiler),m2c_target(compiler)The guide for a compiler's code; m2c's target for it. What every console's agents get. ROM mode has these in
rom/and the engine already. A PROJECT console implements them itself, because only it knows where its project keeps names and file boundaries. A part the console can't do yet keeps its default ("can't yet"), and it gets a ROADMAP.md item and a "—" in the table:Part What needs it rename_symbol(fp, version, old, new)Polishing and rename_symbol: real names in the project's symbol list (dtk's and ds-decomp'ssymbols.txt). Without it, polished code keeps addresses for names.split_source(fp, version, source, at, new),splits_sourcessplit_file: a source file divided where a new one starts (a library's code, a second compiler).join_functions(fp, first, last, keep)join_functions: a function the analysis cut in pieces made whole, once agents agree.file_compiler,set_file_compilertry_compiler, when its build lets each source file have its own compiler.generated_functions(fp, version)Code its analysis knows no C of its own makes (Visual C++'s exception-handling stubs, consoles/pc/scratch.py) set aside when the project is measured, with why.its processor's pieceandjumps(arch/arm.py; x86:piece,arch/x86.py)Pieces found and joined without agents, in on_start(seeconsoles/nds/recover.py,consoles/pc/scratch.py), when a tool finds its functions (ds-decomp, Ghidra) and can cut them. -
Its compilers. One pinned entry each in
toolchains.toml(see "Adding a compiler" below). -
Its processor, if
arch/hasn't got it: addarch/<name>.py(relocation masks, capstone's mode, andasm_reasonif you can tell hand-written code) and itsArchinarch/__init__.py. -
Its guides for agents:
consoles/<id>/guides/<topic>.md. The first line is the guide's title. -
A demo game:
projects/demo-<id>/build.pybuilds the Demo Quest game (projects/demo-n64/original) with the console's compiler, and writesbuild/demo.json:{"game": <file>, "symbols": {name: address}}. Use only code we may share. Never any part of a real game. -
Register it in the list at the end of
consoles/__init__.py(_registry). -
Pass the conformance test:
uv run pytest tests/test_consoles.py -q -k <id>. It builds the demo, checkssniff, imports it, judges matching C (score 0) and wrong C, makes a draft, and rebuilds the game where the console can. It skips, saying what's missing, when a tool isn't installed. -
Say it: add a column to ROADMAP.md's table, and the console to README.md's and docs/GUIDE.md's lists.
-
The drop zone takes a quick look at a file before it uploads it (
app/static/js/home.js,identifyHead). Add your console's file there too, or the page refuses its files.
Example: PC has Visual C++ 6.0 to 2010, and you want Visual C++ 2012 (11.0).
- Pin it in
src/decompnet/toolchains.toml. A new part of a pack (msvc2005, or a pack of its own, as 2012-2013 would be) with itsurl, itssha256(sha256sumof the archive) andinto = "11.0". An archive that's a whole install takes only its compiler and headers withkeep(seemsvc2005). A compiler of 2015 and newer compiles against a Windows SDK: that's a toolchain of its own (winsdk-<version>) the pack names inheaders, so packs that use one SDK share it (seemsvc2015); each version's folder then gets anincludes.txtthe build reads. Take it from where the decomp community keeps it (decomp.me's compilers, decomp.dev's archive, the repositories they use). Where the community keeps none (Visual C++ 2015 and newer: decomp.me's newest x86 Visual C++ is 2005 SP1), take a public archive of the vendor's own files, pinned by commit and sha256, and say whose it is in the entry'ssource(2017's is ojdkbuild's, made for building OpenJDK); never from the vendor's site with someone's account. Changing an entry later is safe: an install from the old entry counts as not installed (toolchains.changed), and the app offers to install it again. - Proprietary means opt-in. Its entry says
license = "proprietary". The app installs it only after the user accepts its licence in Setup. Never download it in code, a test or CI: public CI can't have it, and its tests skip there. - How it runs on Linux. Windows compilers run through wibo (a pinned tool); check that the new
cl.exeruns there. One wibo can't run goes in a pack markedwine = true, run through the user's wine (wine.py): the pack decides, not the version number, so a 2012-2013 pack can be either (the app tells the build which packs in$DECOMPNET_WINE_PACKS; a project'sconfigure.pyrun by hand sends 2015 and newer to wine). wibo stops at the first Windows function it doesn't have and names it (2010's compiler neededmsvcp100.dllbeside it; 2005's and later linkers stop atlstrcmpiWin wibo 1.2.0). A Linux compiler needs nothing; a 32-bit one may needrequires = ["runtime-i386"]. - The console lists it:
consoles/pc/__init__.py,MSVC_VERSIONS. A ROM console's compilers are itscompilerstuple:Compiler(id, name, built, guess)(seeconsoles/ps2/__init__.py). - Which game used it. PC reads the program's Rich header:
RICH_COMPILERSinconsoles/pc/scratch.pyalready knows every Visual C++ version's product ids, andRELEASESthe builds of its updates.RICH_BUILDSgives each compiler of the packs by the build itscl.exesays: once 11.0's is there, a game built with that build builds with it (another build of 11.0 with the closest), andBuild.cannot_matchstops saying it can't match. A PS2 program's.commentnote says its GCC:_GCCinconsoles/ps2/elf.py, and the compiler'sguessnames it. - Its flags. The defaults are the toolchain's
flags, and the console'sdefault_flagsadjusts them (the PS2's small data). PC projects write theirs inproject_template/tools/configure.py(CL_FLAGS; from 8.0 on,/GXis/EHsc). - MIPS only:
search_flagstries flags by compiler family (FLAG_FAMILIESinapp/engine/compilers.py), and the compiler map tells compilers apart by their habits (compilermap.py,quirks). Add the new family there. - Prove it builds matching code: build the demo with it (
projects/demo-ps2/build.py <toolchain>does this for the PS2's compilers,projects/demo-pc/build.py <version>for Visual C++) and add it to that console's test (OTHER_COMPILERSintests/test_ps2.py,NEWERintests/test_pc.py), skipped when it isn't installed:pytest.mark.skipif(toolchains.installed(...) is None, reason="needs ..."). - Say it: the compiler in ROADMAP.md, README.md and docs/GUIDE.md where they list the console's compilers.
A compiler that only ever came in a proprietary SDK (an early Xbox XDK's Visual C++ 7.0 build), or an SDK whose
libraries a console needs, can't be pinned and downloaded: nobody may publish it. It's a kit, in src/decompnet/kits/
(the connector, like consoles/ and agents/): the user points Setup at their own copy, decompdecomp checks and
records the folder, and reads it there. Nothing of it is copied, downloaded or put in CI.
- Copy
kits/xdk.pytokits/<id>.pyand fill in its facts:id(its Setup entry),name,platform,description,files(what proves the folder: paths in it, any case),places(folders inside the one the user picks where it may be). - Its parts, each optional:
locate(folder)(the copy a folder is or holds, when its layouts are more thanfilesinsideplaces:kits/visualcpp.pyknows VC98, VC andVC/Tools/MSVC/<version>),build(folder)(which build the copy is, read from its files: the XDK's from its libraries, Visual C++'s from c2.dll's version resource,kits.file_version),compilers(folder)(OwnCompiler: a version name, the compiler, its headers, what runs it: wibo, wine or nothing, and its exactbuild) andknown_files+known(the SHA-256 of a file each build has, so Setup says "verified": a kit isn't pinned, this is how users know their copy is the one the games were built with). Hashes are facts and may be shipped; the files never. Several copies. Setup records any number of copies of a kit (a manifest'sfolders;Removeforgets one, the files stay), each checked when added, so a user with two XDKs or a Visual C++ 6.0 and a 2008 has both. Nothing in a part may assume one copy:compilers(folder)reads that copy only, and itsversionname must be unique per copy (xdk-3911,own-9.0.30729: configure.py--owntakes any name, and a project storesMSVC/<name>).kits.folders(id)lists the copies,kits.compilers(ids)the compilers of all of them. - Register it in
_registryat the end ofkits/__init__.py. It shows in Setup as a toolchain of kind "local" (toolchains.registryadds it); it needs no entry intoolchains.toml. - The console takes it: its
kitsnames it, and the console asks the connector for it (kits.folders,kits.compilers) where it's needed. A console that takes kits gets their compilers inConsole.compilers(it lists its own ascompilers; the connector addskit_compilers(), asMSVC/<version>), so a project can be switched to one like any other. The PC'stool_argspasses them to the build (own_compiler_args: configure.py's--own VERSION=RUNNER,CL,INCLUDE). Match by build, not by kit: the console picks the copy whose build is the game's (the Xbox'sgame_info: the XDK copy whose build equals the game's XDK build; the PC'sown_copy: the Rich header's version and build number against each copy'sbuild, else the nearest build of the same version, and it says so), and only when its packs don't have that build. A project template other than PC's takes--ownthe same way. ROM mode runs a kit's compiler too. A ROM project's compiler id may name anOwnCompiler(itsversion,ps3sdk-270):Console.kit_compilerslists it with the console's own,kits.own_compiler(id)finds it, andproject.compiler_configruns its exe from the user's copy (through wibo off Windows whenrunnersays, its folderrootand headers mounted read-only in the sandbox, nothing copied) withargsand the console's flags, in the same sandbox and limits as a pinned compiler;toolchains.get/known/installedanswer for it while the copy is set up. GCC-style arguments (-c -I -o) only so far;runner = "wine"is refused in ROM mode. Fillroot(the folder the compiler reads besidebin/),argsandflagswhen you add one, and let the console'sdefault_compilerpick the copy by build, as the PS3's does by the.commentstamp. A copy of a compiler a pack already has (another build of it) setsliketo that pack instead: it then runs through the pack's own command with its folder asroot(kits/owncompiler.py, the ROM consoles' "Your own PS2 compiler" and the rest), and its id starts with the pack's so a console'sstartswithflag rules apply to it. - Pass the tests:
uv run pytest tests/test_kits.py -q. It checks the facts, that it's a local toolchain nothing downloads, that a console takes it, and that no code outsidekits/and that console names it. Test it with a homemade folder (empty stand-ins, never a file of the real kit).
Each agent the app can start is one module: src/decompnet/agents/<id>.py. Everything decompdecomp knows about that
agent is in it: how a session starts, how to read what it prints, its models, where its settings are. The rest of
the app never asks "is this opencode?". It asks the helper's agent, agents.get(kind), through one file: the
connector, agents/__init__.py.
| Module | Agent | Its parts |
|---|---|---|
agents/claude.py |
Claude Code | claude -p with the app's MCP server as its only one; its model aliases and versions |
agents/codex.py |
Codex CLI | codex exec --json, the user's own MCP servers switched off for the run |
agents/antigravity.py |
Antigravity CLI | agy with stream-json in and out; its models from agy models; once Gemini CLI |
agents/opencode.py |
opencode | opencode run, its own server per helper (opencode 2); its models from opencode models |
agents/cursor.py |
Cursor Agent | Headless stream JSON with private settings and MCP allowlist |
agents/kimi.py |
Kimi Code | npm CLI, stdin prompt bridge and private settings |
agents/zcode.py |
ZCode CLI | zcode --output-format stream-json, its own settings file for the app's MCP server, the prompt in an attached file |
agents/ohmy.py |
Oh My Pi | omp -p --mode json, a settings overlay that keeps the user's own MCP servers out and the session's .mcp.json in |
agents/api.py |
API helper | No program: the app's own loop for any OpenAI-compatible API, and the saved endpoints' presets |
Around them:
| Where | What |
|---|---|
agents/__init__.py |
The connector: the Agent class (every fact and part, one line each) and the list of agents. |
agents/template.py |
The module to copy for a new agent. |
app/agents.py |
What's the same for every agent: starting and restarting helpers, waiting out usage limits, their records, ending everything they started when the app quits. |
app/tools.py |
The tools every agent gets, and its prompt (WORK_PROMPT). |
An agent is one of two sorts:
- A program the user installs and signs in to (Claude Code, Codex, Antigravity CLI, opencode, Cursor Agent, Kimi
Code, ZCode CLI, Oh My Pi). The app runs it headless, a session at a time, in a private folder. It connects only to
the app's own MCP server, with a token of its own, and may use only decompdecomp's tools. The prompt goes in on
stdin, or in a file the agent is given by path when its CLI has no stdin prompt (zcode's
--attach), never as text on the command line; what it prints is read into the feed. - A loop in the app (the API helper). It talks to a model's API itself and calls the tools directly.
- Open
agents/<id>.py. Its docstring says how a session runs and what the agent prints. - Change the part you need there. Something every agent needs (how long a helper waits after a failure) goes in
app/agents.py. - Run its tests:
uv run pytest tests/test_agents.py tests/test_agent_kinds.py tests/test_cursor_agent.py tests/test_kimi_agent.py -q. Never run the real program in a test: it starts the MCP servers in the user's own settings. Use a recorded line of its output instead.
-
Copy the template.
cp src/decompnet/agents/template.py src/decompnet/agents/<id>.py. Rename the class and the object at the end. -
Pick its sort. A program: fill in
commandand the session's parts. A loop in the app: leavecommandempty and fill inrun(seeagents/api.py). -
Fill in its facts. Each is one line in the
Agentclass:Fact What it is id,aliasesWhat helpers' records store as their kind. Keep it once helpers exist; old ids go in aliases.name,vendorWhat the app shows: its name, and who makes it (or whose models it runs). commandIts program, looked for on PATH. Empty for a loop in the app. install,signin,docsWhat "Install it for me" runs, how to sign in (shown when it isn't), its documentation. familyWho made its models, when it runs only one maker's ("gpt"). A function one model gave up on goes to another family first. models_argsThe arguments that list the models the user's sign-in offers ( ("models",)), read byread_models.tool_metaWhat it reads on each MCP tool's definition (Antigravity: load the tools up front). recommended,uses_endpoints,takes_effortFor the launcher: list it first; take its model and key from the saved API endpoints; offer a reasoning effort. -
Fill in the parts it needs. The rest keep their default, which does nothing or says it can't:
Part What it does session_command(exe, workdir, mcp_url, token, model)One session's command line, and what it adds to the environment. launch_command(argv)Adjust the command used to start the program when its installer uses a shim. stdin(prompt)What goes in on stdin: the prompt, as the agent reads it. parse(event, state)The feed items in one JSON event it prints: text, thinking, tool calls, errors, what the session spent. A protocol program (zcode) also says ("stdin", line) — the app writes the line to its stdin — and ("stop", line) when the work is done, ending a process that wouldn't exit on its own. clean_stderr(line)A line of its stderr worth showing, or "" for noise. fatal(error)Whether an error means every try would fail the same way: the helper pauses instead. models(path, run),read_models(lines)The models to offer in the launcher. config_model()The default model in the agent's own settings. version(path)Its version ( --versionby default).label(name, options, used)What the GUI calls a helper of it. run(manager, session, agent)A loop in the app: one session's work. -
Keep the user safe. A session connects only to the app's MCP server, with the token it was given, and to none of the user's own MCP servers. It may use only decompdecomp's tools: no shell, no file edits, no web. The token never goes on the command line, where every process can read it, and the prompt goes in on stdin or in a file the agent is given by path, never as text on the command line.
-
Register it in the list at the end of
agents/__init__.py(_registry). The Agents page lists the agents in that order. -
Pass the tests:
uv run pytest tests/test_agent_kinds.py tests/test_cursor_agent.py tests/test_kimi_agent.py -q. It checks the facts, the ids, the command line (no token on it) and that no code outsideagents/asks an agent's name. Add a test of its own totests/test_agents.py: a recorded line of its output, and the feed items it gives. -
Say it: add the agent to README.md's list of agents, docs/GUIDE.md's table and the site's agent list (
site/public/index.html).
- Talk it over first in
#contributorson the Discord, or in an issue. - Work on a branch named
<type>/<short-name>, the type one offeat,fix,refactor,perf,docs,test,ci,build,chore,revert(fix/ps2-long-symbol-names). CI fails a pull request from any other branch, and labels it by the prefix. - A change to a console or a feature says which of the app's features you ran on it and how (AGENTS.md, "Check every feature on the console you touch"); reviewers check the same list.
- Keep each one to one change, and say in the description what it fixes or adds, and how you tested it.
- A performance change (a
perf/branch) shows a before and after from the throughput benchmark: runuv run python -m decompnet.bench --out before.jsonon main and--out after.jsonon your branch, on the same computer, and pasteuv run python -m decompnet.bench --compare before.json after.jsoninto the description. A part that got faster but matches no more functions per CPU-minute isn't a win yet (docs/APP_PERFORMANCE.md, "Throughput: functions matched per CPU-minute"). - Commit messages describe what users get, in one sentence, with a body explaining why.
- Don't bump the version. Releases are made separately.
- Pull requests written with an AI agent are fine (AGENTS.md is there for it). Read the diff yourself, and make sure the tests pass.
By contributing you agree that your work is released under the project's license, the GNU AGPL version 3.
decompdecomp continues decomp.wtf, which is archived. Please don't open issues there.