Hero Code

A coding agent that runs on any model, paid per call in $HERO.

It reads your repository, edits files, and runs your tests, from a terminal. What is different is the model layer: it talks to Hero Run, so the same session can run on GPT-OSS, Kimi K3, Claude, DeepSeek, Llama or ~375 others, or on auto, which picks the best value for the job. One key, one balance, no per-provider signups.

export HERO_RUN_KEY=hr_live_...        # mint at https://herorunai.com/keys
npx hero-code                          # interactive, in the current directory
npx hero-code "why is the auth test failing?"

Options

-m, --model <id>      model id, or auto | cheapest | fastest   (default: auto)
    --max-tokens <n>  answer budget per step (default: 4096)
    --yes             do not ask before writing files or running commands
    --base <url>      API root (default: https://herorunai.com/v1)
    --list-models     print every available model

You pay for the token budget you ask for, so --max-tokens is a real dial: raise it for long refactors, lower it for quick questions. Every turn prints what it cost.

What it can do

| tool | asks first? | |---|---| | read_file, list_files, search | no, reading is safe | | write_file, edit_file | yes | | run_command | yes |

Anything that writes or executes asks for confirmation. --yes turns that off. It is opt-in and never the default, because an agent that can rewrite a repository unattended should be a decision rather than a surprise.

Every path is resolved and must stay inside the directory you started in. A relative path that climbs above that root is refused rather than read. (Known limit: a symlink inside the tree that points outside it will still resolve outward. Do not run this in a directory with symlinks you do not trust.)

edit_file replaces an exact string that must appear once. Line numbers go stale the moment anything above them shifts, and fuzzy matching edits the wrong code silently, so requiring a unique string fails loudly instead.

When a reply stops because it ran out of token budget rather than because the model was done, the run says so. A half-answer that looks complete is worse than no answer.

In the browser

hero-code --web            # http://127.0.0.1:4141

The page is only the chat surface. Your key, the tools and the agent loop stay in the terminal process, because a browser cannot read your files or run your tests. Writes and commands still ask, as Approve and Deny buttons rather than a y/N prompt, and the listener is bound to loopback because anything that can reach it can run commands on your machine.

Runtime

Runs on Node 20+ or Bun, unmodified. It only uses node: builtins and fetch.

Bun starts in about 19 ms against Node's 54 ms. Across a session dominated by model latency measured in seconds, that gap is noise, so the reason to reach for Bun is distribution: it compiles to one executable with no runtime to install.

bun build src/cli.mjs --compile --outfile hero-code
./hero-code --help

Building on it

The agent loop is about 50 lines in src/agent.mjs and contains no HTTP at all. It is built on hero-run-ai, the Hero Run SDK, which speaks OpenAI-style tool calling against any model in the catalog. Replace the toolset in src/tools.mjs and you have a different agent on the same loop.

Licence

MIT.