PyKTANE

Welcome to PyKTANE's documentation!

Solvers for Keep Talking and Nobody Explodes: you describe the bomb, PyKTANE reads the manual. It only asks for what a rule actually needs, tracks strikes and per-module state, supports undo, and can be extended with modded module packs.

It also ships an optional MCP server, so an AI assistant can play the expert for you.

Read the Docs

Installation

PyPI

pyktane is available on PyPI:

# With uv
uv add pyktane
# With pip
pip install pyktane
# With Poetry
poetry add pyktane

For the MCP server, add the mcp extra: pyktane[mcp].

GitHub

You can also install the latest version of the code directly from GitHub:

# With uv
uv add git+https://github.com/MicaelJarniac/pyktane
# With pip
pip install git+git://github.com/MicaelJarniac/pyktane
# With Poetry
poetry add git+git://github.com/MicaelJarniac/pyktane

Usage

For more examples, see the full documentation.

As a library

from pyktane import NeedsInfo, Session

bomb = Session()
simon = bomb.add_module("Simon Says")
try:
    bomb.solve(simon, {"flashes": ["red", "green"]})
except NeedsInfo as missing:
    print(missing.fact.question)  # What is the serial number?

bomb.set_fact("serial", "AB3CD4")
bomb.solve(simon, {"flashes": ["red", "green"]}).instruction  # 'Press blue, yellow.'
bomb.strike()  # Simon Says changes with strikes.
bomb.solve(simon, {"flashes": ["red", "green"]}).instruction  # 'Press yellow, blue.'

Mistakes can be fixed wherever they happened, not just undone:

wires = bomb.add_module("Wires")
bomb.solve(wires, {"wires": ["red"] * 6})
bomb.correct(wires, {"wires": ["red"] * 5})  # "6 wires... wait, 5"

bomb.set_fact("serial", "AB3CD5")  # Misheard? Fixed from the start.

for entry in bomb.history:  # "That wasn't a strike": find it,
    print(entry.describe())  # e.g. "3: strike"
revision = bomb.remove_action(3)  # remove just that action,
for change in revision.changed:  # and hear which answers were wrong.
    print(change.instance, change.before.instruction, "->", change.after.instruction)
    # Simon#1 Press yellow, blue. -> Press blue, yellow.

bomb.undo()  # Every change, corrections included, can be undone.

Every module in the base game is supported: Wires, The Button, Keypads, Simon Says, Who's on First, Memory, Morse Code, Complicated Wires, Wire Sequences, Mazes and Passwords, plus the needy Venting Gas, Capacitor Discharge and Knobs. Their rules are checked against the official manual (v1, verification code 241).

With an AI assistant (MCP)

Add this to your MCP client's configuration (Claude Desktop, Claude Code, Cursor, opencode...):

{
  "mcpServers": {
    "pyktane": {
      "command": "uvx",
      "args": ["--from", "pyktane[mcp]", "pyktane-mcp"]
    }
  }
}

Then ask your assistant to be the expert, or use the server's defuse prompt. It records the edgework, asks you what it needs, and tells you what to do. It works well in voice mode: describe modules the way you'd say them ("vertical wires", "a big button"), and when an answer depends on something it doesn't know yet, it tells you what's safe to do right away first.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

More details can be found in CONTRIBUTING.

Contributors ✨

License

MIT

This project was created with the MicaelJarniac/crustypy template.