Introducing agy-hq: Turning Google Antigravity into a Multitasking Personal Assistant Agent
Most AI coding setups behave like a single-task contractor: open one repository, start one chat, and wait while the agent reads files, edits code, and runs tests.
A real personal assistant doesn’t disappear for ten minutes just because you handed over one meaty assignment. Over a normal morning—moving between my laptop and my phone—my tasks rarely stay inside a single codebase or even inside software engineering. I want one home workspace where I can ask whether my 2pm slot is open, drop an incoming document into an inbox to summarize against my notes, and kick off bug fixes in two separate repositories—while the assistant in front of me stays immediately available for my next thought.
Today I’m sharing the workspace setup I built and use every day for that: github.com/zjshen14/agy-hq.
agy-hq (short for headquarters) runs on Google Antigravity—an agent-first IDE that includes background subagents, live Markdown artifact cards, local lifecycle hooks, and a mobile Remote Control web UI for talking to your desktop workspace from your phone. Rather than building a custom chat server or separate mobile app, agy-hq pairs a ready-to-run workspace template with a small, zero-dependency Go helper (./bin/hq) that makes Antigravity behave like a coordinated personal assistant: keeping one main chat responsive, isolating parallel tasks in separate directories, locking personal notes inside a git-ignored local/ vault, and even auditing local logs (./bin/hq obs) to show why a 130-step background worker actually bills fewer fresh tokens than waking up an idle main chat twice. (If you enjoy the backstory on why prompt-only rules struggled before adding hooks, those earlier notes are here—you don’t need them, as everything below starts from scratch.)
What agy-hq looks like in practice: you talk to one pinned [HQ] Front Desk assistant from laptop or phone alongside a zero-token live board (hq_console.md), while a local Go helper dispatches heavy work to the background and keeps personal files inside local/.
Try it in 60 seconds (--demo)
Prerequisites: Google Antigravity on macOS or Linux (or WSL2 on Windows), Go 1.22+, and Git.
Cloning someone else’s personal-assistant template usually feels lifeless at first because your notes, inbox, and task board start empty. To make agy-hq tangible right away, ./scripts/bootstrap.sh --demo compiles ./bin/hq (~1 second using only the Go standard library) and populates local/ with a synthetic [Sample] sandbox—a fictional ACME quarterly filing in local/inbox/, a sample thesis note with exit triggers, active tasks on the board, and a staged outbound command ready to approve or reject:
git clone https://github.com/zjshen14/agy-hq.git && cd agy-hq
./scripts/bootstrap.sh --demo # omit --demo for a clean empty local/ vault
./bin/hq status
Running ./bin/hq status immediately displays your local vault and the sample approval queued up with its SHA-256 lock:
Vault: /path/to/agy-hq/local
Pending Actions: 1
Active Worktrees: 0
- [prop-demo-acme-q3-alert] [Sample] Publish ACME Q3 10-Q digest: "Gross margin 64.2% (+140 bps YoY); watching 14-week substrate lead time" (demo_echo) sha256:e951958440e4
Open the agy-hq folder in Google Antigravity and send any message. The SessionStart hook initializes [HQ] Front Desk (pin it to the top of your sidebar), pins the live hq_console.md board on the right, and loads your compact startup memory.
Tracing one 3-part prompt from your phone
To see how it feels like an assistant rather than a single-repo coding tab, trace what happens when you open Antigravity’s Remote Control on your phone and send one mixed message to [HQ] Front Desk:
“Is 2pm free today? Also diff the ACME 10-Q in my inbox against my notes, and fix PR #279 in
~/src/web-app.”
Without guardrails, an eager agent would start reading the filing, editing ~/src/web-app, and running npm test directly inside your main chat—freezing your phone screen for five minutes before answering whether 2pm is open. Here is what agy-hq does instead:
- Answers the 2pm check in two seconds (
<= 3reads per turn): On[HQ] Front Desk,./bin/hq hook pre-toolallows up to three lightweight read-only lookups per user turn—so checking your calendar finishes immediately. If the Front Desk tries to edit source code, run a test suite, or make a fourth read, the hook blocks the call and tells it to dispatch background workers so your assistant stays free for your next message. - Checks out an isolated
git worktreein any local repo: Your codebases don’t need to sit insideagy-hq. Passing--repo=~/src/web-app --task=web-fix-pr279checks out an isolated Git worktree and branch underlocal/worktrees/web-fix-pr279/, where a background worker (or a dedicated[Task:web]sidebar thread for multi-turn design) edits code and runs tests without touching your main~/src/web-appcheckout or colliding with another task on the same repo. - Quarantines untrusted files against prompt injection: Meanwhile, a second background worker opens
local/inbox/acme-q3-10q-sample.txtvia./bin/hq quarantine. Because external attachments and emails can hide prompt-injection instructions,quarantinewraps the text as untrusted data and marks that session ID as tainted—mechanically blocking file writes, outbound CLI commands, spawning clean child subagents to escape the taint, and calling externalmcp_*plugin tools. - Refreshes the live board in 0 tokens and asks 1-tap approval: At the end of each turn,
./bin/hq hook stopupdates the pinnedhq_console.mdcard in pure Go (0extra LLM tokens, zero markdown status tables spammed into chat). Whenever a worker wants to perform an irreversible external action—sending a message, emailing someone, or merging PR#279—it stages the exact command via./bin/hq propose, quotes the full unescaped payload in chat, and pops up Antigravity’s native Approve / Reject card on your phone (or on an optional127.0.0.1:4242local web console guarded by a 256-bit CSRF token). Tapping Approve verifies at least 8 hex characters of theSHA-256hash (sha256:e9519584) before executing it.
Modular Markdown skills—keep only what you use
A personal assistant covers different domains for different people, so seeing workflows like filing-diff, ledger-ingest, or gchat often raises a fair question from developers: “Do I need SEC filings, plain-text accounting, or Google Chat set up—or have to edit Go code—just to use agy-hq?”
Not at all. Every workflow in .agents/plugins/agy-hq/skills/*/SKILL.md is an independent, plain-Markdown runbook (<= 150 lines) loaded only when relevant—not compiled Go logic and not a sequential pipeline:
Nine independent SKILL.md plug-ins over a shared Go safety floor. You don’t need Go to edit or write skills—and you can ignore or delete any optional domain you don’t use.
- Core engineering & bounded memory (
swe-pulse,morning-brief,sleep-consolidate): If you only want an engineering and daily-planning assistant, these three give you multi-repogit worktreeorchestration and PR/CI tracking, a morning rollup of calendar items, open PRs, and pending approvals, plus self-cleaning memory. Startup memory (local/MEMORY.md) is capped at<= 80lines by Go so startup prompts stay lean, linking tolocal/memory/topics/*.mdnotes thatsleep-consolidatecross-checks against raw tool outputs at night so unverified claims don’t stick. - Intake & optional domain plug-ins (
inbox-triage,gchat,filing-diff,thesis-check,ledger-ingest,tax-prep): Drop-in Markdown skills for quarantined file triage, Google Chat spaces/drafts, section-by-section10-K/10-Qdiffs, investment thesis checks, and localBeancount/hledgeror tax workpapers. Skip them, delete them, or drop in your ownSKILL.mdin two minutes.
Across every skill, the two-layer local/ vault keeps personal life out of Git history: tracked engine code and generic skills live in agy-hq/, while all personal notes, memory logs, worktrees, and private records live inside git-ignored local/—backed up to its own private local/.git repository and guarded by 6 pre-commit privacy checks.
Matching models to jobs—and why new deep thinkers like Gemini 4 Carbon fit right in
Splitting a responsive Front Desk from background workers also solves a growing headache as frontier reasoning models—most recently Gemini 4 Carbon—lean into longer, 10-to-15-minute verification and self-checking loops. In a traditional single-window chat, letting a heavy reasoning model explore a race condition or security audit across 100+ steps locks up your assistant the entire time; conversely, leaving a frontier model attached to a casual chat burns scarce quota every time you check your schedule.
Because agy-hq delegates heavy work out of the main thread, ./bin/hq automatically right-sizes models by task complexity: quick (gemini-3.8-flash-low) for status checks and triage, standard (gemini-3.8-flash-high) for everyday coding and document extraction, and deep (gemini-4-carbon-high, or any explicit --model override you prefer) for architecture design, subtle concurrency bugs, security audits, and thesis stress-testing. Your assistant stays instant up front while long-horizon models get uninterrupted room—and deterministic Go guardrails—to do their best work in isolated background worktrees.
Does delegating to subagents blow up your token budget? (./bin/hq obs)
Whenever I describe delegating coding and research out of the main thread into background subagents, the first practical question people ask is: “Doesn’t spawning subagents burn way more tokens?”
To measure instead of guessing, agy-hq includes ./bin/hq obs, which parses Antigravity’s local transcript.jsonl step logs—fresh uncached input_tokens, prefix-cached cache_read_tokens, and output_tokens—in pure Go at zero token cost. Auditing 68 real conversations (4,894 model steps and 505.8 million gross tokens) revealed the exact opposite of what I originally expected:
Measured across 505.8M gross tokens: continuous background subagents stay warm inside the ~5-minute prefix-cache window, whereas an uncompacted main chat waking up after idle gaps pays full uncached prompt cost.
- Workspace-wide,
92.1%of all prompt tokens hit prefix cache (462.5Mcached reads vs.39.8Muncached fresh input). - Continuous coding subagents are remarkably cache-efficient (
97.4%–97.9%hit): Because a background worker steps every 3 to 8 seconds, almost every turn lands inside the ~5-minute prefix-cache TTL. A 130-step coding subagent (15.2Mgross tokens) billed only396kuncached input tokens; a 151-step subagent (20.6Mgross tokens) billed430k. - Idle gaps on a bloated main chat are the real budget sink (
0%cache hit): Because[HQ] Front Deskstays open across days while human messages and scheduled jobs arrive 10 minutes to hours apart, its prefix cache expires between turns. Once the Front Desk drifted to207kcontext tokens, just 2 wakeup steps (after 11- and 29-minute idle gaps) billed414kuncached input tokens—more fresh input in two coordinator turns than a 130-step coding subagent!
To eliminate that “cold-wakeup tax,” agy-hq tracks live context size and nudges /compact (or a clean shift handover) once [HQ] Front Desk crosses 160k tokens—cutting cold wakeups from 252k down to 27k tokens (89.2% less per wakeup) while local/MEMORY.md preserves continuity.
Good to know & grab what’s useful
Two practical notes if you take agy-hq for a spin:
- The 3-lookup cap on the Front Desk is deliberately strict. Occasionally, a simple question happens to need a fourth file read; the hook will force
[HQ] Front Deskto hand off to a quick background subagent rather than risk letting a slow investigation block your phone chat. Every cap, routing tier, and skill lives in plain Go, YAML, and Markdown if you prefer looser defaults. - Pulling updates won’t clobber your private vault. Running
./bin/hq upgradesnapshots your privatelocal/.git, fast-forwardsmain, rebuilds./bin/hqin ~1 second, runs non-destructive config migrations, and checks workspace health with./bin/hq doctor—backed by 21 isolated sandbox end-to-end tests (~1.8s).
Even if you don’t need a full personal headquarters workspace, feel free to grab individual pieces: the zero-dependency Go PreToolUse / Stop hook skeleton, ./bin/hq obs to inspect prefix-cache hit rates across your own Antigravity logs, or the two-layer local/ vault layout.
Everything is live at github.com/zjshen14/agy-hq (Apache 2.0). If you try --demo, adapt it into your own personal assistant setup, or hit rough edges, I’d love to hear from you in Discussions or Issues!
Want the exact CLI overview, routing tiers, and telemetry numbers?
Prepared with AI assistance. Figures correspond to github.com/zjshen14/agy-hq as of November 11, 2026, with chart data recorded in summary.json.
- Host & zero-dependency Go helper (
./bin/hq): Built with the Go 1.22+ standard library (0external dependencies ingo.mod). Plugs into.agents/hooks.json(SessionStart,PreToolUse,Stop). Everyday commands include./bin/hq status,./bin/hq doctor,./bin/hq obs [--days=N] [--json],./bin/hq spawn --repo=<path> --task=<slug>,./bin/hq subagent,./bin/hq worktree add|list|prune,./bin/hq propose/approve/reject,./bin/hq webui(127.0.0.1:4242), and./bin/hq upgrade. - Smart model & thinking-depth routing: Automatic task classification routes
quicktasks togemini-3.8-flash-low,standardcoding/extraction tasks togemini-3.8-flash-high, anddeeparchitecture, security audit, concurrency debugging, and thesis-falsification tasks togemini-4-carbon-high(with explicit--model/--depthflags and natural-language overrides). - Front Desk & worktree isolation:
local/memory/front_desk.jsontracks the active Front Desk conversation lease. On that thread,PreToolUseallows up to3read-only inspection calls per turn and denies inlineedit_file,write_file(outsidehq_console.md), and test suites (go test,npm test,pytest). Coding tasks isolate branches underlocal/worktrees/<repo>-<task>/.Stoprefresheshq_console.mdandlocal/memory/journal/in pure Go (0extra LLM tokens). - Nine modular skills (
<= 150lines each):swe-pulse,morning-brief,sleep-consolidate,inbox-triage,gchat,filing-diff,thesis-check,ledger-ingest, andtax-prep. Startup memory (local/MEMORY.md) is mechanically capped at<= 80lines. - Quarantine, approval & privacy gates: Tainted sessions (
local/memory/tainted/<conv>.json) block file writes, outbound CLI commands, childinvoke_subagent/hq spawnescapes, and externalmcp_*calls. Outbound proposals verify>= 8-charSHA-256prefixes; the optional127.0.0.1:4242WebUI enforces loopbackHost+ same-originOrigin/Sec-Fetch-Site+application/json+ constant-time 256-bitX-HQ-CSRFchecks. Pre-commit and pre-push checks (./bin/hq ci pre-push,~2.5s) verify6/6privacy rules (includinglocal/pii-denylist.txtand--historypatch scanning),18/18simulated hook security probes, and21isolated end-to-end sandbox workflows (~1.8s). - Token & prefix-cache audit (
./bin/hq obs): Across68Antigravitytranscript.jsonllogs (4,894reasoning and compaction steps;505,830,652gross tokens =39,816,608uncachedinput_tokens+462,514,486cache_read_tokens+3,499,558output_tokens), overall prefix-cache hit ratio was92.1%. Continuous coding subagents hit97.4%(130steps,395,917uncached) and97.9%(151steps,430,040uncached), while[HQ] Front Desk(110turns,500steps) incurred49cold wakeups (9,505,555uncached tokens,23.9%of workspace uncached spend). Context watermarks warn at160,000tokens (criticalat200,000), cutting cold wakeups from252,166to27,244tokens (-89.2%).
Scan with WeChat
Scan this QR code with WeChat to read or share on mobile.