Known Gotchas

Known gotchas

Differences between the README and the code, verified against the source. The code is the authority.

-c is --min-coverage, not --config

The README documents --config (-c), and shows this as its first example:

python iamnotacoder.py -r ... -f src/my_module.py -b main -t TOKEN -c config.toml

In the code, -c is the short flag for --min-coverage, which is typed as a float. --config has no short flag at all. So that command does not load a configuration file: it tries to parse config.toml as a coverage percentage and fails.

Use the long form:

python iamnotacoder.py -r ... -f src/my_module.py -b main -t TOKEN --config config.toml

The shipped config.toml has no effect

It is written with sections, and the loader hands the parsed TOML to Click as a default_map, which matches only top-level keys. Sections mean no key matches an option, so every value is ignored and the defaults apply, silently.

Full explanation and the flat form that does work in Configuration and prompts.

Only --files is actually required

The README lists --repo, --files, --branch and --token as required. In the code only --files carries required=True. The rest are optional, which is what allows a local run with no GitHub interaction. Nothing stops you starting there.

Two flags named in the README with different behaviour

• --fast exists in the configuration as fast, commented in the shipped file as a no-op
• --llm-optimization-level accepts fast, balanced and thorough, and the config file marks it as future use

Neither is load-bearing today. Do not tune them expecting an effect.

Safety rails to keep on

This tool clones a repository, rewrites source files with an LLM, commits, pushes and opens a pull request. In order of how much they protect you:

1. --dry-run runs everything and writes nothing. Use it first, every time you change prompts, model or categories
2. --fork-repo works on a copy in your own account. Without it, the branch is pushed to the target repository, which needs write access you may well have on your own projects. That is exactly when it is easy to forget
3. --local-commit stops before the pull request, so you can read the diff with normal git tooling
4. --force-push off. It overwrites a remote branch. There is no undo for the person whose branch it was
5. max_files_per_pr bounds the size of a single pull request. A very large diff will not be reviewed, by anyone

The tests it generates are not verification

Tests are generated by the same model that rewrote the code, from that code. They can pass while encoding the same misunderstanding. Coverage thresholds tell you how much of the file was executed, not that the behaviour is right.

Useful as a smoke test, not as evidence that a refactor is safe.