The Optimizer

The Optimizer

python iamnotacoder.py --files src/module.py --repo https://github.com/user/repo --branch main --token $GITHUB_TOKEN

Flags

Taken from the @click.option declarations in iamnotacoder.py, which is the authority when this disagrees with the README.

Flag	Short	Default	Meaning
--files	-f	none	The only required option. Comma-separated paths to improve
--repo	-r	none	Repository URL
--branch	-b	none	Target branch
--token	-t	none	GitHub PAT with the repo scope
--config	none	none	Path to a TOML config. No short flag, see gotchas
--tools	-T	black,isort,pylint,flake8,mypy	Static analysis tools to run
--exclude-tools	-e	empty	Tools to skip even if listed above
--llm-model	-m	qwen2.5-coder-14b-instruct-mlx	Model name
--llm-temperature	none	0.2	Higher is more random
--llm-custom-prompt	-p	.	Directory holding prompt_<category>.txt files
--llm-optimization-level	-l	balanced	fast, balanced, thorough
--min-coverage	-c	none	Minimum coverage percentage. -c is this, not --config
--categories	-C	style,maintenance,security,performance	Which improvements to apply
--test-framework	-F	pytest	Only pytest today
--output-file	-o	overwrite	Where to write the improved file
--output-info	none	report.txt	Text report path
--openai-api-base	none	none	Base URL for a local LLM
--fork-repo	flag	off	Fork first, work on the fork
--fork-user	none	inferred	Your username, when it cannot be inferred
--dry-run	flag	off	Do everything, change nothing
--local-commit	flag	off	Commit locally, no pull request
--no-dynamic-analysis	flag	off	Skip test generation and execution
--force-push	flag	off	Force-push the branch if it exists
--line-length	none	79	Formatting width
--debug	flag	off	Verbose logs, and keeps the temporary directory
--verbose	flag	off	Show detailed static analysis errors
--no-output	flag	off	Suppress most console output

Note that only --files is enforced as required, even though the README lists four. That is deliberate in effect: without --repo you are working locally, and the GitHub steps are skipped.

What a run does

1. Shallow-clones the repository into a temporary directory
2. Creates a branch with a generated name
3. Runs the selected static analysis tools, caching results when cache_dir is set
4. Generates tests with the LLM, unless --no-dynamic-analysis, and fixes syntax errors in what it generated
5. Runs the tests, and checks coverage if --min-coverage is set
6. Asks the LLM to improve the code, one pass per category, guided by the prompt files
7. Checks whether anything actually changed
8. Commits, including generated tests
9. Pushes the branch, to your fork when --fork-repo is used
10. Opens a pull request
11. Writes a text report and a JSON log
12. Removes the temporary directory, unless --debug

Steps 8 to 10 are the ones --dry-run and --local-commit cut off.

Running against a local model

export OPENAI_API_KEY=none
export OPENAI_API_BASE=http://localhost:1234/v1

python3 iamnotacoder.py --repo https://github.com/user/repo --files script.py \
  -b main -t $GITHUB_TOKEN --config config.toml --fork-repo

Any OpenAI-compatible server works, LM Studio being the one the defaults assume. With a local model, openai_api_key = "none" is the expected value rather than a placeholder to replace.

Reports

Each run writes a text report (report.txt by default) and a JSON log: which tools ran, what they found, what the LLM changed, and how the tests went. When a pull request looks wrong, the JSON log is where you find out which stage produced it.