LitFamily cover: seven armored machines stand in their bays, and the LitGravity machine in the seventh bay, gyroscope rings around a dark spherical head, wakes with orange cores in its head and chest and a lit frame, under LITFAMILY and KEEP THE WORK LIT.

LitGravity

Keep the work lit.

LitGravity gives Google's Antigravity CLI (agy) the habit of planning before it edits, checking what it built, and leaving a handoff, so the next conversation starts where this one stopped. One npm command installs it as an agy plugin.

Install Demo Safety Quick start What you can make What you get agy limits 한국어

Demo

What ignition looks like, captured from the real hook and status line on this Mac: the typed prompt, the injected route note, and the status line carrying the lit-loop map.

What you can make

Each picture is a real output made on this Mac. The lit-adhd brief was drawn by its collector over three real agy conversations; the others were made by each skill's own engine from the skill's worked example, the same engine agy calls when you ask in a conversation.

Picture	Skill	What it shows
	`lit-pptx`	One deck in four of its tonalities. Charts and KPI rows stay native and editable, Pretendard is embedded, and each deck passed the gate for overflow, contrast and empty slides.
	`lit-schematic`	A P&ID with ISA-5.1 tags, line numbers, a legend and a title block. Its checker passed: no text on a line, no line through a symbol, no loose end.
	`lit-schematic`	The same skill drawing equipment as an isometric cutaway and as a two-panel figure for a paper.
	`lit-typographic-motion`	Four frames of a 12-second film from a one-line Korean request. The skill wrote a treatment first, rendered it frame by frame with a sound bed, and its gate checked flashes, legibility and the loop.
	`lit-adhd`	Type `lit adhd` after a scattered day: one brief of what you asked, what got written, what is still running and one real next step.

Why LitGravity

agy starts fast: you type a line and it gets to work. The trouble shows up later. A long conversation fills its context, the next one begins without what the last one learned, and "done" often means the model said so. You end up re-explaining where you were and checking by hand what really works.

LitGravity gives each conversation a routine. Start a prompt with lit and a hook, which runs before the first model call, tells agy which LitGravity skill to read before it touches anything. A bigger change gets a written plan in plans/ first. The work is checked against that plan with tests and a look at the real surface, and whatever nobody could check is marked as unverified. Before you stop, a handoff in .litgravity/handoff/ records what was built, how it was checked and what is left.

you type    lit plan a tiny todo app
it does     reads the plan skill, explores the repo, writes plans/todo-app.md with ordered tasks and checks
it ends     "Plan saved. Run `lit start plans/todo-app.md` when you are happy with it."

agy still runs the conversation and picks the model, while LitGravity adds the routine around it. That routine lives in plain files you can read:

What agy does	What lit adds
Starts from one typed line	A plan in `plans/` before the first edit
Forgets the last conversation	Checks against the plan, marks the unchecked as unverified
Calls it done when the model says so	A handoff in `.litgravity/` the next turn reads

Install

You need Node.js 20 or newer and the Antigravity CLI, signed in once. In a terminal, run:

npx @litfamily/litgravity install

The installer shows every destination first. By default it copies the plugin to ~/.gemini/config/plugins/litgravity, so LitGravity is available in every project; --scope project copies it to ./.agents/plugins/litgravity for one project. It validates the plugin with agy plugin validate before and after copying. agy loads a plugin's hooks, skills and agents without a trust step, so there is nothing to approve. Then check the result:

npx @litfamily/litgravity doctor

doctor lists the installed copy, the validation result, the six hook events and a smoke run of each hook script, every skill and agent, every engine with its pre-warm command, the host programs the skills call, and the Python the engines will use. It ends with LitGravity: ready when nothing is broken.

Terminal capture. The install command ends with Status: Ready, and the doctor command ends with LitGravity: ready after thirty passing checks.

Useful switches: --dry-run previews and writes nothing; --yes lets an agent or CI shell install (a shell without a terminal otherwise only previews); --status-line adds the optional LitGravity status line to agy's user settings (never on by default).

The status line is one row under the prompt, drawn in the LitFamily status-line style: the [🔥LIT v…] mark, then every segment in LitGravity's flame orange. It reads model [effort] │ ctx [█▎░] 42%/1049k │ quota [▌░]28% ↻ 2h5m, then the active lit route as a pink 🔥 LIT chip with its clock, then where the route stands on its map (PIN, RED, GREEN, VERIFY, REVIEW, RECORD for the open criterion of litwork and lit-loop, read from its evidence files; interview, plan, work, review, done for planning and start-work, with the plan's rows), the lanes of a lit-team, and whatever agy also reports: cost, background tasks, the branch and the title. The context and quota gauges turn yellow at 70% and red at 90%. On a narrow terminal the extras go first and the route and the context gauge stay. NO_COLOR turns colour off and LITGRAVITY_HUD_ASCII=1 keeps every glyph ASCII. If agy already shows another status line, the installer refuses to touch it; install --status-line --replace-status-line swaps it after saving the old value, and uninstall puts that value back.

Let a coding agent install it

Paste this into a coding agent opened in any folder:

Install LitGravity, the LitFamily plugin for Google's Antigravity CLI.
Use only the official npm package @litfamily/litgravity. Show me your plan and wait for my yes before changing anything.
1. Check that Node.js 20+ and agy are on PATH (`agy --version`).
2. Preview: npx @litfamily/litgravity install --dry-run
3. Install: npx @litfamily/litgravity install --yes
4. Verify: npx @litfamily/litgravity doctor and report its last line.
5. Tell me what was written (the installer prints a "Written:" list) and anything it refused.

Quick start

Open agy in a project. Type /skills to see the LitGravity skills and /hooks to see the plugin's hooks.
Start a prompt with lit. Plain lit runs the default loop; the word after it picks the route: lit plan, lit review, lit research, lit debug, lit handoff, lit recap, lit brainstorm, lit korean. Any skill id works as that word (lit debugging, lit structural-search), and /litgravity:<skill-id> runs a skill as a slash command.
Approve a plan, then lit start plans/<slug>.md builds it row by row with tests.
Before you stop, lit handoff. Next time, lit recap reads where you were.

npx @litfamily/litgravity list prints every skill with the words that reach it. A lit while its route is already active gets a short "continues" note, lit <other route> switches, a bare lit picks up a plan you started with lit start, and lit new starts over.

The status line

One row under the prompt shows where the work stands: the model and its effort tier, the context and quota gauges, the active route with its clock, and the map of that route with the current stage lit. The capture below is a real render from this Mac, before and after a lit prompt.

Terminal capture of the status line. Before lit it shows the model and the context gauge at 42 percent. After lit it adds the lit-loop chip with its clock and the PIN through RECORD map with PIN lit.

When the terminal narrows, the extras give way first and the route and the context gauge stay. Where colour is off, the same row renders in plain text:

[LIT] | GF3.8 | ctx [#--] 42%/1049k | [LIT] . lit-loop 2:20 | [PIN] = RED . - GREEN . - VERIFY . - REVIEW . - RECORD .

Some moments change the look of the row. While lit adhd (or lit-rewind, the skill typed whole or after /, or the skill the model loads by itself) is the route, every cell turns its own colour of a slow rainbow. When the turn ends on a question, a typed approval, a BLOCKED report or a goal that needs a decision, the row turns amber and reads ⚠ YOUR TURN · <why> until you type. During lit review work the five lanes (goal, qa, quality, security, context) appear as each reports, in its own colour with its verdict mark and a count such as 2/5. A plan or goal finished during the route shows ✦ DONE ✦ for twenty seconds. agy repaints the line when it chooses, so every look is static, and NO_COLOR keeps the labels in plain text.

What you get

42 skills, each a dense agy skill read on demand, with the references, scripts, templates and engines it needs inside its own folder. agy loads only the first 24,000 bytes of a SKILL.md, so the long material sits in the skill's references/ folder and the skill names the file to open.

A lit turn runs the same routine through these parts. A bigger change gets a written plan first, the work is built row by row with tests under a goal record that outlives one conversation, a second look reviews it before anything merges, research shows its sources, documents and prose read clean, and the turn ends with a handoff the next conversation reads:

Part	Contents	Role
42 skills	Dense agy skills with their references, scripts and engines	Plan, build, check, research, write, hand off
11 agents	Child agents agy starts under their type names	Plan, execute, verify, review, Korean prose
6 hooks	Run at session start, each turn, each tool call, and the stop gate	Route `lit`, hold unfinished turns, ledger every tool

agy loads only the first 24,000 bytes of a SKILL.md, so the long material sits in the skill's references/ folder and the skill names the file to open. The skill groups are loop and goals, ideas and planning, building, review and cleanup, research and knowledge, teams, prose, continuity and guidance, interface and docs, documents and figures, film and covers, and tools; npx @litfamily/litgravity list prints every skill with the words that reach it.

The document, diagram, README-cover, figure and motion skills ship pinned engines: office, diagram, readme, sciviz and motion. Each installs into ~/.local/share/litgravity/runtime/<name> and nowhere else. Install them once with npx @litfamily/litgravity runtime install all (or one name); runtime status shows each one. A skill checks its engine first and asks agy to run the install command when it is missing. Engines that need Python pick a supported interpreter by themselves: a python3 newer than 3.14 has no wheels for the pinned packages, so they walk to python3.14, python3.13 and so on, honour LITGRAVITY_OFFICE_PYTHON, LITGRAVITY_SCIVIZ_PYTHON or LITGRAVITY_MOTION_PYTHON, and answer BLOCKED with the exact fix when no interpreter fits. The skills also call programs already on your machine: LibreOffice, pandoc, Poppler, Chrome or Chromium, ffmpeg, libwebp, ast-grep, XeLaTeX and the language checkers that lsp drives. doctor names what is missing and the command that installs it; LitGravity never installs software globally.

11 agents, started by agy with invoke_subagent under their type name: lit-planner, lit-executor, lit-verifier, qa-runner, quality-reviewer, librarian-researcher, and five Korean prose agents (korean-style-analyzer, korean-prose-editor, meaning-preservation-auditor, native-flow-reviewer, polish-orchestrator). Reviewers and the Korean agents get read and search tools only.

6 hook events:

SessionStart adds the LitGravity route list, an update notice and a pointer to a fresh handoff note, once per new conversation.
PreInvocation is the lit router. agy has no prompt hook, so on the first model call of a turn the router reads the newest prompt from the transcript, applies the re-entry rule and injects one step that names the skill file to read.
PostInvocation and Stop run the checks that agy cannot run in advance (see the limits below). Stop also holds a turn: a lit-plan turn until plans/<slug>.md exists, start-work while an approved plan has open rows, litgoal and lit-loop while a goal record has an open criterion, at most three holds in a row without progress. Say pause, or write BLOCKED at row N:, PAUSED at row N: or CANCELLED: in the ledger, to release it. A motion turn ends when the skill's own done-check passes on the last render, or after two holds with a plain not-done notice.
PreToolUse refuses child agents that could write while lit-plan is active.
PostToolUse writes one ledger line per tool call while a route is active, in .litgravity/ledger/<conversation>.jsonl, with key shapes redacted. A silent ledger means the hooks are not loaded.

Models: npx @litfamily/litgravity models lists the models and effort tiers your agy offers, read from agy itself, so a model Google adds later shows up with no LitGravity update.

What agy limits today

These are the facts of agy 1.4.3, probed on a real install. LitGravity works inside them and says so where it matters.

No blocking before a write. agy's PreToolUse hook has to decide every call it sees; an empty answer counts as a denial, and an allow may lift your own approval prompts. So LitGravity leaves file writes and shell commands alone before they happen. A lit-plan turn that changed anything outside plans/ is told to undo it right after, and prose that stacks negations or hedges is reported after it is written. The one hard stop is a child agent that could write during a lit-plan turn.
Headless runs cannot ask. In agy -p, a run_command or write_file that needs permission is denied, and the denial ends the run with an empty answer (the JSON lists it under denied_actions). read_file inside the workspace works. The skills read first and report BLOCKED with the permission they need. For scripted use add allow rules to agy's settings or pass --dangerously-skip-permissions, at your own risk. Use a project-scope install (--scope project) when a headless run has to read the skill files, because a plugin whose real path lies outside the workspace was denied its read_file in the same probe.
Seeing images. agy's model reads a PNG through read_file. Every look step in the visual skills relies on that, and it was proven with a picture whose only content was a word the prompt never mentioned.
Starter Quota. Every model call counts against your account's quota, so tests and probes use agy plugin validate and /hooks, /skills, /agents, which cost nothing, and a build of LitGravity spends only a handful of real calls.
No compaction event, no slash-command folder, no MCP server from a plugin here. lit-handoff writes .litgravity/handoff/latest.md and a new conversation is pointed at it. Skills are the commands (/litgravity:<skill-id>). wikify runs as script subcommands inside the skill.
No lsp tool. The lsp and lsp-setup skills drive language checkers from the command line instead.

What a planning turn may do

lit plan turns are planning only. Most of that is asked, then checked afterwards, because agy offers no safe way to stop a write before it happens (see the limits above):

The router tells the model to write only under plans/ and .litgravity/ and to keep the shell to plain read-only commands. Your own approval prompts still decide whether a write or command runs.
After every model call and at the end of the turn, the boundary check compares the workspace with its state at the start of the turn. A file changed or removed outside plans/ is reported and the model is asked to undo it, at most twice per turn. A command that changed nothing on disk leaves no trace for this check.
Child agents are refused before they start unless they are read-only: lit-planner, librarian-researcher, lit-verifier, quality-reviewer and the Korean prose agents.

Route state lives outside the project, under ~/.local/state/litgravity/, away from the files a planning turn is asked to touch. If that state is damaged, the child-agent limit and the plan gate stay on; if it goes missing, the hooks fall back to the route journal kept beside it.

Held turns and the ledger

Some turns are allowed to wait. A lit-plan turn with no plan file yet is held at the end until plans/<slug>.md exists, at most three holds in a row without progress. Start-work waits while an approved plan has open rows, and litgoal and lit-loop wait while a goal record has an open criterion. Say pause, or write BLOCKED at row N:, PAUSED at row N: or CANCELLED: in the ledger, to release a hold. The capture below is the real hold from a planning turn that wrote nothing.

Terminal capture. After the prompt lit plan a tiny todo app with no plan file written, the Stop hook answers decision continue with the lit-plan gate reason asking for the plan file. A second block shows a ledger line recording a read_file tool call.

While a route is active, every tool call lands in .litgravity/ledger/<conversation>.jsonl with key shapes redacted, one line per call. Before you stop, lit handoff writes .litgravity/handoff/latest.md with what was built, how it was checked and what is left, so the next conversation starts from that note.

Safety and uninstall

The installer writes only its own plugin folder, its data directory ($XDG_DATA_HOME/litgravity) and, when you ask, the status line key in agy's user settings, after a backup. It never reads agy's credential files.
A symlinked, foreign or edited destination stops the install before the first write, with the command to move it aside. --dry-run never mutates.
Hooks fail open: if one breaks, your conversation continues.
Engine caches live under ~/.local/share/litgravity/runtime/. uninstall keeps them, so delete that folder to free the space.
Set LITGRAVITY_HOOK_TRACE=<file> before starting agy to log one line per hook call. It is off otherwise. Three commands cover the lifecycle, and every one previews with --dry-run:

Task	Command
Install	`npx @litfamily/litgravity install`
Update	`npx @litfamily/litgravity install` (validates, replaces in place)
Refresh engines	`npx @litfamily/litgravity runtime install all`
Check	`npx @litfamily/litgravity doctor`
Remove	`npx @litfamily/litgravity uninstall --yes`

Files that conversations created in your projects (plans/, .litgravity/) stay where they are.

Family

LitGravity is one of the seven LitFamily packages. Each one brings the same way of working to a single coding agent, and each installs and runs on its own: install the one for the agent you use, and it needs none of the others.

The seven armored machines on the cover are those seven packages, and LitGravity is the orbit machine in the seventh bay. The cover is brand motion made with the LitFamily motion skill: drawn and animated artwork, with no agy session recorded in it. If your system asks for reduced motion, you see a still frame instead.

The seven LitFamily machines side by side, all lit: LitClaude, LitHermes, LitCodex, LitOpenCode, LitGrok, LitMuse and LitGravity, under LITFAMILY and KEEP THE WORK LIT.