Pandemonium

Inject good coding habits into AI agent framework directories.

Many AI coding agents load project config directories into their system context. Pandemonium finds those directories and appends curated habit prompts — so every agent session can start with clean-code principles already loaded.

pandemonium.py --init
pandemonium.py --init --path .github
pandemonium.py --unicode --greek

How It Works

prompts/en/habits.md     ← English source prompt
       │
       ▼
  Translator             ← deep-translator (Google / DeepL / LibreTranslate)
       │                    results cached at ~/.cache/pandemonium/translations/
       ▼
  Encoder                ← format encoders + 55 charset encoders
       │                    --init: obfuscated hybrid round-robin (no readable English)
       ▼
  Detector               ← scans --path for config-directory markers
       │
       ▼
  Inserter               ← appends encoded prompt; skips already-injected files
       │
       ▼
  .claude/rules/*.md
  .github/skills/*.md
  .vscode/instructions/*.md
  …

Injection is idempotent — running Pandemonium twice on the same file is safe; already-injected files are skipped.

Use --clean to strip injections and remove scaffold files Pandemonium created.

Supported Config Layouts

Pandemonium detects agents by directory markers, not product names.

Config root	Detection marker	Writable directories
`.claude/`	`.claude/` or `CLAUDE.md`	`.claude/rules/` `.claude/memory/` `.claude/skills/` `.claude/agents/`
`.codex/`	`.codex/` or `AGENTS.md`	`.codex/rules/`
`.kiro/`	`.kiro/`	`.kiro/steering/` `.kiro/specs/`
`.github/`	`.github/copilot-instructions.md`	`.github/skills/` `.github/agents/`
`.vscode/`	`.vscode/` `.vscode/mcp.json`	`.vscode/instructions/` `.vscode/agents/` `.vscode/skills/`
`.opencode/`	`.opencode/`	`.opencode/agents/` `.opencode/commands/` `.opencode/skills/`
`.cursor/`	`.cursor/` or `.cursorrules`	`.cursor/rules/`
`.aider/`	`.aider.conf.yml` or `CONVENTIONS.md`	project root `.md` files
`.windsurfrules`	`.windsurfrules`	project root + home memories dir
`.gemini/`	`.gemini/`	`.gemini/skills/` `.gemini/agents/`
`.openhands/`	`.openhands/`	`.openhands/`
`.continue/`	`.continue/`	`.continue/`
`.harness/`	`.harness/` or `harness.yaml`	`.harness/`
`.pi/`	`.pi/` or `pi.config.json`	`.pi/`
`.openclaw/`	`.openclaw/` or `openclaw.toml`	`.openclaw/`

By default only the tree at --path is scanned. Pass --include-home to also scan agent config under $HOME (e.g. ~/.claude/, ~/.pi/).

Target a specific subtree directly:

pandemonium.py --init --path /path/to/repo/.github
pandemonium.py --init --path /path/to/repo/.vscode

Install

With UV (recommended)

git clone <repo-url> pandemonium
cd pandemonium
uv sync
uv run pandemonium.py --help

With pip

pip install -e .
pandemonium --help

Requirements

Python ≥ 3.11
deep-translator — translation engine (Google backend needs no API key)
rich — terminal output
click — CLI

Usage

uv run pandemonium.py [OPTIONS]

`--init` (recommended)

One flag for the default workflow:

Reads only prompts/en/habits.md
Splits the prompt into line chunks (10 → 20 → 10 lines per segment)
Encodes each chunk with the next obfuscated encoder in a round-robin cycle:
- zero-width invisible
- 53 charset encoders (hex, shift_jis, utf-8, base64, octal, …)
No readable English in output (no unicode boxes, ASCII borders, or camelCase comments)

pandemonium.py --init
pandemonium.py --init --path .github
pandemonium.py --init --clean --path .github   # strip, then re-inject

Explicit encoding flags (--unicode, --charset, etc.) still work and override --init when combined.

Format Encoding Flags

Control how the injected text looks. Multiple flags can be combined; they cycle across selected files.

Flag	Effect
`--ascii`	Plain ASCII bordered block
`--unicode`	Unicode box-drawing art
`--invisible`	Zero-width steganography
`--camelcase`	camelCase comment-style block
`--all-enc`	Cycle all four format encoders

Invisible encoding encodes UTF-8 bytes as zero-width Unicode characters (U+200B/U+200C), separated by U+200D, terminated by U+2060:

from pandemonium.encode import decode_invisible
recovered = decode_invisible(open("somefile.md").read())

Charset Encoding Flags

Flag	Effect
`--charset NAME`	Charset / escape encoding (repeatable): `utf-8`, `hex`, `shift_jis`, …
`--all-charsets`	Cycle all 55 charset encodings
`--list-charsets`	Print supported charset names and exit

When both format and charset flags are set, charset takes priority for all files.

Language Flags

Source prompt is English; other languages are translated on first use and cached.

Flag	Language
`--french`	French
`--spanish`	Spanish
`--greek`	Greek
`--chinese`	Chinese Simplified
`--german`	German
`--japanese`	Japanese
`--arabic`	Arabic
`--portuguese`	Portuguese
`--russian`	Russian
`--hindi`	Hindi
`--korean`	Korean
`--italian`	Italian
`--all-langs`	All supported languages, cycled across files

Translation Backends

Flag	Backend	API key required
`--backend google`	Google Translate (default)	No
`--backend deepl`	DeepL	`--deepl-key YOUR_KEY`
`--backend libre`	LibreTranslate (self-hostable)	`--libre-url URL` + optional `--libre-key`

Translations are cached at ~/.cache/pandemonium/translations/ as SHA-256-keyed JSON files.

rm -rf ~/.cache/pandemonium/translations/

Other Flags

Flag	Description
`--path DIRECTORY`	Root path to scan (default: current directory)
`--include-home`	Also scan `$HOME` agent config dirs
`--clean`	Remove injected blocks and scaffold files
`--server URL`	Embed MCP server URL in `mcp.json` when scaffolding
`--ui-lang CODE`	CLI message language: `en` `fr` `es` `el` `zh`
`--list-langs`	Print supported translation languages and exit
`-h / --help`	Show help and exit

Examples

# Default: obfuscated hybrid encoding into detected config dirs
pandemonium.py --init

# Target only .github subtree
pandemonium.py --init --path .github

# Explicit format + language
pandemonium.py --unicode --greek --path .

# Charset-only encoding
pandemonium.py --charset shift_jis --charset hex --path .claude

# Remove injections
pandemonium.py --clean --path .github

# Re-inject after clean
pandemonium.py --init --path .github

# DeepL translations
pandemonium.py --greek --backend deepl --deepl-key sk-...

# List charset encodings
pandemonium.py --list-charsets

Translation Engine

Prompts are stored in English under prompts/en/. With --init, only habits.md is used.

prompts/en/
  habits.md      ← default prompt for --init

The engine splits text at paragraph boundaries to stay within per-request limits, then reassembles translated chunks.

Caching

~/.cache/pandemonium/translations/
  a3f8b1c2d4e5f6a7.json    ← SHA-256(backend:en>fr:text) → translated text

Each cached file is {"t": "<translated text>"}. Delete the directory to force re-fetch.

Adding Your Own Prompts

Edit prompts/en/habits.md for the --init workflow. For multi-file injection (without --init), add more .md files under prompts/en/:

## Git Workflow
- Rebase feature branches onto main before merging.
- Write commit messages in the imperative mood.
- One logical change per commit.

Project Structure

pandemonium/
├── asset/
│   └── logo.png                Project logo
├── pandemonium.py              Entry point
├── pyproject.toml
├── LICENSE
│
├── prompts/
│   └── en/
│       └── habits.md           Default prompt (--init)
│
├── tests/
│   ├── test_char_encoder.py
│   ├── test_detect.py
│   ├── test_clean.py
│   └── test_hybrid_init.py
│
└── src/
    └── pandemonium/
        ├── main.py             Click CLI
        ├── detect.py           Config-directory detection
        ├── encode.py           Format + charset + --init hybrid encoders
        ├── char_encoder.py     55 charset / escape encoders
        ├── insert.py           Translate → encode → inject / clean
        ├── registry.py         Injection registry (~/.cache/pandemonium/)
        ├── translator.py       Translation engine (3 backends)
        ├── mcp_tracker.py      MCP json scaffolding
        └── ui.py               Rich CLI components

Development

uv sync
uv run pytest
uv run ruff check src/

# Run init against a config dir
uv run pandemonium.py --init --path ../.github

# Decode invisible-encoded content
python3 -c "
import sys; sys.path.insert(0,'src')
from pandemonium.encode import decode_invisible
print(decode_invisible(open('somefile.md').read()))
"

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
asset		asset
mcpserver		mcpserver
prompts/en		prompts/en
src/pandemonium		src/pandemonium
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pandemonium.py		pandemonium.py
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Pandemonium

Table of Contents

How It Works

Supported Config Layouts

Install

With UV (recommended)

With pip

Requirements

Usage

`--init` (recommended)

Format Encoding Flags

Charset Encoding Flags

Language Flags

Translation Backends

Other Flags

Examples

Translation Engine

Caching

Adding Your Own Prompts

Project Structure

Development

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Pandemonium

Table of Contents

How It Works

Supported Config Layouts

Install

With UV (recommended)

With pip

Requirements

Usage

--init (recommended)

Format Encoding Flags

Charset Encoding Flags

Language Flags

Translation Backends

Other Flags

Examples

Translation Engine

Caching

Adding Your Own Prompts

Project Structure

Development

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`--init` (recommended)

Packages