DEV Community: Wassim AZI

A live-preview terminal UI in plain Node.js, with zero dependencies

Wassim AZI — Fri, 30 Oct 2026 11:00:00 +0000

In Google's Antigravity CLI (agy), the /statusline command turns the status bar on or off, and that's it. People expect more: a way to change what the bar shows without writing a custom shell script. Configuring a statusline by hand usually means wrestling with an undocumented JSON schema. You edit a property, save, switch windows, inspect the bar, and go back to edit again.

When building agy-powerline, I wanted the terminal customization experience to feel like Powerlevel10k for Google Antigravity: one command that opens an interactive configurator with a live preview of your bar, where you browse presets, toggle widgets, and audition themes with arrow keys, with the preview following every change.

The project has a hard rule: zero runtime dependencies. No Ink, no blessed, no chalk. Partly for supply-chain reasons (people run it with npx, and it touches their dev configuration), partly because every module it doesn't load is start-up time it doesn't pay. So the interactive TUI is built on Node's standard library and a handful of raw ANSI escape codes. Here's how it works, and what I'd do the same way again.

The primitives: raw mode, keypresses, the alternate screen

Everything starts with four calls:

const readline = require("readline");

readline.emitKeypressEvents(process.stdin);
process.stdin.setRawMode(true);
process.stdin.resume();
process.stdin.on("keypress", onKey);

emitKeypressEvents parses the raw bytes into events like { name: "up" } or { name: "c", ctrl: true }, so arrow keys, Enter, Escape and letters all arrive in one handler.

Then the editor switches to the terminal's alternate screen and hides the cursor, so it doesn't scroll away your shell history:

const CSI = "\x1b[";
process.stdout.write(`${CSI}?1049h${CSI}?25l`); // alternate screen, hide cursor

The most important part is the way out. In raw mode, Ctrl+C is just a key, so the key handler treats it as quit. SIGINT and SIGTERM get the same handler. Quitting always does the same three things: save, leave raw mode, and restore the screen.

function quit() {
  if (exiting) return;
  exiting = true;
  persist();
  process.stdin.setRawMode?.(false);
  process.stdout.write(`${CSI}?25h${CSI}?1049l`); // show cursor, main screen
  process.exit(0);
}

A TUI that leaves your terminal in raw mode with no cursor is a TUI people uninstall.

Redraw everything, every time

There's no diffing and no virtual DOM. On every keypress, the editor builds the whole frame as an array of strings, moves the cursor home, clears to the end of the screen, and writes the frame:

function draw() {
  process.stdout.write(`${CSI}H${CSI}J` + frameLines().join("\n") + "\n");
}

process.stdout.on("resize", draw);

For an editor that only redraws when you press a key, this is fast enough, and it's very simple to reason about: there's no previous state to get out of sync with. If it ever becomes a problem, writing only the lines that changed would be the next step.

The frame is a pure function, so it's testable

Because draw() only writes what frameLines() returns, the interesting part is a function of state and window size. The module exports a renderFrame() for tests that sets the state, pins the size and the color depth, and returns the frame as a string:

const frame = renderFrame({
  config: defaultConfig(),
  screen: "layout",
  cursor: 1,
  columns: 200,
});

That makes a terminal UI testable like any other output. One test, for example, checks that each layout's description in the details panel is exactly three lines under 90 columns, separated by blank lines. Another draws every screen at seven window sizes, from 60×16 to 220×50, in Unicode and ASCII mode, and checks that no frame is wider or taller than its window. No pseudo-terminal, no screenshots, no timing.

The preview is the real renderer

The live preview isn't a mock of the bar. It calls the same renderStatusline() function the installed statusline runs on every refresh in agy, with sample session data and a terminal width set to the preview panel's width:

previewData.terminal_width = width - 4;
const rendered = renderStatusline(previewData, previewConfig(), { color: getActiveDepth() });

So the preview fits, drops widgets and cuts lines exactly the way the real bar will in a terminal that wide. If it looks right in the editor, it looks right in agy.

With no dependencies, the same modules also run in a browser. The web configurator bundles the runtime's own CommonJS modules into the page, so its preview comes from the same renderer as the bar in your terminal.

Hovering is a preview, not a change. Moving the cursor over a theme, a preset or a layout redraws the preview with it, and the preview's title says so (preview, enter to apply). Enter applies it; moving away leaves your setup as it was.

One safety detail: the bar has an exec widget that runs a shell command you configure. The preview never runs it, and shows [cmd] instead. Scrolling through your config shouldn't execute anything.

Responsive, in a terminal

A terminal can be 80 columns or 200, and 20 rows or 60. The editor changes shape at two widths:

From 80 columns, the descriptions line up in their own column.
From 140 columns, the list gets a details panel next to it: the selected widget drawn on its own with its options, a preset's rows, or a theme's colors.

Height is handled the other way around. When the window is short, the editor gives things up one step at a time: first the tagline, then the blank lines between panels, then the notes, then the preview's toggles. That way the list keeps at least six rows. A list longer than its panel scrolls, and the scroll position is kept between frames, so the list only moves when the cursor leaves the visible part.

Counting columns is harder than it looks

Every box, panel and padding depends on one function: how many columns a string takes on screen. string.length is wrong in several ways:

Escape sequences (colors, hyperlinks) take no columns, so strip them first.
Most emoji and CJK characters take two.
Combining marks, zero-width joiners, variation selectors and skin-tone modifiers take none.

And terminals don't always agree. When I recorded the demo GIF with VHS, one emoji (🪙) was drawn one column wide, while the width count says two. Everything after it on that row moved over by one column. There's no perfect answer: you pick the width most terminals use and accept the odd exception.

Colors for every terminal

The editor and the bar detect the color depth: truecolor, 256 colors, or none (NO_COLOR is respected). In 256-color mode each color maps to the nearest one in the terminal's palette. Getting that right needed care: an early version turned near-black text into navy blue. There's also an ASCII mode for terminals without a Nerd Font, and a test checks that every screen draws in plain ASCII when it's on.

Every theme is also checked in the test suite: WCAG AA contrast (4.5:1 minimum ratio) for text on each pill and for each color on the terminal background. For the colorblind-* themes, the tests simulate protanopia, deuteranopia and tritanopia to mathematically guarantee that caution and danger states remain distinguishable.

Recording the demo

The GIF at the top is recorded from a script with VHS, so it can be re-recorded after each change. The tape starts the editor with a demo config in a temporary folder, so recording it never touches my real settings, and drives it with keypresses: add a widget by typing its name, browse a few presets, themes and layouts, open the last tab.

What I'd do differently

The editor is one file of about 2,100 lines. That was fine while the design was moving, but it's time to split it into one module per screen. Everything else (raw mode, full redraws, a pure frame function, the real renderer as the preview) I'd do the same way again.

If you're building a small CLI and think you need a heavy TUI framework, try readline and a few escape codes first. You may not need anything else.

To test the editor yourself:

npx agy-powerline configure

Or test all 16 themes, 3 layouts, and custom meter styles right in your browser with the web configurator.

🤖 One-shot install with Antigravity:

Hey agy, please install agy-powerline by running `npx agy-powerline init --yes`, then tell me to restart agy.

The code is MIT: wassim-azi/agy-powerline, in src/cli/configure.js and src/cli/tui-style.js. Questions and suggestions are welcome in the comments.

Building a statusline for Google's Antigravity CLI that doesn't break on Windows

Wassim AZI — Wed, 28 Oct 2026 11:00:00 +0000

A statusline sounds like a weekend project. Read some JSON, print one colored line, done.

Then you run it on Windows.

I built agy-powerline, a statusline for Google's Antigravity CLI (agy). It's plain Node with no dependencies, and it runs on Windows, macOS, Linux and WSL. Most of the work wasn't drawing the bar. It was making sure the bar starts, every time, on every machine, and never takes the session down with it. Here's what I ran into.

How agy runs a statusline

You give agy a command in its settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "C:/Users/you/.agy-powerline/statusline.cmd"
  }
}

Whenever its state changes, agy starts that command, writes a JSON payload to its stdin (model, quotas, context window, terminal width and more), and shows what it prints.

The official docs explain the payload and show a bash script you chmod +x. They don't say how the command is started on each OS, how long it may take, or what happens when it fails. Everything below I found by testing.

Two details matter a lot:

On Windows, agy runs the command through cmd /c. On macOS and Linux, through sh -c.
It runs all the time. Anything slow, fragile or noisy shows up right away.

Trap 1: quotes that cmd doesn't understand

The obvious Windows command is "C:\Program Files\nodejs\node.exe" "C:\Users\you\...\statusline.js". It doesn't work.

agy is written in Go, and Go's os/exec escapes embedded double quotes as \" when it builds the Windows command line. That's the C runtime's convention, but cmd doesn't follow it: it keeps the backslash and the quote as part of the program name, and can't find node.exe.

So the setting holds no quotes at all. It points at a small launcher, written with forward slashes:

@echo off
setlocal DisableDelayedExpansion
"C:\Program Files\nodejs\node.exe" "%~dp0statusline.js"

The quoting now happens inside the batch file, where cmd handles it the normal way. A few details:

%~dp0 is the launcher's own folder, so the script path is never written twice.
A % in the Node path is written as %%, or cmd would read it as a variable.
DisableDelayedExpansion keeps a ! in a path from being expanded.

cmd also splits a command line at &, (, ^, ,, ; and =. A launcher in a folder whose path contains one of them never starts, so init refuses such a folder and says how to pick another (AGY_POWERLINE_HOME). An error at install time beats a bar that silently never appears.

Trap 2: the right Node, the right shell quoting

On macOS and Linux the command is sh -c, so the paths are single-quoted, which keeps spaces and $ intact:

'/opt/homebrew/bin/node' '/Users/you/.agy-powerline/statusline.js'

The Node path is process.execPath, the binary that ran init, not node from the PATH. agy may not start with your shell's PATH (with nvm, for example), so a bare node can resolve to nothing, or to an old system Node.

WSL had its own version of this. Windows' npx is often on the WSL PATH through /mnt/c/..., and running init with it would write a Windows Node path into Linux settings. init and doctor detect a Windows Node under WSL and refuse to continue.

Trap 3: the invisible BOM

Windows PowerShell 5.1 writes UTF-8 files with a byte order mark when you ask for UTF-8 (Set-Content -Encoding UTF8, Out-File). JSON.parse doesn't skip it:

JSON.parse("\uFEFF{}"); // SyntaxError

So anything that reads JSON strips it first: agy's settings.json, the bar's config, imported configs, and the payload on stdin.

const text = fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "");

One line, but missing it means a config the user edited in the wrong editor breaks the bar for no visible reason.

Trap 4: a stdin that never closes

This one took a while to find. Sometimes agy starts the statusline and keeps its stdin open without writing anything (at the time of writing it's open as google-antigravity/antigravity-cli#698). A script that does a blocking read of stdin waits until agy kills it. After a few kills in a row, agy turns the custom statusline off.

The fix on the script side: read stdin asynchronously, with a deadline.

function readStdin(timeoutMs) {
  return new Promise((resolve) => {
    const chunks = [];
    let done = false;
    const finish = (complete) => {
      if (done) return;
      done = true;
      clearTimeout(timer);
      // An open stdin would keep the process alive after the bar is printed.
      process.stdin.destroy();
      resolve({ text: Buffer.concat(chunks).toString("utf8"), complete });
    };
    const timer = setTimeout(() => finish(false), timeoutMs);
    process.stdin.on("data", (chunk) => chunks.push(chunk));
    process.stdin.on("end", () => finish(true));
    process.stdin.on("error", () => finish(true));
  });
}

With a 1-second deadline: if stdin closed, render it. If it didn't and nothing arrived, exit 0 with no output. The script is never killed, so it's never counted as a failure.

Trap 5: never crash where the bar goes

Whatever the statusline prints ends up in the status bar. A stack trace there is ugly at best, and can quote payload text at worst. So the runtime has a few hard rules:

An uncaught error prints a short fixed marker ([agy-powerline: error, see agy-powerline.log]), writes the details to a local log, and exits 0.
Invalid JSON prints [agy-powerline: invalid JSON] and says where it broke, without quoting the input.
When agy closes the pipe before the bar is written (EPIPE), that's a normal shutdown, not a crash: exit quietly.
Text that isn't ours (branch names, the conversation title, command output) is stripped of terminal escape sequences before it's printed.
The payload holds personal data: your email address, the conversation ID and the path to the transcript. None of it is printed, logged or written to the debug dumps users attach to bug reports.

Start-up time is most of the cost

A statusline is a new process on every refresh, so start-up time matters more than the rendering. On a Windows 11 laptop, agy-powerline's own work is about 0.1 s per refresh. Starting cmd and Node adds about 0.1 to 0.25 s, depending on how busy the machine is.

Two things made a measurable difference:

One file instead of eighteen. On Windows, Node spent more time opening the 18 small module files than running them. init now joins the runtime into a single statusline.js (each file still gets its own scope, the way Node wraps modules). That cut agy-powerline's share of each refresh by about a third.
No git process unless needed. The branch and dirty state come from reading .git directly. The ahead/behind counts need git rev-list (about 60 ms on Windows), so they're cached per pair of commits and recomputed only when the branch or its upstream moves, with a 150 ms timeout.

Fitting any terminal width

The payload includes terminal_width, and the bar has to fit it. When a row is too wide, it shrinks in steps:

Widgets drop their labels and keep only their values, then the model name and the meters get shorter.
Widgets drop out by priority (a custom badge goes before the conversation title, the title before the quotas, the model last).
As a last resort, the row is cut with ….

Measuring "too wide" is its own small problem. You strip escape sequences first, then count columns: emoji are two wide, combining marks and variation selectors are zero. And terminals don't always agree with each other on emoji width, so a little slack helps.

Never lose the user's settings

init edits a file that belongs to another program, so it's careful about it:

It refuses to touch a settings.json that isn't plain JSON (comments, trailing commas), and tells you what to add by hand.
It backs up the file before every change, and keeps the very first version in a separate backup that's never replaced (settings.json.agy-powerline.original.bak).
It only changes the statusLine key.
A settings.json symlinked by a dotfile manager (stow, chezmoi, yadm) stays a link: the change goes into the file it points to.
uninstall backs the file up too and removes only the statusLine key. uninstall --delete also deletes agy-powerline's files, but only the ones in a fixed list (INSTALLED_FILES), never a whole folder.

How it's tested

CI runs on Windows, macOS and Linux, across Node 20, 22 and 24.
On the Windows runner, a smoke test runs init in a home folder with a space in its path, then starts the command it wrote through a real cmd.exe /d /c, the way agy does. It fails on a non-zero exit code, on anything written to stderr, or if the bar didn't render.
Snapshot tests pin the rendered bar for each layout and fixture payload, with the clock, time zone and terminal width frozen.
Property-based tests with fast-check (a fixed seed, 300 runs per property) throw random and malformed payloads at the renderer: it must never throw, print no control characters besides its own colors, and fit every row into widths from 40 to 240 columns. Another one pipes random input into the runtime script, which must exit 0 without a stack trace.

What I'd tell someone writing a statusline

Test on Windows on day one. Most of these traps don't exist on macOS.
Read stdin with a deadline.
Exit 0, always. Print nothing rather than an error.
Measure start-up, not just rendering.
Kill what you start. A timeout that stops waiting for a child process doesn't always stop the process: on Windows, a command run through cmd can outlive its timeout. Kill the whole process tree. (That one is still on my own list, for the bar's shell-command widget.)
Treat the payload as untrusted text, and keep its personal fields out of your logs.
Never start agy itself, or anything slow, from the statusline. One user on Google's forum pointed it at agy and ended up with about 1,000 agy.exe processes.

The code is MIT on GitHub: wassim-azi/agy-powerline. If you want to try it out on Windows, macOS, or Linux, you can install it manually:

npx agy-powerline init

Or have your agent install it directly in an open agy session:

"Hey agy, please install agy-powerline by running npx agy-powerline init --yes, then tell me to restart agy."

If you've hit other Windows traps with Node CLIs, I'd like to hear about them in the comments.

What Antigravity CLI actually sends to your statusline script (field by field)

Wassim AZI — Tue, 27 Oct 2026 12:00:00 +0000

If you write your own statusline for Google's Antigravity CLI (agy), you start from the official docs: agy runs your command when its state changes, pipes a JSON payload to its stdin, and shows what the command prints.

The docs list the payload's fields. But when I captured real payloads for agy-powerline, they didn't quite match: some documented fields never showed up, a few useful ones arrived without being documented, and the quota buckets, the part most people want, aren't listed at all.

This is the payload as it actually arrived, captured from agy 1.3.0 to 1.4.0 on a Google AI Pro account, in October 2026. Your plan, version and OS may differ: treat every field as optional.

A real payload

Trimmed, with personal values replaced:

{
  "cwd": "/home/user/project",
  "session_id": "00000000-0000-0000-0000-000000000000",
  "conversation_id": "00000000-0000-0000-0000-000000000000",
  "conversation_title": "hello",
  "transcript_path": "/home/user/.gemini/antigravity-cli/conversations/…",
  "model": {
    "id": "Gemini 3.8 Flash (High)",
    "display_name": "Gemini 3.8 Flash (High)",
    "effort": "high"
  },
  "workspace": { "current_dir": "/home/user/project", "project_dir": "/home/user/project" },
  "version": "1.3.3",
  "context_window": {
    "total_input_tokens": 33129,
    "total_output_tokens": 10161,
    "context_window_size": 1048576,
    "used_percentage": 3.159,
    "remaining_percentage": 96.841,
    "current_usage": {
      "input_tokens": 3353,
      "output_tokens": 187,
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 24680
    }
  },
  "exceeds_200k_tokens": false,
  "product": "antigravity",
  "quota": {
    "gemini-5h": { "remaining_fraction": 0.987, "reset_time": "2026-10-13T00:36:57Z", "reset_in_seconds": 15752 }
  },
  "agent_state": "idle",
  "vcs": { "type": "git" },
  "cycle_mode": "accept-edits",
  "sandbox": { "enabled": false },
  "subagents": [{ "name": "research", "role": "List the files in the project folder.", "status": "completed" }],
  "plan_tier": "Google AI Pro",
  "email": "user@example.com",
  "terminal_width": 198,
  "vim": { "mode": "NORMAL" }
}

The quota buckets

quota is an object keyed by bucket. The docs' example shows only gemini-weekly. Here's every bucket I've seen:

Bucket	What it is	Window
`gemini-5h`	Gemini models	5 hours
`gemini-weekly`	Gemini models	7 days
`3p-5h`	Third-party models (Claude, GPT)	5 hours
`3p-weekly`	Third-party models	7 days
`gemini-argon-wtu-weekly`	Gemini 4 Argon's own quota, on Google AI Pro (since mid-October 2026)	7 days

Each bucket has:

remaining_fraction: from 0 to 1. Multiply by 100 for "percent left".
reset_time: an ISO timestamp. Both …T00:36:57Z and …T00:36:57.000Z show up, depending on the version, so parse it with Date.parse() rather than a regex.
reset_in_seconds: optional according to the docs. If it's missing, compute it from reset_time.
Sometimes "disabled": true. I skip those buckets.

A few things worth knowing:

The Argon bucket arrives whatever model you're using, not only when Argon is selected. To show "the quota that matters right now", pick the bucket group from model.id: Argon models → the Argon bucket, other Gemini models → gemini-*, everything else → 3p-*.
How far into the window you are needs no extra field: 1 - reset_in_seconds / window_length, with 18,000 s for 5-hour buckets and 604,800 s for 7-day ones. Compare it with the share you've used, and you know if you're ahead of or behind pace.
The values come from agy, as of its last refresh. A statusline can't be more up to date than the payload.

Fields that arrive but aren't documented

Field	Seen as	Notes
`cycle_mode`	`"accept-edits"`	The approval mode. Missing from some captures, so treat "absent" as the default mode. The docs list `execution_mode` instead, which I've never seen.
`subagents`	`[{ name, role, status }]`	`status` was `"running"` or `"completed"`. `role` is a whole sentence (the task you gave it), so cut it before printing.
`conversation_title`	`"hello"`	Appears once the conversation has a title.
`model.effort`	`"high"`	The reasoning effort.

Fields that are documented but never showed up

On my machine, with a Google AI Pro account, these never appeared:

execution_mode (see cycle_mode above).
pending_input_count, even with a prompt queued.
tool_confirmation_pending.
vcs.branch, vcs.client and vcs.dirty: vcs only ever held type (see antigravity-cli#739). Starting git on every refresh is slow on Windows (an ahead/behind count alone took about 60 ms), so read the branch from .git/HEAD yourself and cache anything that needs git.
sandbox.allow_network: only enabled arrived.

If your script depends on one of these, give it a fallback.

Gotchas

model.id isn't an API id. It held the same text as display_name, effort included: "Gemini 3.8 Flash (High)". Match on substrings (includes("argon")), not on exact ids.
used_percentage counts input, not output. In every real capture it equals total_input_tokens / context_window_size (33,129 / 1,048,576 = 3.159% above). total_output_tokens isn't in it. If you add output tokens to your token count, the count stops matching agy's own percentage, so show the input count, or work the count out from the percentage.
exceeds_200k_tokens can be null before the first request, according to the docs.
agent_state takes idle, thinking, working, tool_use or initializing, per the docs. I've seen idle, working and tool_use.
terminal_width is the live width. Use it to fit your output: a line wider than the terminal wraps and pushes the bar out of place.
vim appears only with Vim mode on, with mode set to NORMAL, INSERT and so on.

The cache numbers

context_window holds totals for the whole session, and current_usage the numbers for the latest request:

"current_usage": {
  "input_tokens": 3353,
  "output_tokens": 187,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 24680
}

From those you can work out how much of the latest prompt was read from the prompt cache:

cache_hit_pct = cache_read_input_tokens / (input_tokens + cache_read_input_tokens) * 100

In the payload above, 24,680 / (3,353 + 24,680) * 100 = 88%: most of the prompt came from the cache. When cache_read_input_tokens is 0 and cache_creation_input_tokens isn't, nothing was read from the cache and the prompt was written to it: a cold start.

Subagents

subagents lists the child tasks of the conversation, with status set to "running" or "completed":

"subagents": [
  { "name": "research", "role": "List the files in the project folder.", "status": "completed" }
]

role is the whole instruction the subagent got, so cut it short before you print it, or it wraps the line.

Personal data in the payload

The payload holds your email, session_id and conversation_id, and the full transcript_path. Your script receives them on every refresh, so be careful with them:

Don't print them, and don't write them to a log.
If you save payloads to debug, strip those fields first, and replace paths before you share a file in an issue.
Treat every string (cwd, conversation_title, subagent roles) as untrusted text: strip terminal escape sequences before printing, or a crafted value can change your terminal's state.

Reading stdin safely

One more thing the docs don't mention: agy can start the command and keep stdin open without writing anything (antigravity-cli#698). A blocking read then waits until agy kills the script, and after a few kills agy turns the statusline off. Read stdin with a deadline (one second works), and exit 0 with no output if nothing arrived. Also strip a leading byte order mark (\uFEFF) before JSON.parse.

Capture your own

To see exactly what your agy sends, point the statusline at a script that saves stdin to a file before rendering. With agy-powerline installed, set AGY_POWERLINE_DEBUG=1 before starting agy: each refresh saves the payload to ~/.agy-powerline/last-payload.json, with the email and IDs removed and paths replaced, so it's safe to share.

If you see a field or a bucket that isn't listed here (a cost object, another quota bucket, execution_mode in plan mode), I'd like to hear about it: comment below or open an issue with your dump. I'll update this list.

To install agy-powerline and start rendering these wire payloads right away:

npx agy-powerline init

🤖 One-shot install with Antigravity:

Hey agy, please install agy-powerline by running `npx agy-powerline init --yes`, then tell me to restart agy.

See your Antigravity CLI quotas without typing /usage (Gemini 5h/7d, Claude and Argon)

Wassim AZI — Tue, 20 Oct 2026 19:21:53 +0000

Think of it as htop for Google Antigravity CLI: an always-on display of your quotas, your context window and how fast you're using them.

If you've ever hit your Google AI Pro limit in the middle of an intense coding session, you know the feeling of context window blindness: one moment the agent is cruising through file edits, the next it grinds to a halt, and you discover your 5-hour quota ran out twenty minutes ago.

The traditional workaround is typing /usage, squinting at the numbers, and going back to work. A few prompt turns later, you find yourself typing /usage again.

Since mid-October 2026, there is even more to keep track of. On Google AI Pro, Gemini 4 Argon has its own weekly quota pool, completely separate from the standard Gemini bucket. So developers now balance three distinct quota pools:

Gemini: a 5-hour window and a 7-day window, each with its own reset time.
Third-party models (Claude, GPT): their own 5-hour and 7-day windows.
Gemini 4 Argon: an independent weekly quota on Google AI Pro.

I wanted all of that on screen, all the time, without asking for it or breaking flow state. This post explains which quota metrics agy exposes to its statusline wire format, and how to display them persistently using agy-powerline, a zero-dependency statusline engine.

The quota buckets agy sends

agy has a statusLine setting: it runs a command of your choice and pipes it a JSON payload, as described in the official docs. The docs' example payload shows a single quota bucket. In practice, agy sends up to five:

Bucket	What it is
`gemini-5h`	Gemini, 5-hour window
`gemini-weekly`	Gemini, 7-day window
`3p-5h`	Third-party models (Claude, GPT), 5-hour window
`3p-weekly`	Third-party models, 7-day window
`gemini-argon-wtu-weekly`	Gemini 4 Argon's own weekly quota, on Google AI Pro

Each one looks like this:

"gemini-5h": {
  "remaining_fraction": 0.979,
  "reset_time": "2026-10-16T23:59:02.000Z",
  "reset_in_seconds": 17042
}

remaining_fraction goes from 0 to 1. A bucket can also come with "disabled": true, and is best ignored then. The Argon bucket is sent whatever model you're using, so you can keep an eye on it before you switch to Argon.

So the data is there. A statusline only has to read it and draw it.

Install

You need Node.js 20 or newer. Then run:

npx agy-powerline init

init installs the runtime as one file in ~/.agy-powerline, backs up agy's settings.json, and sets its statusLine command. On a first install it asks you for a preset, a layout and a theme, with a live terminal preview of each. Restart agy once and the bar is live.

The setting points at the exact Node binary that ran init, so the bar doesn't depend on agy finding node on its PATH. That matters with nvm, or when agy is started from somewhere other than your shell.

🤖 Vibe-coding? Have your agent install it for you:
If you already have an agy session open, paste this prompt into your conversation:
Hey agy, please install agy-powerline by running `npx agy-powerline init --yes --preset quotas`, then tell me to restart agy.

If you'd rather stay inside agy using native extensions, it's also an agy plugin:

agy plugin install https://github.com/wassim-azi/agy-powerline
/agy-powerline-setup

It works natively on Windows (cmd and PowerShell), macOS, Linux and WSL. On Windows it doesn't need bash or jq.

The Quota watch preset

The default bar shows the model, context, git and your Gemini quotas. If quotas are what you care about most, switch to the preset made for them:

npx agy-powerline preset quotas

It draws three rows:

Your plan and the model in use.
Gemini 5h and 7d side by side, each with its reset timer.
Third-party 5h and 7d, then Argon's weekly quota and its reset.

A widget with nothing to show hides itself: without the Argon bucket in the payload, the Argon widgets simply don't appear.

Reading the pace marker

A percentage alone doesn't tell you much. "40% left" is fine if the window resets in 20 minutes, and bad news if it resets in 4 days.

So each quota meter carries a pace marker: a mark at the point the time window has reached. Here are two meters from the demo data (in the terminal, the colors make the fill stand out):

⏳ •••••●••••••  72.0% rem   🔄 Reset: 2hr 47m
📅 •••••••••●••  21.0% rem   🔄 Reset: 1d 17h

The meter fills from the left as you use quota. The marker (●) shows how far into the window you are.

5h quota: it resets in 2h 47m, so 2h 13m of the 5 hours have passed, about 44%. You've used 28%. The fill is behind the marker: you're using quota slower than time passes, so you can relax.
7d quota: it resets in 1d 17h, so about 76% of the week has passed. You've used 79%. The fill is just past the marker: at this rate, you'll run out shortly before the reset.

The marker needs no extra data: it comes from reset_in_seconds and the fixed 5-hour and 7-day window lengths. If you find it noisy, press r in configure to turn it off.

Prefer to see when a quota resets rather than how long until it does? Set the reset widget's format to a clock time:

{ "id": "fiveHourReset", "format": "time" }

One meter for "the quota that matters right now"

If you want something smaller, the quota widget shows only the bucket closest to running out, for the model you're using:

the Argon bucket when Argon is the model,
the other Gemini buckets for other Gemini models,
the third-party buckets for Claude and GPT.

The compact preset uses it to fit everything on one line:

npx agy-powerline preset compact

Still too wide for a small terminal? Minimalist mode (m in configure) drops every label and keeps the values. And on any width, the bar drops labels and shortens meters first, then the least important widgets, so it never wraps. Here's the bar from the top of this post in a window under 80 columns:

Tracking daily and weekly token spend without API calls

Quota windows (5-hour and 7-day resets) tell you how fast you're running right now, but they don't answer another common question: How many total tokens did I burn today across all my conversations?

The statusline payload sends context for the active session, but doesn't track historical usage. To solve that, agy-powerline includes tokensToday and tokensWeek widgets. They read Antigravity's local conversation files in ~/.gemini/antigravity-cli/conversations/ directly: no API keys, no network calls, no telemetry. They need Node 22.13 or newer, which has SQLite built in; on older Node they stay hidden, and npx agy-powerline doctor says why.

The tokens preset puts them on the bar:

npx agy-powerline preset tokens

It shows the context tokens, the session's tokens in and out and the cache hit rate, with today's and the last 7 days' totals on a second row.

Make it warn you

Quota and context meters switch to a caution color, then a danger color, as they run low. You can pick the levels per widget, and make a widget blink when it crosses the danger level:

npx agy-powerline configure

Select a widget, press Enter, and change its caution and danger levels. The live preview at the bottom of the screen follows every change, and q saves and quits. A running agy picks up the change on its next refresh.

While you're in configure, the tabs at the top let you try the presets, 16 themes (two of them color-blind safe), three layouts (Powerline pills, plain colored lines, or a classic text bar with block meters) and pill shapes. You can also customize how meters render: classic blocks, minimalist line, geometric rings (●●●○○○), or a ramp where each filled cell is shaded from the theme's ok color through caution to danger.

Prefer a browser? The same options are in the web configurator, which exports a config file you can import.

How fresh are the numbers?

The bar shows exactly what agy sends, as of its last refresh: agy runs the statusline when its state changes, and the quota values come from agy itself. agy-powerline makes no network calls of its own, so it can't be more up to date than agy, but it also can't disagree with it.

What else it won't do

No telemetry, no runtime dependencies. Everything comes from the payload, from your .git folder and from your OS.
Your settings are safe. init refuses to edit a settings.json it can't parse, and keeps a backup of the original.
Want agy's own line too? npx agy-powerline init --stack draws the bar below the built-in one instead of replacing it.

To remove it: npx agy-powerline uninstall.

Feedback welcome

The repo is github.com/wassim-azi/agy-powerline. If a quota or a field you care about is missing, open an issue: I build widgets from what agy actually sends, so a payload from your setup helps a lot. npx agy-powerline report writes a privacy-safe bug report, and the troubleshooting page shows how to capture a payload.

What do you keep checking with /usage that you'd rather see all the time?