codingame-tools

Solve CodinGame puzzles and author CodinGame contributions from your own editor, under version control — instead of in the browser IDE.

Highlights

• Browser login — CodinGame has no API tokens, so cg login drives a real browser and captures the session. Works with any sign-in method, including third-party identity providers. Credentials are stored per profile; a headless --manual path exists for CI.

• Async client with structured API wrappers — CgClient exposes 22 service endpoints as typed methods, with dataclasses for every request and response, plus a helper layer that handles retries and the CDN timeouts that heavy operations provoke.

• Puzzle manager — a local working directory for solving a puzzle: import it, edit one file, run its test cases, submit. Language switching restores your own previous code, since CodinGame stores your latest source per language.

• Contribution manager — a local working directory for a puzzle you're writing. data/ is a real git working tree with main/server/version-data branches, so syncing with CodinGame is a genuine fetch/rebase/merge workflow — conflicts included — rather than a one-shot overwrite.

• A CLI exposing all of it — 148 commands, from the two workflow groups down to one subcommand per raw API method. Nothing is library-only.

• Local validation — run your solution against real test cases with no network access at all. Output comparison reproduces CodinGame's own rule exactly, measured against the live service, so a local pass predicts a remote one.

• VS Code integration, including debugging — generated run/debug configuration, breakpoints in your solution, and a test-case picker. Compiled languages build, run and debug inside Docker, so C++ works with no local toolchain at all.

• The protocol, documented — CodinGame publishes no API spec. Every endpoint here was reverse-engineered, wrapped in dataclasses, and documented with what it actually does — including the parts that contradict what the name suggests. Where behaviour was confirmed by probing the live service, the docstring says so.

• Fully typed — mypy clean across the package and its tests, py.typed shipped.

Installation

pip install codingame-tools

Quick start

cg login                          # opens a browser, saves credentials
cg whoami

cg puzzle import temperatures     # pull a puzzle into ./puzzle
$EDITOR puzzle/solution.py
cg puzzle play                    # run locally against downloaded test cases -- no network
cg puzzle submit                  # graded submission

Authoring a contribution:

cg contribution create ./my-puzzle "My Puzzle"   # purely local; nothing exists server-side yet
$EDITOR my-puzzle/data/statement.cgmd
cg contribution play                             # validate locally
cg contribution push                             # now it exists

Or use the client directly:

import asyncio
from codingame_tools.client import CgClient

async def main() -> None:
    async with CgClient() as client:
        for c in await client.services.contribution.get_all_pending_contributions():
            print(c.public_handle, c.title)

asyncio.run(main())

Documentation

• Documentation for this version — concepts, workflow guides, the client library, and a command reference generated from the CLI itself.
• Documentation for the latest release — if you're reading an older version's page and want current docs.

The first link is relative in the repository and is rewritten to an absolute, tag-pinned URL when a release is cut, so it resolves both on GitHub and on PyPI, and always points at the docs as they were for that version.

Caveats

This talks to a private API by imitating the web client. It will occasionally break when CodinGame changes something, usually as a clear error naming the field that moved. And some operations are irreversible or publicly visible — submitting creates a permanent graded submission, pushing updates real content, and running a server-side test durably overwrites your saved code. Commands that do any of that say so.

Supported Python versions

Python 3.10 through 3.14.

License

MIT. See LICENSE.

For development and release workflow, see CONTRIBUTING.md.