ferrum0.1.0

The coding assistant that shows its work.

Ferrum is a small command-line tool for C, C++, Rust, and Python projects. It reads your code before it answers, shows every change as a diff for your approval, and never says a fix is verified unless the build or tests actually passed.

Install Ferrum
a real session — an off-by-one bug, found and proven fixed
$ ferrum fix "sum prints 14 instead of 15"Ferrum > reading main.c...Ferrum > reading Makefile...Ferrum > proposing a patch to main.c...@@ -5,7 +5,7 @@-    for (size_t i = 1; i < count; i++) {+    for (size_t i = 0; i < count; i++) { Apply patch? [y/N] y--- build: PASS (clang)✓ Fix verified

How it works

  1. 1

    Point it at a project

    Run ferrum . in any project folder. Ferrum maps the files, languages, and build system — a read-only pass that touches nothing.

  2. 2

    Ask a question or describe a bug

    Ferrum investigates by opening real files and searching real names, then answers with file and line references you can check. In fix mode it proposes one patch at a time, as a diff.

  3. 3

    Approve, then verify

    Press y and it applies the change, runs your build and tests, and reports exactly what happened — a pass is a pass, a failure is a failure, and you see the output either way.

What you get

Reads first, writes last
Every answer is built from files Ferrum actually opened, with citations like main.c:8 so you can verify the reasoning yourself.
Nothing changes without you
Patches arrive as unified diffs behind a yes/no prompt. Decline, and the file stays exactly as it was.
Verification or it didn't happen
Ferrum runs your real build — Make, Cargo, CMake, or a direct compiler call — and your tests, then shows the actual output.
Honest results
If verification fails, Ferrum says so and exits with an error code. It never dresses up an unverified guess as a fix.
Your model, your choice
Use Ollama on your own machine or any cloud API that speaks the OpenAI format. Switch between them with one command.
Preview before you commit
fix --dry-run shows the exact patch Ferrum would make — diff, diagnosis, and all — without touching a file.
Setup in one screen
ferrum doctor checks your configuration, model endpoint, and compiler toolchain, and tells you plainly what is ready and what is missing.

Usage

Six commands cover most of what you do. Click any of them to copy.

ferrum .

Inspect a project: languages, build system, and files.

ferrum "why does sum() print 14 instead of 15?"

Read-only diagnosis, answered with file and line references.

ferrum fix "make it print 15"

Propose a patch, approve it, build, and verify.

ferrum fix --dry-run "make it print 15"

The same, but no file is ever written.

ferrum doctor

Check configuration, endpoint, and toolchain at a glance.

ferrum config local

Switch between a local Ollama model and your cloud model (ferrum config cloud).

Install

Ferrum needs Python 3.10 or newer and a model endpoint — a local Ollama server or any OpenAI-compatible API. Nothing else.

uv tool install --from ferrum-cli ferrum

with uv

pip install ferrum-cli

with pip

Then run ferrum doctor — it walks you through the rest. View on PyPI