Htvag Agent

Docs

How Htvag Agent actually works, and how to get the most out of it.

Getting started

  1. Download and install the desktop app from the download page. Windows and Linux are supported today.
  2. Sign in. The app opens your browser at this site, you approve the request, and you're signed in automatically — nothing to copy or paste.
  3. Open a folder. Point it at any repository on your machine. The agent is confined to that folder for the whole session — it cannot read or write anything outside it.
  4. Describe the outcome, not the steps. "Add rate limiting to the login route" works better than a list of instructions — it plans its own steps, and re-plans when something doesn't go as expected.

From the terminal instead

The same agent runs as a CLI if you would rather stay in a shell. It needs Node 20 or later and works in any terminal on macOS and Linux, or in WSL or PowerShell on Windows:

npm install -g htvag-agent
htvag login
htvag                     # interactive, in the current folder
htvag -p "fix the failing test"   # run once and exit

It shares your account, sign-in and daily credits with the desktop app. The only difference is that it works in the folder you launch it from rather than one you pick in a dialog.

How the agent works

Most coding assistants generate a suggestion and hand it back to you. This one keeps a loop running: plan, edit, run, check the result, fix what's wrong, repeat — until the thing you asked for is actually built and verified, not just described.

The completion gate

Before a turn is allowed to end, a check runs over what actually happened: is anything on the todo list still open? Were files edited without ever being run or tested? Does the reply defer work back to you ("next, you should…") instead of doing it? Any of those push the agent to keep going instead of stopping. This is the main thing that separates it from a chat-only assistant — it isn't allowed to call something done that it hasn't verified.

Real tools, not a sandboxed toy

It reads and edits files directly, greps and globs your actual repo, and runs commands in a persistent shell — the same primitives a human engineer uses, with the same working directory and environment carrying over between commands.

Skills

Skills are reusable playbooks the agent can pull into context for a specific kind of task — the same idea behind this tool's own skill system. Instead of improvising an approach every time, it loads a written-out, better approach for tasks that match one.

Both the desktop app and the CLI ship with a few built in:

  • code-review — reviews a diff for correctness bugs and unnecessary complexity before calling a change done.
  • debug-build-error — a systematic process for tracking down a failing build or test instead of guessing at fixes.
  • add-auth — a session-based email/password auth implementation, end to end.
  • deploy-checklist — pre-deploy checks: env vars actually set on the host, database migrations, persistent-storage traps on serverless platforms.

Writing your own

Any project can add its own by creating .htvag/skills/<name>/SKILL.md inside the repo — a short frontmatter header with a name and one-line description, followed by the instructions in the body:

---
name: my-skill
description: When the agent should reach for this.
---

The actual instructions go here — as specific and concrete
as you'd write for a colleague joining the project.

A project's own skill overrides a built-in one of the same name, so you can also use this to sharpen a default for how your codebase specifically wants something done.

Choosing which ones are on

In the desktop app, the ⌗ button in the sidebar opens the skills panel: switch each one on or off, read its full instructions before you trust it, and add a skill folder from anywhere on disk. A skill you add there applies in every project, not just the open one.

Switching a skill off is not cosmetic — it is filtered out before the agent's prompt is built, so it stops costing tokens and the agent cannot load it. From the CLI the same controls are htvag skills, htvag skills disable <name> and htvag skills enable <name>.

Daily credits

Every signed-in account gets 5 credits to start, reset at 00:00 UTC — nothing to configure, no key to find. Credits only count genuinely new work per turn: the parts of a session that repeat (system instructions, tool definitions, earlier turns) are served from cache and don't eat into your balance the way resending the whole conversation would.

Beyond that, credits accumulate while you work. Ad slots sit beside the workspace and refresh as you go; each one that loads pays back half of what it actually earned, converted to tokens — up to 15 a day. The grant follows real ad rates rather than a number we picked, so there is nothing to claim and nothing to watch on purpose.

Running it without credits

Credits are the default because they need no setup, but they are not the only way to run the agent. There are three engines, and you can switch between them at any time — in the desktop app under Model, or from the CLI.

Your own machine, with Ollama

Point the agent at a model running locally through Ollama. Nothing leaves your computer, no account is needed, it works offline, and it costs no credits at all — the only limit is your hardware.

ollama pull qwen2.5-coder:7b   # a small model that reliably calls tools
htvag local on                 # switch the agent onto it
htvag local off                # back to the cloud

Two things are worth knowing before you rely on it. A 7B model is meaningfully weaker than the hosted one — it holds a short task together well and loses the thread on a long refactor — so the agent runs a leaner prompt and a smaller tool set locally to fit the model's context. And Ollama defaults to a 4,096-token window — smaller than the agent's own instructions — and silently drops anything past it, which looks like the agent forgetting what it was doing. The agent asks for a larger window on every request instead; raise or lower it to suit your RAM:

htvag local ctx 32768

Your own API key

If you already pay a model provider, use that key directly. Requests go straight to them and are billed on your account, so your daily credits are never touched.

htvag key set mimo <your-key>
htvag key rm mimo              # back to the included credits

In the desktop app the same three choices live behind the Model button, with the local models you have pulled listed for you. Keys are stored in your OS keychain where one is available.

Connecting it to your other tools

The agent can already drive anything with a command line — it has a real shell. These three cover everything else, and each one is a file you can commit so a whole team gets it.

MCP servers

Model Context Protocol servers give the agent reach into systems that have no CLI: an issue tracker, an error monitor, a database, a design tool. Each connected server's tools appear in the loop as mcp__<server>__<tool>, and the agent uses them exactly like its built-in ones.

htvag mcp add linear npx -y mcp-remote https://mcp.linear.app/sse
htvag mcp                      # what is configured, and whether it connects

Configuration lives in ~/.freeai/mcp.json, or .mcp.json in a project so the repo carries it. The format is the same one Claude Code uses, so a server config from anywhere else works unchanged. A server that fails to start is reported and skipped — it never takes the session down with it.

Your own commands

A prompt you keep retyping becomes a command. Drop a markdown file in ~/.freeai/commands/ — or .htvag/commands/ in a repo — and its filename becomes the command. deploy.md gives you /deploy, and $ARGUMENTS in the body picks up whatever you type after it.

Hooks

Hooks are for the rules that must hold every time rather than most of the time. A shell command in .htvag/hooks.json runs before a tool, after a tool, or when the agent thinks it's finished — and a non-zero exit means something. A PreToolUse hook that fails blocks the tool outright; a Stop hook that fails sends the agent back to work instead of letting it finish.

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "write_file|edit_file", "command": "npx prettier --write $HTVAG_TOOL_PATH" }
    ],
    "Stop": [{ "command": "npm test" }]
  }
}

That last line is the useful one: with it, the agent cannot call a task done while the test suite is red — not because it was asked nicely, but because the harness checks.

Screenshots, rules and picking up where you left off

Build from a design, and check it against the design

Attach a screenshot or mockup and the agent builds from what it can see rather than from your description of it. In the desktop app, paste or drag the image straight into the composer; from the terminal:

htvag -i mockup.png "build this page"
/image shot.png                # or mid-conversation

What happens next is the part that matters. The agent runs the page in a real browser, screenshots its own work, and looks at that screenshot beside your design — comparing layout, spacing, type scale, colour and radii, naming what is off, fixing those specific things, and rendering again. It keeps going until the difference is down to what the reference cannot tell it.

This is enforced, not encouraged: if you attached a design and the agent tries to finish without ever looking at what it rendered, the run is sent back to work. "It compiles" and "it looks like the design" are unrelated claims, and only one of them was asked for.

Permission rules

The five permission modes are a single dial for the whole session, which means letting the agent run your tests unattended also means letting it run anything else. Rules are per call:

// .htvag/permissions.json — commit it, and the whole team gets it
{
  "permissions": {
    "allow": ["bash(npm test*)", "bash(npm run build*)", "read_file"],
    "ask":   ["bash(git push*)"],
    "deny":  ["write_file(*.env*)", "bash(rm -rf*)"]
  }
}

Precedence is deny, then ask, then allow — and a deny holds even in Bypass mode, because a rule that a flag can overrule is not worth writing. Patterns are matched against the command for bash and against the path for file tools.

Carry on tomorrow

The terminal keeps its transcripts, scoped to the folder the work happened in — so htvag --continue in a repo resumes that repo's conversation, not whatever you typed last somewhere else.

htvag --continue     # the last chat in this folder
htvag --resume <id>  # a specific one; /sessions lists them

Creator program

If you have an Instagram following, you can link your account from the desktop app and get a referral link. Anyone who signs up through it and watches reward videos earns you 30% of that ad revenue, calculated monthly and paid by direct UPI transfer. Set it up from the creator page — no minimum follower count.

Troubleshooting

Windows warns the installer is untrusted

"Windows protected your PC" is Microsoft SmartScreen flagging any app it hasn't seen many downloads of yet — it isn't specific to this app. Click More info, then Run anyway.

Sign-in doesn't come back to the app

Make sure the browser window that opened actually finished the approval step — if it's stuck on a blank tab, close it and click Sign in again from the app.

"Daily limit reached"

Leave the app open — the ad slots keep earning credits as they refresh — or wait for the reset at 00:00 UTC.

Something else? Get in touch.