Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.refactron.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
What is Refactron?

Refactron is a CLI for safety-first refactoring of Python and TypeScript codebases. The refactoring engine is 100% deterministic AST transforms — no LLM touches your code. Before any file is written, three gates must pass: syntax validity, import integrity, and your project’s full test suite on a shadow tree. Atomic write or rollback — never partial state.
Refactron analyzing and refactoring a legacy Python project
npm install -g refactron@0.2.3
cd your-project && refactron login
refactron analyze .
refactron run --apply

​
Why Refactron exists

Every existing “AI refactoring” tool generates code and hopes you’ll catch the bugs. NYU’s study of 1,692 Copilot programs found ~40% had exploitable vulnerabilities. An ACM AST 2024 study found 92.45% of Copilot-generated tests fail or are broken when there’s no existing suite. That’s a non-starter for production codebases. Refactron does the opposite. The engine is deterministic; the LLM is confined to Step 4 — generating documentation for already-verified refactors.

​
Core differentiators

Deterministic engine

10 transforms (5 Python, 5 TypeScript) implemented as pure AST rewrites via LibCST and ts-morph. No statistical inference; no model temperature.

3-gate verification

Syntax → imports → tests on a shadow tree. Every gate must pass before any byte hits your filesystem.

Atomic batch write

All-or-nothing rename via write-file-atomic. Either every change in a refactor commits, or none does.

Cross-file preconditions

Transforms refuse to apply when callers, mocks, or other-file dependencies would break. Skipped, not silently broken.

LLM only for docs

Documentation generation (Step 4) runs only on already-verified diffs. Five providers: Ollama, Groq, OpenAI, Anthropic, or our managed backend.

Honest limitations

No Ruby/Go/Rust adapters yet. Self-analysis fails by design. We tell you what doesn’t work in the FAQ.

​
How a refactor flows

Full breakdown of the safety model: The 3-Gate Safety Model.

​
Next steps

Quickstart

Install Refactron and run your first verified refactor.

The 3-Gate Safety Model

How syntax, imports, and tests gate every write.

Transform catalog

All ten transforms, with before/after and preconditions.

CLI reference

Every command, flag, and exit code.