Promptr turns a prompt file into a pull request worth reviewing

The unit of work is a file, not a conversation

The README describes Promptr as a CLI tool that lets you use plain English to instruct OpenAI LLM models to make changes to your codebase, with changes applied directly to the files referenced from the prompt. That framing matters, because it rules out the interactive chat pattern most people expect from a coding assistant. There is no session, no follow up question, no approval step inside the tool. The interface is a prompt plus a list of paths.

promptr [options] -p "your instructions" <file1> <file2> <file3> ...

The workflow the README recommends around that command is the interesting part: commit any changes so you have a clean working area, author the prompt in a file, make sure the prompt contains the relative paths of the files it refers to, then run the tool and inspect the results with your favorite git UI. The tool writes to your working tree and a human looks at the diff afterwards. That is why a dry run flag exists, and why the answer to whether the output is trustworthy is not about the model at all, it is about whether the resulting diff passes review.

The project points at two pull requests as worked examples, 38 and 41, and says the individual commits and the prompts that created them are linked in the PR descriptions. Reading the prompt next to the diff it produced is the fastest way to learn what the tool does well, since both halves are public.

Liquid templating is the part that scales past one file

Promptr renders prompts through liquidjs, the JavaScript implementation of the Liquid template language. The README frames this as a feature for larger projects with repetitive patterns or standards, and the mechanism is the render function.

{% render '_project.liquid' %}
// your prompt here

The include file holds the project wide rules. The example given in the README is a file named `_poject.liquid`, with the typo in the name apparently part of the original, containing constraints like these.

This project uses Node version 18.
Use yarn for dependency management.
Use import not require in Javascript.
Don't include `module.exports` at the bottom of Javascript classes.
Alphabetize method names and variable declarations.

Those five lines are the entire value proposition for teams. Instead of restating the house style in every prompt, it lives in one file that gets rendered into every prompt, and a change to the rules applies to the next run rather than to prompts already written. The README names three use cases for it: project wide coding standards, boilerplate snippets for things like model definitions and API endpoints, and shared instructions such as how to document functions.

One consequence is worth thinking about before you adopt it. Rendering happens before the request goes out, so a mistake inside an include file is invisible in the prompt you typed. The dry run flag exists partly for this reason, since it shows the prompt that will be sent without touching your filesystem.

Nine flags, and the two that matter most

The options table is long enough to be worth reading in full, because several flags change what the tool does to your disk rather than what it prints.

The apply flag is the important one.

| `-x` | Optional boolean flag. Promptr parses the model's response and applies the resulting operations to your file system when using the default template. You only need to pass the `-x` flag if you've created your own template, and you want Promptr to parse and apply the output in the same way that the built in "refactor" template output is parsed and applied to your file system. |

With a built in template the tool applies operations on its own, and with a custom template you have to say so explicitly. That asymmetry is the safety property of the design, and it is also the first thing to check when a run produces nothing.

The rest of the surface covers model selection with -m defaulting to gpt-4o, dry run with -d, interactive mode with -i, template choice with -t where the built ins are empty, refactor, swe and test-first, output path with -o which prints to stdout when unset, verbose with -v, and disable-auto-context with -dac, which stops files named in the prompt from being attached automatically. The prompt option itself takes a path or a url, so the instruction text can live anywhere fetchable, including a private gist or an internal docs page.

Five runtime dependencies and a 2023 SDK pin

The manifest lists five dependencies, and one of them dates the project.

  "dependencies": {
    "commander": "^10.0.0",
    "gpt-3-encoder": "^1.1.4",
    "liquidjs": "^10.7.0",
    "openai": "^3.3.0",
    "prompt-sync": "^4.2.0"
  },

commander parses the flags, liquidjs renders the templates, gpt-3-encoder counts tokens, and prompt-sync formats the conversation payload. The openai entry at ^3.3.0 is the fact to sit with. The README documents gpt-4o as the default model, and gpt-4o was announced well after the 3.x line of the JavaScript client was current, so the tool is calling a current model through a client library from an older major generation. That is not automatically broken, since a REST call is a REST call, but it does mean you are not getting whatever the current SDK does about retries, streaming and error shapes, and it is the most likely reason for surprising behavior if you try a newer model name.

The two descriptions of the tool disagree in a smaller way that is still informative. The README says plain English instructions to OpenAI LLM models, while the manifest description says instructs GPT3 or GPT4 to make changes to your codebase, and the model flag still accepts the value gpt3 as shorthand for gpt-3.5-turbo. The documentation has moved on to model agnostic wording while the flag surface still carries the old generation. Neither statement is wrong, and the practical reading is that the tool is model agnostic in intent and conservative in what it has been tested against.

The build produces binaries for three platforms, the README says one

The installation section offers three routes: a global install through yarn, a global install through npm, or copying a release binary for the current release to your path. The README then states that only MacOS is supported right now for the binary route.

The manifest disagrees, or rather it tells you where that claim came from.

    "build:win": "cd dist && pkg -t node18-win . && cd ..",
    "build:macos": "cd dist && pkg -t node18-macos . && cd ..",
    "build:linux": "cd dist && pkg -t node18-linux . && cd ..",

There are three pkg targets in the build scripts, one per platform, so the project can be built for Windows and Linux as well. Both statements can be true at once: building is possible everywhere, and published binaries are only produced for MacOS. If you are on Linux, the npm route is the one that works today, since it just installs the package and runs bin/index.js.

The bundle script assembles that package by running webpack, copying build.json to dist/package.json and installing inside dist, and the binary smoke test is a single shell pipeline that generates a JavaScript class, prints the file and deletes it again.

    "test-binary": "cd dist && ./promptr -p \"Create a new javascript class called AwesomeClass in AwesomeClass.js\" && cat AwesomeClass.js && rm AwesomeClass.js && cd .."

That test is worth understanding as a design statement. It treats the interesting behavior of the whole tool as one thing, can a prompt create a new file, and it verifies that by looking at the bytes on disk. Everything else in the repository, the src and test directories, webpack.config.js, build.json and a yarn.lock, supports producing a single executable that does that.

A release history of three entries

There are three published releases, and their contents describe the trajectory of the tool more clearly than the changelog does.

    "name": "@ifnotnowwhen/promptr",
  "version": "6.1.0",

The version in the manifest is 6.1.0, and the releases are v6.0.6 from 2024-01-26, v6.0.7 from 2024-05-18 and v6.1.0 from 2024-05-22. v6.0.6 defaulted the GPT4 model to gpt-4-turbo-preview, v6.0.7 changed that default to gpt-4o, and v6.1.0 added the ability to set a custom base path for the OpenAI API. Read in order, that is a project tracking model releases and then adding the one feature needed to point at a proxy or gateway, and then stopping.

The last commit to the repository is dated 2026-04-24, which is more recent than the last release by a wide margin. That gap is normal for a small tool and it means the default branch may contain work that has never shipped to npm. If you install the package you get the May 2024 code; if you clone and build you get whatever is on main. For a tool whose output writes to your source files, that distinction decides whether you read the code first.

The repository also carries a .gitpod.yml and a .github directory, so there is a browser based development environment and CI configuration in the tree. The topics list is telling about intent as well, covering ai, chatgpt, cli, codegen, coding-assistant, gpt-4, gpt-4o, prompt-engineering, prompt-toolkit and prompt-tuning, which places the project in the prompt engineering conversation rather than in the assistant framework conversation.

Editorial conclusion

Promptr is worth a look if you like keeping prompts in version control and reviewing the result as a diff. The design is honest about that: a dry run flag, an explicit apply flag, and a workflow where you commit before you run. Two things to weigh first. The runtime is pinned to openai 3.3.0, a major version from before the current SDK line, while the documented default model is gpt-4o, so the gap between the model names in the docs and the client library the tool actually loads is wider than the version number suggests. And the last tagged release is 6.1.0 from May 2024, with the most recent push to the repository dated 2026-04-24, which means the package on npm is old enough that you should read the source before trusting it with a branch you care about.

Frequently asked questions

Official sources

1. ferrislucas/promptr on GitHub
2. Issues
3. License: MIT
4. README
5. Releases