Heretic: An Open-Source CLI Tool for Modifying LLM Behavior Without Training
Explore Heretic v2.1, an open-source CLI that removes LLM refusals, suppresses slop, and reduces sycophancy using mathematical weight ablation (ARA and Ablitera
Altering the conversational disposition of a large language model (LLM) or lifting overzealous safety refusals traditionally required fine-tuning—an expensive process that demands extensive curated datasets, high compute budgets, and hours of backpropagation. Heretic, an open-source command-line tool authored by p-e-w, takes a distinct mathematical approach. Instead of retraining model parameters, Heretic steers weights directly using contrasting example prompts, pluggable behavioral scorers, and hyperparameter optimization, enabling creators to modify foundation models in an afternoon on consumer-grade hardware.

Image source: p-e-w/heretic (GitHub README)
Heretic rolled out its v2.1.0 release on November 8, 2026. Distributed under the GNU AGPLv3 license, the project has gained substantial traction across the machine learning community, amassing over 40,400 GitHub stars and 4,600 forks.
Contrasting Prompts and Optuna-Powered Optimization Architecture
Rather than executing standard gradient descent across millions of tokens, Heretic formulates model modification as a targeted hyperparameter optimization problem. It integrates pluggable modifier modules with a Tree-structured Parzen Estimator (TPE) optimizer driven by Optuna.
The modification pipeline begins by contrasting behavioral prompts—for example, benign prompts that trigger false-positive refusals versus neutral task completions—to identify activation pathways associated with the target behavior. The optimizer systematically tests parameter variations across model layers, searching for settings that minimize or maximize metrics computed by modular scorer plugins.
Heretic includes two primary modifier engines:
- Arbitrary-Rank Ablation (ARA): The default modifier, developed specifically for Heretic (Weidmann 2026). It applies surgical tensor adjustments across arbitrary matrix ranks without blunt layer zeroing.
- Directional Ablation (Abliteration): The classic refusal suppression approach grounded in representation engineering (Arditi et al., 2024). Heretic enhances this baseline with flexible ablation weight kernels across transformer layers, projected abliteration, and norm preservation (MPOA).
Standard, unguided abliteration scripts often cause collateral damage, degrading general reasoning capability while attempting to excise refusals. Heretic mitigates this regression by co-optimizing behavioral metrics alongside a Kullback-Leibler (KL) divergence scorer (kl_divergence.py). By penalizing divergence from the base model's broader token probability distribution, the optimization loop identifies weight interventions that strip unwanted behaviors while preserving core cognitive performance.
Preset Configurations: Beyond Censorship Removal
While Heretic's default configuration (config.default.toml) targets refusal suppression, the repository includes several dedicated configuration files designed to reshape distinct behavioral quirks:
- Slop Suppression (
config.noslop.toml): Dampens repetitive, vacuous AI filler phrasing and generic introductory platitudes. - Sycophancy Reduction (
config.nosyco.toml): Decreases the model's tendency to echo user misconceptions or validate biased premises. - Humor Reduction (
config.nohumor.toml): Strips playful banter and forced levity in favor of direct, utilitarian prose. - Emotional Realignment (
config.emotions.toml): Calibrates the emotional undertone and empathy markers in responses. - Terse Outputs (
config.terse.toml): Trims extraneous conversational padding to produce concise, direct answers.
Developers can also build bespoke objective functions by subclassing the abstract Scorer class defined in scorer.py. Defining a custom get_score method and supplying the file path (path/to/plugin.py:MyScorerClass) in the TOML configuration allows users to steer models toward specialized domain criteria without editing Heretic's source code.
Installation, Hardware Requirements, and 4-Bit Quantization
Heretic runs on systems equipped with Python 3.10 or newer and PyTorch 2.6 or higher. The package is distributed directly through PyPI:
pip install -U heretic-llm
heretic Qwen/Qwen3-4B-Instruct-2507
Upon invocation, Heretic benchmarks host hardware to determine the optimal batch size before starting optimization. Once processing concludes, the CLI presents an interactive workflow to inspect the model through a built-in terminal chat interface, run standard benchmarks, save modified weights locally, or push the artifact directly to Hugging Face.
Operational parameters and compute profiles include:
- Quantized Processing: Setting
quantization = "bnb_4bit"enables on-the-fly 4-bit model quantization via bitsandbytes. While introducing a minor precision trade-off, this reduces VRAM requirements to match standard 4-bit inference footprints, unlocking large dense model modifications on consumer setups. - Processing Runtime: On a single NVIDIA GeForce RTX 3090, processing a 4-billion parameter model like
Qwen/Qwen3-4B-Instruct-2507using default settings typically takes 30 to 40 minutes.
Reproducibility Manifests and Migration Considerations
Reproducing exact tensor modifications across different systems often fails due to driver inconsistencies, CUDA non-determinism, and library mismatches. Heretic resolves this reproducibility gap by producing a lightweight manifest folder containing reproduce.json (approximately 9 KB) alongside human-readable setup documentation whenever a model is published.
To reproduce an identical artifact from scratch in an equivalent software environment, users invoke:
heretic --reproduce path/to/reproduce.json
Heretic automatically inspects system packages, verifies environment alignment, and executes the exact optimization trace recorded in the manifest.
Users should note key operational boundaries. Configuration files authored for Heretic 1.x are incompatible with Heretic 2.x releases; existing pipelines must update their TOML schemas using docs/migration_v1_to_v2.md. Furthermore, while the configuration syntax anticipates multi-modifier pipelines, current versions restrict each execution run to a single active modifier (ARA or Abliteration).
Sources
- GitHub Repository: p-e-w/heretic
- Official Project Homepage: Heretic Project
- Hugging Face Organization: Heretic Org