Guhwoo

guhwoo: drive a cloud draft from your agent (via the guhwoo CLI)

guhwoo (guhwoo.com) is an AI-native, motion-first editor for web pages and web artifacts. The user works visually in it (pan/zoom, select, drag, adjust tweaks, edit directly); you, the agent, write the code. You push local HTML up as a cloud draft, the user refines it in the editor, and you pull their changes back and keep going. The draft is your shared source of truth.

You run under the user's own account session (guhwoo login does a browser sign-in and reuses the existing JWT). Generation comes from your LLM, so it does not consume guhwoo cloud credits.

One-time setup

1. Install the CLI (put bin/guhwoo.mjs on PATH):

   ln -sf "$(pwd)/bin/guhwoo.mjs" /usr/local/bin/guhwoo   # or ~/.local/bin/guhwoo
   # or skip it: node <repo>/bin/guhwoo.mjs <command>
   

2. Sign in:

   guhwoo login          # opens the browser; one click in an already-signed-in guhwoo.com session
   guhwoo whoami         # confirm  (credentials live in ~/.guhwoo/credentials.json, mode 0600)
   

The loop

1. Write a complete, standalone .html locally (a real motion-first web page).
2. Create the draft and open the editor. Decide object type and canvas first — see the next section:

   guhwoo draft create --html page.html --name "Landing" --open
   

   This creates the cloud draft, binds the current directory to it (writes .guhwoo/draft.json), and opens the editor.
3. The user refines it in the editor (drag things, adjust tweaks, rewrite copy, change colours). Those edits save into the draft automatically, cost zero tokens, and should not be done by you.
4. Pull their changes back:

   guhwoo history                     # preferred: the net change since you last looked
   guhwoo draft pull -o page.html     # full current source, when you actually need all of it
   

5. Push your next round:

   guhwoo draft push page.html        # overwrites the draft HTML; the editor refreshes live
   

Objects in a draft: animation frame or web page

A draft holds one or more objects, each a standalone HTML artifact. Objects have two independent properties — type and canvas — set by different flags. Choose them separately.

1. Type: whether it has a timeline (--animation)

	Animation frame (--animation)	Web page (default)
Timeline	Yes: track, playhead, space to play, drag to seek; the master clock drives it	No: the row is hidden, page animations run themselves, the clock stays out
Canvas behaviour	Fixed W×H, eight resize handles	Adjustable width, height flows with content, side handles only
Export	GIF / MP4 / HTML / Lottie	HTML (code)
Good for	Fixed-length motion, anything you scrub frame by frame or turn into video	Landing pages, long reads, anything that scrolls naturally

Type is fixed when the object is created. There is no switch for it in the editor; getting it wrong means rebuilding.

2. Canvas: set on its own (--size / --format)

Canvas is orthogonal to type. Giving a canvas does not imply animation, and wanting animation does not mean accepting the default canvas.

Flag	Canvas
--size 720x1440	720×1440 (any values)
--format vertical (alias portrait)	1080×1920
--format square	1080×1080
--format landscape (alias wide)	1920×1080
omitted, with --animation	1920×1080 (a default, not a limit)
omitted (web page)	1440×1024

Any combination is valid:

guhwoo draft create --html reel.html --animation --size 720x1440 --open   # vertical animation frame
guhwoo draft create --html reel.html --animation --format vertical        # same, via a named preset
guhwoo draft create --html landing.html --format landscape                # fixed-width page, no timeline

Choosing

Go by the capability the artifact needs, not by its dimensions. Needs a timeline, frame-accurate seeking or video export → --animation, and give it the size it deserves with --size/--format. Artifact is a naturally scrolling page → the default web page. Dimensions are never a reason to give up the timeline, and the reverse holds too.

Objects appended with draft push --object <new id> are always web pages (1440×1024). Use draft create for animation objects.

Images and assets: do not inline base64

The user's assets stay on their device (in the browser) and do not go into your HTML. When a page needs an image, font, video or audio, do not write data:/base64 URLs — that bloats the HTML and re-uploads the bytes on every push. Instead:

1. Upload the file once (to the bound draft):

   guhwoo asset put logo.png        # prints the reference: asset://logo.png
   

2. Reference it with the portable placeholder (anywhere a URL goes):

   <img src="asset://logo.png" alt="Logo">
   <div style="background-image: url(asset://hero.jpg)"></div>
   

The editor resolves asset://<name> to the local file when rendering and inlines it on export; the bytes only reach the cloud if the user publishes. The HTML you push stays small and portable: placeholders, no bytes, no URLs. guhwoo asset list shows what has been uploaded.

Commands

Command	What it does
guhwoo login [--token <jwt>]	Browser sign-in (or paste a token); credentials in ~/.guhwoo/credentials.json
guhwoo draft create --html <file> [--name <n>] [--animation] [--size WxH | --format vertical|square|landscape] [--open]	Create a cloud draft, bind the current directory, --open launches the editor. --animation sets type (timeline), --size/--format set canvas — independent, see above
guhwoo draft open [id]	Open a draft's editor in the browser (id defaults to the bound draft)
guhwoo draft pull [id] [-o <file>] [--object <oid>]	Pull the draft HTML including the user's edits; -o writes a file, otherwise stdout
guhwoo draft push <file> [id] [--object <oid>]	Overwrite the draft HTML from a local file (--object defaults to main)
guhwoo draft list	List your drafts
guhwoo draft use <id>	Bind the current directory to a draft
guhwoo asset put <file> [id] [--name <n>]	Upload an image/font/media to the draft; reference it as asset://<name>. Do not base64-inline images.
guhwoo asset list [id]	List the draft's uploaded assets
guhwoo history [id] [--since <ts>] [--all] [--each] [-n <count>]	What changed since you last looked: a unified diff (- / +) per object, plus geometry changes and an origin marker ([user] / [agent]). Starts from the cursor and collapses many autosaves into one net diff per object; --each for the per-save timeline, --all from the beginning
guhwoo whoami / guhwoo logout	Check sign-in state / sign out

Binding: create and use write draftId into .guhwoo/draft.json in the current directory, after which pull/push/open/history can omit the id.

This file states intent; guhwoo --help is the interface spec — where they disagree, the actual --help output wins.

When to use you, and when to let the editor do it

• You own semantics and authoring: structure, sections ("make it a three-column pricing table"), motion, "give this hero a scroll-triggered entrance", changes described in words. → pull (see the current state and the user's edits) → edit locally → push.
• Deterministic nudges belong to the user in the editor (moving things, resizing, adjusting an existing colour or slider tweak). Those write straight to the draft and cost zero tokens; do not do them for the user.
• To know what the user changed in the editor, use guhwoo history. It hands you the diff, geometry changes and origin ([user]/[agent]) since your last cursor — no need to pull two full copies and compare them yourself. Reach for guhwoo draft pull only when you need the full current source.

Output principles

• Code is the truth: a change only counts once it lands in the draft HTML (push). The editor refreshes immediately; the user does not need to reload.
• Motion-first web output: prefer CSS transform/transition/@keyframes, IntersectionObserver (animate on appear) and @media responsiveness over imperative scripting. CSS @keyframes — including staged timelines via animation-delay — can be seeked and scrubbed in the editor and can be exported. Reserve window.seekTo(t) for canvas/WebGL animation, which the browser cannot introspect frame by frame.
• Getting it back into the user's repo: they can use the editor's export (HTML/code), or you can just use the HTML you already pulled.
• Motion quality floor. Lockstep timing, teleporting and linear easing are what make motion read as machine-made. The minimum bar: seeded stagger across group moves, a 0.1–0.2s anticipation beat before large displacements, 30–50% overlap between adjacent phases, a 3–6% overshoot settle on arrival, and exits eased faster than entrances.

What you can and cannot see

You can see the saved draft state (draft pull) and the version history (history, with [user]/[agent] origins). You cannot see the user's current selection, annotation strokes, playhead position, or an unsaved drag in progress. Only the user can tell you those in conversation — do not guess, and do not pretend to know.

Non-Claude agents (Cursor, Cline, …): paste the equivalent of this file into their rules format. The guhwoo CLI and the protocol are the same.