Why I built huu: orchestrating agents with human methods, not more prompts

Why I stopped trusting well-written prompts

Estimated reading time: 4 min

The last straw was an audit at the company. The tech tower needed a morale boost, and morale in practice meant tested code, multiple projects, tight deadlines, high trust. I did what everyone does: threw a huge task at Claude Code and trusted the well-written prompt.

It didn't work. I learned a few things along the way.

1 - No matter how much you refine the prompt, the agent tends to hallucinate as the amount of work increases. 2 - Automatic orchestration doesn't give you human control: everything ends up bounded by the AI, not by you. 3 - Claude Code, while satisfactory, is expensive, and the agent will always stop before finishing a huge task, even if it's just to ask to continue. 4 - Writing tests in legacy code is as simple as it is time-consuming. 5 - Managing multiple prompts in parallel gives you mental exhaustion that pulls you away from the task. 6 - Even the simplest LLMs return incredible results on small, closed-scope tasks.

The personal number: before, I'd burn through the weekly subscription budget. Today I spend about five reais to generate tests for a 200+ file project.

The problem was never the model. It was the lack of method. That's where huu was born.

What huu is

huu (Humans Underwrite Undertakings, "humanos subscrevem empreitadas") is an agent orchestrator where the method is yours and the intelligence belongs to the model. You write a JSON pipeline listing the steps and files; it becomes N parallel agents, one per file, each in its own isolated git worktree, merged at each stage with git merge --no-ff in fixed order, all inside Docker so the agent never sees your credentials.

The focus is auditing, test generation, and knowledge extraction. Feature work, "fix this bug", that's not what it's for. In the repo's GIF you can see a real run: 55 minutes generating a test suite (100% line coverage in that run, no guarantees yours will hit that number).

Installation

You need Node.js 20+, git, and Docker. Docker is mandatory, not optional: huu only runs inside containers, so your shell credentials stay out. And an OPENROUTER_API_KEY, which is how the models get in. I tested everything here with npm version 5.2.0.

bash

export OPENROUTER_API_KEY=sk-or-...  # key from openrouter.ai/keys
npm install -g huu-pipe              # installs the CLI globally
huu                                  # opens the web UI and re-executes in the container

Running huu brings up the interface at http://localhost:4888 and drops the default pipelines into ./pipelines/. If you prefer the terminal, use huu --cli.

In practice: giant task becomes N small tasks

The usual way to do this is to open Claude Code and say: "write tests for the whole project". I did that. Many times. The agent starts well on the first few files, then the context degrades, it hallucinates as the amount of work increases, and it always ends before finishing, even if it's just to ask to continue.

The huu way is different. The huu Test Suite pipeline first does a recon that discovers the test-worthy files on its own, without you pointing out anything. Then a step with scope per-file does the fan-out:

json

// pipelines/meu.pipeline.json
{
  "name": "Write tests for $file",
  "prompt": "Write unit tests for $file following huu-tests.md.",
  "files": [],
  "scope": "per-file"
}

Same prompt for everyone, only $file changes. Thirty agents in parallel, each with a single mission of closed scope. At the end, a judge runs the suite and sends it back for rework if it doesn't pass.

It works for a simple reason: each agent gets a small task of closed scope, which is exactly where even the simplest LLMs deliver incredible results.

When to use (and when not to)

The rule of thumb is one sentence: if each step requires an open-ended design decision, it's not a job for huu; if the method is known and you just need to execute it rigorously, that's exactly its job.

It's good for auditing, test generation, knowledge extraction, bulk mechanical migration. Like migrating 40 tests from Mocha to Vitest: the prompt is identical across the 40 files, only the $file changes. It's no good for "fix this bug" or "build this feature". Open-ended work calls for an interactive agent, and writing a pipeline for that is pure overhead.

The concrete impact: today I spend about five reais to test a 200-file project. Before, I'd burn through my entire weekly Claude Code budget.

Cautions

Before you go running it in critical production, some honest caveats.

huu is a young project, essentially a single-author effort, with development heavily assisted by AI. It has over 1,100 tests in Vitest, but no automated CI: running typecheck and tests before committing is a contributor convention, not a gate. Evaluate it like you would any new one-person tool.

Deterministic is the method, not the result. Two runs of the same pipeline produce different diffs, and merge conflicts fall to an LLM resolver, by design. And line coverage only proves the code ran, not that the assertions would catch a bug: treat 100% as a starting point, not proof.

Finally, Docker is mandatory (the old --no-docker and --yolo flags have been removed), and the cost of the merge and judge steps still isn't included in the reported total.

The invitation

The next step is simple: install and run the huu Test Suite on one of your projects, or open http://localhost:4888/simulation to see everything work without any API key and zero cost. Zero risk.

But honestly, what I really want to leave you with is this thought: rethink how we use AI day to day, because it's getting expensive. Use whatever tool you want. The thesis: the method is yours, the intelligence is the model's.

If you found it helpful, a star on github.com/frederico-kluser/huu is welcome, and new pipelines and issues too. And send this post to your team on Slack or WhatsApp, especially to whoever controls the budget.