happy-desktop
AGENTS.md113 starsChanged 19 days agoMITView on GitHub
Absolutely never change a host process of electron app without double confirmation from a human - this breaks clous updates. Never create GitHub Actions workflows, or add automatic triggers (push, pull_request, schedule) to existing ones, without explicit user instruction: Actions minutes cost real money. Validation runs locally. Read master-plans/00-master-plan.md first, before any other work. It explains how master plans are used and maintained. Then find every plan in master-plans/ relevant to your task and read each one in full before…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- blueprint-screensSkill
- guided-reviewSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
29 rules. About 0 are common, 12 are distinctive, and 17 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 9
Never create GitHub Actions workflows, or add automatic triggers (push, pull_request, schedule) to existing ones, without explicit user …
- Very specific: line 29
Read docs/releases.md before release work.
- Distinctive: line 50
Before hardcoding any product behavior an agent can affect, ask: could this just be a prompt?
- Distinctive: line 51
If so, it belongs in the agent's prompt, not the client.
- Distinctive: line 57
Treat each feature as one atomic, independently mergeable change, not as the lifetime of a Conductor workspace.
- Very specific: line 62
After that merge, reuse the same workspace/worktree when convenient.
- Very specific: line 79
Do not write tests unless the user asked for them.
- Distinctive: line 84
When the user does ask for tests, follow the rules in the sections below for where they live and what they must prove.
- Very specific: line 99
Never put the desktop app in front of the person.
- Very specific: line 117
When a review is run, address every actionable finding and rerun the relevant checks.
- Distinctive: line 128
When a feature needs both server and UI work, development starts with the server feature: design its API and data model carefully, …
- Very specific: line 151
Before creating or changing any user interface, read and follow DESIGN.md.
- Distinctive: line 159
Use flexbox for layout almost all of the time — it is the default for every row, column, stack, toolbar, and centered box.
- Very specific: line 174
Never use JS-driven scrollbars.
- Very specific: line 182
Every icon is a font glyph from the two families Happy itself uses — Ionicons and Octicons, vendored under …
- Very specific: line 188
Do not hand-draw glyphs, do not add an inline-SVG icon component, and do not change what backs Icon.
- Very specific: line 205
Every new built-in plugin must include its own newly generated plugin.png whose visual identity matches that plugin.
- Distinctive: line 210
Every surface must stay current on its own.
- Very specific: line 236
Treat a change of store identity as an explicit lifetime boundary.
- Distinctive: line 239
Read changing values from props or the current external-store snapshot.
- Distinctive: line 257
Treat conditional branches and changing keys as potential mount/disposal boundaries.
- Very specific: line 263
When browser tests for a store adapter or repeated-row projection are requested, they must prove the lifecycle contract, not only visible …
- Very specific: line 273
When asked to “sync to main,” commit the current work, fetch and rebase it onto the latest origin/main, then push the resulting HEAD to …
- Very specific: line 278
Keep sync validation proportional to the packages that changed.
- Very specific: line 299
Every retried mutation must reuse one idempotency key across all attempts.
- Distinctive: line 317
Keep public snapshot, action, output, and private-input contracts as explicit, closed TypeScript trees.
- Distinctive: line 334
Do not mirror local state across stores merely to keep them synchronized.
- Distinctive: line 347
Keep authoritative input separate from public local actions.
- Very specific: line 352
When tests for races and failure handling are requested, write them against the programmable fake server in happy-desktop-state/testing, …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Instructions
Notice
Absolutely never change a host process of electron app without double confirmation from a human - this breaks clous updates.
GitHub Actions
Never create GitHub Actions workflows, or add automatic triggers (push,
pull_request, schedule) to existing ones, without explicit user instruction:
Actions minutes cost real money. Validation runs locally.
Master plans
Read master-plans/00-master-plan.md first,
before any other work. It explains how master plans are used and maintained.
Then find every plan in master-plans/ relevant to your task
and read each one in full before starting.
Master plans are dictated by the user and describe where the product is going,
in what order, and what counts as done. They outrank conclusions drawn from the
existing code. Do not create, edit, rename, or delete a file in master-plans/
unless the user explicitly asks for that change in the current task. When the
code contradicts a master plan, report the contradiction instead of revising the
plan.
Releases
Read docs/releases.md before release work. Desktop and renderer releases default
to previews; production must be explicit. Use the existing main-dispatched,
single-run workflows with notes, preserving signing and source checks.
Versions are CalVer and always computed, never chosen: stable YYYY.M.C,
preview YYYY.M.C-preview.N (UTC year and month, month not zero-padded). C
counts the month's stable releases; a preview takes the next stable C and the
next N for it. Dispatch release workflows without a version and let
scripts/release/desktopVersion.mjs derive it from the v* tags. Do not type,
guess, or reuse a version, return to X.Y.Z numbering, drop the -preview.N
suffix, zero-pad the month, or bump source manifests: they stay at 0.0.0 and
release builds stamp the computed version. See docs/releases.md → "Versions".
Renderer-only requests never implicitly ship a native app. Do not release, deploy,
restart, or push as a side effect of implementing release tooling.
Project
Happy (2) is a desktop work and coding app that evolves by adopting itself. It is desktop-only: do not assume mobile use, add mobile-specific behavior, or adapt layouts for mobile viewports.
Before hardcoding any product behavior an agent can affect, ask: could this just be a prompt? If so, it belongs in the agent's prompt, not the client. Layouts, section names, ordering, and "X always sits at the top" are guidance the agent follows and the person can override; the client draws what the agent and the person decided.
Feature development workflow
Treat each feature as one atomic, independently mergeable change, not as the lifetime of a Conductor workspace. A worktree may contain only one unmerged feature at a time; finish and push the current feature before starting the next one.
After that merge, reuse the same workspace/worktree when convenient. It does
not need to be recreated, checked out directly on main, or have a branch tip
identical to origin/main before work starts. The next feature must remain a
separate, reviewable diff and must be rebased onto the latest origin/main
during the normal sync-to-main workflow. Create another Conductor workspace
only for parallel work or when another feature must begin while the current one
is still unmerged.
Build each feature in isolation, with an explicit boundary between its server and UI work. Do not mix unrelated features into the same implementation.
Small UI work does not need this ceremony. For a quick visual or interaction change, just make it: if it typechecks, builds, and renders correctly, it is done.
Tests
Do not write tests unless the user asked for them. No unit tests, no gym
tests, no browser tests — not "just one to be safe", not as a side effect of
touching a file that already has tests. Verify your change by building and
running it instead.
When the user does ask for tests, follow the rules in the sections below for where they live and what they must prove. Keep existing tests passing for the code you touch.
The happy-desktop-ui suite is very slow — it drives real browsers and takes many
minutes. Do not run it more than once, and do not run it at all unless you
actually need its result. pnpm check (and therefore pnpm release) already
runs it, so never run the package suite separately alongside one of those. When
you only need to inspect one failure, run that single test file instead of the
whole package.
On macOS, request reviewed full-access execution before running any real-browser Playwright suite; otherwise the inherited sandbox crashes the browsers and triggers native crash dialogs.
Never put the desktop app in front of the person. Every gym, recording, or
other agent-driven Electron launch goes through gymElectronLaunch in
happy-desktop-gym and records video with gymElectronVideoRecord: the window
is real but hidden, never visible or focused, and has no Dock tile. Do not call
Playwright's _electron.launch or recordVideo directly, page.bringToFront(),
open, osascript, or desktop capture. See
master-plans/10-gyms.md and the gym README's
"Hidden windows".
Review
Review is optional for every edit and never gates pushing or merging. An independent review is worth requesting for sizable or critical work — security or authorization behavior, durable data or migrations, server API contracts, complex concurrency, substantial UI flows, or broad/high-risk diffs — and only once the implementation is complete. Routine mechanical, small, and low-risk changes rely on the implementer's own verification.
When a review is run, address every actionable finding and rerun the relevant
checks. Then run repository-wide pnpm format and sync the task to main
using the workflow below.
Backward compatibility is not a default product requirement. Prefer the clean new-server/backend and UI design unless the current task explicitly requires a compatibility or data-preservation contract; do not add legacy branches solely to preserve obsolete behavior.
Order of work
When a feature needs both server and UI work, development starts with the server feature: design its API and data model carefully, implement it, then build the UI on top of the finished server behavior. Favor simple, durable boundaries that will not create foreseeable maintenance or compatibility problems. Do not add abstractions, options, or behavior solely for hypothetical future use cases; solve the feature currently being built well.
End-to-end data modeling
We own the full stack from agent to app. Data within this owned stack must be modeled explicitly and carried through authoritative typed contracts end to end. Do not use heuristics, inference, parsing conventions, shape detection, or fallback guesses to reconstruct data that one owned layer could have provided to another.
Heuristics are allowed only at boundaries involving something we do not own and cannot give an explicit contract, such as detecting the type of an external file. Isolate the heuristic at that boundary; after detection, represent and transport the result explicitly through the owned stack.
Design system
Before creating or changing any user interface, read and follow DESIGN.md.
It is the authoritative contract for component ownership, blueprint coverage,
layout dimensions, icon preparation, optical alignment, and cross-browser
rendering tests. Reusable visual components belong in happy-desktop-ui; application
packages may only compose them and supply product state and event handlers. Its
rendering-test rules describe how such tests are written when they are asked
for; they do not override the "Tests" section above.
Use flexbox for layout almost all of the time — it is the default for every row,
column, stack, toolbar, and centered box. Use another mechanism (CSS Grid, and
only for a genuine two-dimensional grid) solely when flexbox cannot express the
layout at all; never fall back to floats, inline-block hacks, or layout tables.
See DESIGN.md → "Layout with flexbox".
Nothing jumps. An element that is not being moved by the person never changes
position, except one deliberate glide to its new slot; nothing moves after a
drop settles; confirmations and echoes never move anything. This outranks every
other visual rule. Any change to drag, drop, reorder or list reconciliation must
keep packages/happy-desktop-ui/src/Sidebar.chaos.test.tsx passing in all three
engines, which is this rule's enforcement. See DESIGN.md → "Nothing jumps".
Scrollbars
Never use JS-driven scrollbars; always native scrollbars styled with CSS. Every
scrollport keeps the browser's own bar, painted by the one shared rule in
packages/happy-desktop-ui/src/styles/scrollbar.css. Do not hide a native bar
to draw a DOM thumb, position a thumb from scroll events or observers, or toggle
scrollbar visibility from script. See DESIGN.md → "The scrollbar".
Icons
Every icon is a font glyph from the two families Happy itself uses — Ionicons
and Octicons, vendored under packages/happy-desktop-ui/src/assets/fonts/ and
addressed through the generated name maps in src/vectorIcons/. Use Icon for
the curated house vocabulary and Ionicon/Octicon for a specific upstream
glyph. Adding an icon means picking the upstream glyph a name maps to.
Do not hand-draw glyphs, do not add an inline-SVG icon component, and do not
change what backs Icon. A font glyph is already box-centered, so never assert
an ink centroid on one; prove it with real ink and box geometry instead. If you
believe the icon substrate itself must change, stop and ask — that is a
product-owner decision, not an implementation detail, and swapping it silently
red-lined 50 test files for five days once already. See DESIGN.md → "Icon
systems".
Exception (authorized by Steve, 2026-11-12): the Gen UI renderer in
packages/happy-desktop-ui/src/genUi draws its glyphs from the shared Gen UI
icon set bundled in src/genUi/shared/icons; the rest of the app stays on
Ionicons and Octicons.
Generated images
Whenever a feature needs a new raster image, generate an original image for
that feature. Never copy or reuse another feature's image as a placeholder.
Every new built-in plugin must include its own newly generated plugin.png
whose visual identity matches that plugin.
Reactivity
Every surface must stay current on its own. A manual "Refresh" button (or any control whose only job is to re-fetch) is not allowed — if the user has to ask for fresh data, the screen is broken. Data updates arrive one of two ways:
- Full reactivity via the realtime SSE stream. The primary, focused surface
reconciles live: subscribe to sync events and reconcile durable state through
the
happy-desktop-statedifference APIs (realtime events are delivery hints, never durable state — see "Client state principles"). This is the default; prefer it. - Polling only for a secondary surface that has no realtime channel yet. While that surface is on screen, poll every few seconds; stop polling the moment it unmounts or is no longer visible so a backgrounded view does no work. Polling is a stopgap — if a surface matters enough to keep open, give it SSE.
Asynchronous server work (a build, an export, a job) must stream its status changes to the UI through the same mechanism, not wait for a user-initiated reload.
React UI reactivity and identity
React surfaces render immutable happy-desktop-state snapshots. Keep component and
DOM identity stable across ordinary store notifications so focus, selection,
scroll, measurements, and local UI state survive updates.
- A framework adapter for a
happy-desktop-statesurface owns one coarseuseSyncExternalStoresubscription per materialized store. Repeated rows must not subscribe to the product store individually. - Treat a change of store identity as an explicit lifetime boundary. A changing
React
keymay remount a tree for a genuinely new store. Notifications from the same store must retain existing component and DOM identities. - Read changing values from props or the current external-store snapshot. Do not mirror props or product snapshots into component state, and do not use an effect to keep duplicated state synchronized.
- Let React Compiler handle ordinary render memoization. Add manual memoization only for a measured identity or performance contract, and document that contract beside the code.
- Product state belongs in
happy-desktop-state.happy-desktop-appmay not useuseStateoruseEffect; reusablehappy-desktop-uicomponents may own narrowly scoped local UI state, but may not useuseEffect. Use an event handler, external-store subscription, ref callback, or render-time derivation instead. An imperative browser integration may useuseLayoutEffectonly when no declarative or event-driven boundary exists, with complete cleanup. - Key reorderable entity collections by stable entity ID, never by array index. Preserve references for unchanged entities; changing one field must update its row without replacing that row's DOM node or its siblings.
- Thousands of repeated rows may have normal render bindings, but they must not mirror authoritative product state, start transport work, or own server synchronization. One surface subscription fans out through immutable props.
- Treat conditional branches and changing keys as potential mount/disposal boundaries. Do not place focused controls or stateful panels behind a changing key unless resetting them is the product behavior.
- Virtualize collections that can contain thousands of entries. Efficient reconciliation does not make thousands of simultaneous DOM nodes, layout boxes, images, or observers free.
- When browser tests for a store adapter or repeated-row projection are
requested, they must prove the lifecycle contract, not only visible text:
assert child mount count,
subscription cleanup, exact DOM-node identity,
document.activeElement, selection/local value where relevant, and open local panels or menus across local and authoritative store updates. Run those tests in Chromium, Firefox, and WebKit.
Sync to main
When asked to “sync to main,” commit the current work, fetch and rebase it onto
the latest origin/main, then push the resulting HEAD to main with a normal
non-force push. If main advances or the push is rejected, fetch, rebase again,
and retry until the push succeeds. Never force-push main.
Keep sync validation proportional to the packages that changed. For a
client-only diff limited to happy-desktop-app, happy-desktop-state, and happy-desktop-ui (plus
their docs, assets, or development tooling), formatting plus a typecheck/build
of the touched packages is enough; do not run server gym, server coverage, or
another repository-wide test pass solely because the work is being synced.
These UI and client-state changes cannot corrupt durable server data or
migrations. A server, schema, migration, authentication, or durable-state change
runs the existing server checks for the code it touches.
Client state principles
happy-desktop-state is the in-memory product-state boundary between application code
and the server. Keep authentication, UI framework bindings, persistence, and the
decision to create a process-global instance outside this package.
- The package receives an already authenticated low-level HTTP/realtime transport. Its public actions must not expose URLs, tokens, or wire response shapes to application code.
- Realtime events are delivery hints. Reconcile durable state through the sync difference APIs; never treat receipt of a realtime event as durable state.
- Every retried mutation must reuse one idempotency key across all attempts.
Promise actions reject with a displayable
UserError; optimistic background actions return immediately and surface terminal failure through state events. - State remains memory-only and framework-independent: immutable
get()snapshots plus typed subscriptions are the UI integration contract. - Split product state into independently constructible, on-demand surface stores selected by UI lifetime and update cadence. A store constructor must not open transport, persistence, timers, or authentication resources. Repeated rows and entities must not require one store or subscription each.
- A surface store may publicly expose synchronous, local
voidactions such astextUpdate,attachmentAdd,attachmentRemove, ortextSubmitalongsideget()andsubscribe(). Name every action entity-first in lower camel case, including actions on an already scoped store. Each action mutates only that store first, then may emit a typed output event to the listener supplied by its creator. Name output and private-input variants entity-first as well, for exampletextUpdated,textSubmitted,attachmentAdded, anddisplayNameSaveSucceeded. The listener is optional and defaults to a no-op, so the same concrete store works standalone in Blueprint and tests. - Keep public snapshot, action, output, and private-input contracts as explicit,
closed TypeScript trees. For statically known product fields, do not expose
generic
getField/setField/updateFieldAPIs, string paths,keyofmutation dispatch,unknownvalues, or catch-all record payloads. Give every editable field its own typed entity-first actions and event variants, such asdisplayNameUpdate(value: string)andnotificationLevelUpdate(value: NotificationLevel). Genuinely dynamic collections remain equally strict: use their branded ID type and concrete value type, for exampleReadonlyMap<MessageId, MessageSnapshot>; dynamic cardinality never permits an untyped key or value. - Store updates and subscriptions are synchronous and require no transaction
API. A local action performs its store's
set, then emits output in the same call stack; the owner may synchronously update other already materialized stores before the action returns. Independent stores notify independently and have no cross-store atomic-snapshot contract. State that must be observed atomically belongs in one surface store. Do not create a missing store merely to deliver an event. - Do not mirror local state across stores merely to keep them synchronized. An output event may feed persistence or a server queue without changing another UI store. Update another already materialized store only when that surface actually renders a projection changed by the event; keep common high-frequency actions on one owning store.
HappyStatefeature stores are the only client product-state system. Do not reintroduce an aggregate root snapshot, generic operation/result facade, compatibility shim, adapter, dual-write path, event bridge, or snapshot mirroring between surfaces.- Framework adapters may batch or schedule rendering after several synchronous store notifications, but state correctness must not depend on one render or DOM commit. A subscriber or derived value that requires a coherent combination must read one owning surface store rather than join independent stores.
- Keep authoritative input separate from public local actions. Server results, persistence results, differences, and reconciliation enter through a private typed writer and must not re-emit store output events. Public actions may express intent or optimistic local state, but must not fabricate confirmed, saved, pinned, or otherwise server-authoritative state.
- When tests for races and failure handling are requested, write them against
the programmable fake server in
happy-desktop-state/testing, and cover the same boundary against the real in-memory server throughgym/state.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

