Skip to content

Latest commit

 

History

History
425 lines (359 loc) · 34.2 KB

CONTRIBUTING.md

File metadata and controls

425 lines (359 loc) · 34.2 KB

Contributing to decompdecomp

Thanks for helping. Bug reports, fixes, new platforms and better guides for agents are all welcome.

The one rule: no game data

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.

Reporting a bug

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.

Working on the code

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 linter

There 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 projects passes. 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.

Consoles

Every console gets every feature

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:

  1. Build the shared part where every console uses it: app/ and network.py for the engine, rom/ and forks/ for each mode, arch/ for what depends on the processor.
  2. 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.
  3. 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.

Where a console's code is

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.

Improving a console

  1. Open consoles/<id>/__init__.py. Its docstring says which file does what.
  2. 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 in rom/ or forks/.
  3. Run its tests: uv run pytest tests/test_consoles.py -q -k <id>, and its own file (tests/test_ps2.py, ...).
  4. 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).

Adding a console

  1. 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.

  2. 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/ and consoles/pc/).

  3. Fill in its facts. Each is one line in the Console class:

    Fact What it is
    id, aliases What project configs store. Keep it once projects exist; old ids go in aliases.
    name, short What the app shows, and where space is short.
    status BETA until its conformance test passes and a real game rebuilt byte for byte; then RECOMMENDED.
    arch, big_endian Its processor, an id in arch/.
    mode, layout ROM or PROJECT, and what a project of it is ("splat", "dtk-template").
    compilers Its compilers (Compiler(id, name, built, guess)). The first is the default.
    packs More toolchains Setup offers for it, with what each is for (a proprietary compiler pack).
    guides, compiler_guide Guides agents read first; the one every helper gets up front.
    compiler_family Its compilers' family ("mwcc") when a project names no toolchain: the permuter's weights.
    m2c m2c's target for drafts ("mipsee-gcc"), or "" when m2c can't read its code.
    ram Where its programs live: words in this range are read as pointers.
    demo, demo_tools Its demo game's folder in projects/, and the tools building it needs.
    own_features EXPORT (a tree that rebuilds the game), REBUILD_CHECK (the project's rebuild check).
    as_flags, image_ext, asm_preamble ROM mode's export: assembler flags, the image's extension.
  4. 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_function ROM: 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_arch ROM: 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_functions ROM: 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: $gp as 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_compiler switches it (DS, Windows PC).
    compiler_config PROJECT: the files (globs in the project) file_compiler and file_ranges read: 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's symbols.txt). Without it, polished code keeps addresses for names.
    split_source(fp, version, source, at, new), splits_sources split_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_compiler try_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 piece and jumps (arch/arm.py; x86: piece, arch/x86.py) Pieces found and joined without agents, in on_start (see consoles/nds/recover.py, consoles/pc/scratch.py), when a tool finds its functions (ds-decomp, Ghidra) and can cut them.
  5. Its compilers. One pinned entry each in toolchains.toml (see "Adding a compiler" below).

  6. Its processor, if arch/ hasn't got it: add arch/<name>.py (relocation masks, capstone's mode, and asm_reason if you can tell hand-written code) and its Arch in arch/__init__.py.

  7. Its guides for agents: consoles/<id>/guides/<topic>.md. The first line is the guide's title.

  8. A demo game: projects/demo-<id>/build.py builds the Demo Quest game (projects/demo-n64/original) with the console's compiler, and writes build/demo.json: {"game": <file>, "symbols": {name: address}}. Use only code we may share. Never any part of a real game.

  9. Register it in the list at the end of consoles/__init__.py (_registry).

  10. Pass the conformance test: uv run pytest tests/test_consoles.py -q -k <id>. It builds the demo, checks sniff, 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.

  11. Say it: add a column to ROADMAP.md's table, and the console to README.md's and docs/GUIDE.md's lists.

  12. 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.

Adding a compiler to a console

Example: PC has Visual C++ 6.0 to 2010, and you want Visual C++ 2012 (11.0).

  1. 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 its url, its sha256 (sha256sum of the archive) and into = "11.0". An archive that's a whole install takes only its compiler and headers with keep (see msvc2005). A compiler of 2015 and newer compiles against a Windows SDK: that's a toolchain of its own (winsdk-<version>) the pack names in headers, so packs that use one SDK share it (see msvc2015); each version's folder then gets an includes.txt the 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's source (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.
  2. 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.
  3. How it runs on Linux. Windows compilers run through wibo (a pinned tool); check that the new cl.exe runs there. One wibo can't run goes in a pack marked wine = 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's configure.py run 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 needed msvcp100.dll beside it; 2005's and later linkers stop at lstrcmpiW in wibo 1.2.0). A Linux compiler needs nothing; a 32-bit one may need requires = ["runtime-i386"].
  4. The console lists it: consoles/pc/__init__.py, MSVC_VERSIONS. A ROM console's compilers are its compilers tuple: Compiler(id, name, built, guess) (see consoles/ps2/__init__.py).
  5. Which game used it. PC reads the program's Rich header: RICH_COMPILERS in consoles/pc/scratch.py already knows every Visual C++ version's product ids, and RELEASES the builds of its updates. RICH_BUILDS gives each compiler of the packs by the build its cl.exe says: once 11.0's is there, a game built with that build builds with it (another build of 11.0 with the closest), and Build.cannot_match stops saying it can't match. A PS2 program's .comment note says its GCC: _GCC in consoles/ps2/elf.py, and the compiler's guess names it.
  6. Its flags. The defaults are the toolchain's flags, and the console's default_flags adjusts them (the PS2's small data). PC projects write theirs in project_template/tools/configure.py (CL_FLAGS; from 8.0 on, /GX is /EHsc).
  7. MIPS only: search_flags tries flags by compiler family (FLAG_FAMILIES in app/engine/compilers.py), and the compiler map tells compilers apart by their habits (compilermap.py, quirks). Add the new family there.
  8. 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_COMPILERS in tests/test_ps2.py, NEWER in tests/test_pc.py), skipped when it isn't installed: pytest.mark.skipif(toolchains.installed(...) is None, reason="needs ...").
  9. Say it: the compiler in ROADMAP.md, README.md and docs/GUIDE.md where they list the console's compilers.

Adding a kit (a compiler or SDK users bring)

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.

  1. Copy kits/xdk.py to kits/<id>.py and 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).
  2. Its parts, each optional: locate(folder) (the copy a folder is or holds, when its layouts are more than files inside places: kits/visualcpp.py knows VC98, VC and VC/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 exact build) and known_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's folders; Remove forgets 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 its version name must be unique per copy (xdk-3911, own-9.0.30729: configure.py --own takes any name, and a project stores MSVC/<name>). kits.folders(id) lists the copies, kits.compilers(ids) the compilers of all of them.
  3. Register it in _registry at the end of kits/__init__.py. It shows in Setup as a toolchain of kind "local" (toolchains.registry adds it); it needs no entry in toolchains.toml.
  4. The console takes it: its kits names 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 in Console.compilers (it lists its own as compilers; the connector adds kit_compilers(), as MSVC/<version>), so a project can be switched to one like any other. The PC's tool_args passes 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's game_info: the XDK copy whose build equals the game's XDK build; the PC's own_copy: the Rich header's version and build number against each copy's build, 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 --own the same way. ROM mode runs a kit's compiler too. A ROM project's compiler id may name an OwnCompiler (its version, ps3sdk-270): Console.kit_compilers lists it with the console's own, kits.own_compiler(id) finds it, and project.compiler_config runs its exe from the user's copy (through wibo off Windows when runner says, its folder root and headers mounted read-only in the sandbox, nothing copied) with args and the console's flags, in the same sandbox and limits as a pinned compiler; toolchains.get/known/installed answer for it while the copy is set up. GCC-style arguments (-c -I -o) only so far; runner = "wine" is refused in ROM mode. Fill root (the folder the compiler reads beside bin/), args and flags when you add one, and let the console's default_compiler pick the copy by build, as the PS3's does by the .comment stamp. A copy of a compiler a pack already has (another build of it) sets like to that pack instead: it then runs through the pack's own command with its folder as root (kits/owncompiler.py, the ROM consoles' "Your own PS2 compiler" and the rest), and its id starts with the pack's so a console's startswith flag rules apply to it.
  5. 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 outside kits/ and that console names it. Test it with a homemade folder (empty stand-ins, never a file of the real kit).

Agents

Where an agent's code is

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.

Improving an agent

  1. Open agents/<id>.py. Its docstring says how a session runs and what the agent prints.
  2. Change the part you need there. Something every agent needs (how long a helper waits after a failure) goes in app/agents.py.
  3. 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.

Adding an agent

  1. Copy the template. cp src/decompnet/agents/template.py src/decompnet/agents/<id>.py. Rename the class and the object at the end.

  2. Pick its sort. A program: fill in command and the session's parts. A loop in the app: leave command empty and fill in run (see agents/api.py).

  3. Fill in its facts. Each is one line in the Agent class:

    Fact What it is
    id, aliases What helpers' records store as their kind. Keep it once helpers exist; old ids go in aliases.
    name, vendor What the app shows: its name, and who makes it (or whose models it runs).
    command Its program, looked for on PATH. Empty for a loop in the app.
    install, signin, docs What "Install it for me" runs, how to sign in (shown when it isn't), its documentation.
    family Who made its models, when it runs only one maker's ("gpt"). A function one model gave up on goes to another family first.
    models_args The arguments that list the models the user's sign-in offers (("models",)), read by read_models.
    tool_meta What it reads on each MCP tool's definition (Antigravity: load the tools up front).
    recommended, uses_endpoints, takes_effort For the launcher: list it first; take its model and key from the saved API endpoints; offer a reasoning effort.
  4. 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 (--version by 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.
  5. 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.

  6. Register it in the list at the end of agents/__init__.py (_registry). The Agents page lists the agents in that order.

  7. 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 outside agents/ asks an agent's name. Add a test of its own to tests/test_agents.py: a recorded line of its output, and the feed items it gives.

  8. 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).

Pull requests

  • Talk it over first in #contributors on the Discord, or in an issue.
  • Work on a branch named <type>/<short-name>, the type one of feat, 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: run uv run python -m decompnet.bench --out before.json on main and --out after.json on your branch, on the same computer, and paste uv run python -m decompnet.bench --compare before.json after.json into 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.