geng/ 1 FILE 0 SETUP

For people who code with AI

Give an AI one job
at a time.

Split the work. Limit the tools. Let a test decide.

ONE BIG JOB

SPLIT INTO STEPS

Left: memory fills, then it approves its own work. Right: fresh memory each step, verdict from outside.

Run one in 60 seconds GitHub

PART 1 / THE PROBLEM

Ask for a refund button,
get three problems.

01

It runs out of room

An AI holds only so much at once. By attempt four it has forgotten attempt one.

02

It marks its own work

The AI that wrote the code decides if the code is right. It says yes.

03

It held the keys all along

To finish in one go it could send money the whole time, including while still deciding whether to.

Problem 3 is the quiet one. You gave it the keys and a note asking it to be careful.

PART 2 / THE FIX

Hand out tools per step.

The step that decides has no refund tool.

STEP 1 / DECIDE

STEP 2 / ACT

Watch the red row arrive. Step 1 cannot send money however confused it gets. That power appears only after the check passes.

A rule asks the AI to behave. A missing tool means misbehaving is not available. That is the whole point.

PART 3 / FOUR WORDS

Labels for what you just saw.

STEP

One run of one thing

An AI, or an ordinary program like a test runner.

HAND-OFF

A saved file

A step's answer goes into a file. The next step reads it.

VERDICT

A number, not an opinion

Programs report 0 when fine. geng believes the number.

GATE

A step that can stop it all

The CHECK box above. If it fails, nothing after it runs.

Why the number? Cursor prints nothing readable when it breaks. Kiro and aider have no report at all. Claude, Codex and Gemini use three formats. All nine report the number.

PART 4 / THE FILE

One small text file.

refund.toml

# an AI that can read, but not send money
[agents.checker]
argv = ["claude", "-p", "--allowedTools", "Read"]

# a plain command, not an AI
[agents.shell]
argv = ["bash", "-lc", "{prompt}"]

[nodes.decide]
agent  = "checker"
prompt = "Is order 4471 refundable?"

[nodes.tests]
needs  = ["decide"]  # wait for it
agent  = "shell"
gate   = true        # the stop sign
prompt = "npm test"

Running it

$ python geng.py run refund.toml

wave 1  (1 node(s), 4 at a time)
  ok   decide

wave 2  (1 node(s), 4 at a time)
  FAIL tests exit=1 .geng/log/tests.log

halted: gate node(s) failed: tests

Tests failed, so it stopped before touching money. node is geng's word for step, wave for round.

Swap claude for your AI. Nothing else changes.

PART 5 / YOUR TURN

Run one now. No AI needed.

Needs Python. Costs nothing.

git clone https://github.com/AdityaIndoori/graph-engineering
cd graph-engineering
python geng.py run examples/smoke.toml
EXPECT

6/6 ok

Six steps, three at once, one gate, one retry after two failures.

RUN IT AGAIN

All cached

Under a second. geng skips what already worked.

EDIT A PROMPT

Only that part repeats

That step and the ones after it. The rest stay cached.

IF IT BREAKS

Read the log

FAIL prints a file path holding the command and its output.

PART 6 / FREE SPEED

Steps that do not wait
run together.

Three 2-second steps together: 2.3s. One after another: 6s. Round 2 needs all three answers, so it waits.

PART 7 / SAFETY

Two AIs, one file,
no mess.

Each step gets a private copy of the project, so both write freely. Your files stay put. A failed step leaves nothing behind. Needs git; skip this and the rest still works.

PART 8 / GOING FURTHER

Three ways in.

START HERE

Build one by hand

Empty file to working setup. First half needs no AI.

Tutorial
WITH A REAL AI

omp or Claude Code

Including which settings really remove edit access, and which only look like they do.

omp Claude
THE AI WAY

Let an AI write it

Describe the job in English, get the file, check it before it runs.

How

The AI way: paste this, fill in the blank

Your AI has never heard of geng, so the two links teach it the format. Replace the last line with your own job.

Read these two files first:
https://raw.githubusercontent.com/AdityaIndoori/graph-engineering/main/docs/GENG_FOR_AI.md
https://raw.githubusercontent.com/AdityaIndoori/graph-engineering/main/geng.py

Then write me a geng TOML spec, and nothing else, that:
<describe your job here, for example: audits every file in src/ for missing
error handling, then writes tests for what it finds, then runs pytest as a gate>

Rules: put review and planning steps on a read-only agent, end with a gate that
runs a real test command, and only use placeholders from a step's own needs.

Then check it before it runs: python geng.py plan yourfile.toml draws it and refuses broken files, and --dry-run shows the exact commands.

Two safe commands

python geng.py plan g.toml
python geng.py run g.toml --dry-run

Both run nothing and cost nothing. The second prints the exact commands first.

Works with your AI

Claude Code["claude", "-p"]
Oh My Pi["omp", "-p"]
Codex["codex", "exec"]
OpenCode["opencode", "run"]
Kiro["kiro-cli", "chat"]
Gemini["gemini", "-p"]
Cursor["cursor-agent", "-p"]
Amp["amp", "-x"]
aider["aider", "--message"]

PART 9 / BE HONEST

Most jobs do not
need this.

Fixing one function? Just ask the AI.

USE IT WHEN 1

Too big to remember

Many files, and the AI keeps forgetting earlier decisions.

USE IT WHEN 2

You need a real check

Too important to let the author approve its own work.

USE IT WHEN 3

You are waiting around

Unrelated jobs running one by one.

The trap. Ten classmates checking your homework, all copying from the same wrong textbook, will all agree. Ten AI steps do the same. So let a real test decide, and get second opinions from a different AI.

Four steps cost about four times one step. And you still have to read the result. That is the real limit.

PART 10 / RECEIPTS

53 tests, 3 systems.

Every promise on this page is checked automatically.

  • Edit one step and only that step, plus what follows, runs again.
  • A failed gate skips everything after it.
  • Two steps writing one file land in separate copies. Yours stay untouched.
  • A failed step saves nothing, so it cannot look finished.
  • A second run started mid-run is refused, not scrambled.
  • --dry-run writes nothing at all.
Read the tool Read the tests Nine slides

One file, about 600 lines, nothing but plain Python.

Short answers

Likely questions.

No Python?
Get 3.11 or newer from python.org. Nothing else to install.
Can I use ChatGPT?
Not the website. geng runs commands, so it needs an AI that runs on your computer. The nine above do.
Is my file correct?
geng.py plan draws it and refuses broken files. Then --dry-run shows the commands.
What does it cost?
geng is free. Your AI charges per step, so four steps cost about four times one.
Do I need git?
Only for the private copies in Part 7.
Just a new name for an old idea?
Mostly, yes. The useful part is Part 2. Longer version.
Safe to run a stranger's file?
No safer than any script they send you. These run real commands.
Mix different AIs?
Yes, and you should. One builds, another checks.
Get it on GitHub Run the example