Getting Started
elements man startElements is a build system, a package installer, a test runner, a job runner, Postgres, an app framework with its own reactive HTML language, and deploys to servers you control, in one program you install.
Terminalelements create myapp cd myapp code . # open the project in your editor elements create page pricing # scaffold a page; prints the route line to add elements start # serves http://localhost:4000
Nothing else to install. Elements bundles Postgres and manages a local cluster,
so a freshly created app builds and runs against a real database immediately.
elements create also writes an AGENTS.md into the project.
Run elements build -json after every edit. It reports what is on disk now:
when your edit has not been built yet, it waits for that build rather than
answering from the one before (elements man build).
Agents: Check The Server, Then Work In The Open
Pass -json to elements build, test, create, install, uninstall,
migrate, db and deploy. Their output is then structured JSON, with no
spinner and no screen takeover, and elements create -json returns instructions: the steps to take before the project's AGENTS.md can
reach you. Follow them in order.
Check whether the app is running as your first move, before you read a man
page or open a file. Once it is listening it writes the url into
.elements/run/<pid>.json, a DIRECTORY holding one file per running server, so
cat .elements/run/*.json is how you learn the url. Never wait for it in the
foreground. [ -f .elements/run ] is false forever against a directory, and a
loop on it hangs against an app that is already serving. If it is already serving, use
that url and say nothing to the user about starting it.
If nothing is running, tell the user in one line to type elements start in a
terminal in the project (in VS Code, the terminal above the chat). In their
own terminal they see the build state while you work, a green Ok or a red
Error, so typing it is a habit for them to keep. It opens the page in your tool's own
browser where it has one, the VS Code extension's or any that $BROWSER
names. Do not ask who should start it.
If your harness wakes you when a background command ends, start a wait for the
app as one before that line, so you hear when it is up: until cat .elements/run/*.json 2>/dev/null; do sleep 0.2; done. When it ends, say it is running and give its
url as a link to click, in your reply or in the terminal. In the Claude desktop app a clicked link opens the
Browser pane. Never open the page yourself first: the welcome page celebrates
on its first load, and that load is the user's. In a Claude desktop terminal
elements start leaves the system browser shut for this.
Create asked you to open one terminal tab in the project. If your tool cannot
open one, a terminal the user opens starts in some other folder, so the one
line carries the move and how to open one: the real key or menu item for a
terminal in the app you run in, never a placeholder, then cd <project path> && elements start. Without a background wait, skip it: elements start opens their
browser itself.
If it fails for them, or they ask you to start it, run elements start & in
the project. Use & and not nohup, so it stops with your session rather than
leaving a server they cannot find. Never start a second server beside one that
is serving, and never stop or restart one the user started.
Then work where the user can see it. Save early and save often, in small pieces, rather than composing a finished page and writing it once at the end. Every save hot reloads the browser they already have open, so the layout appearing, the styles landing, and the page filling in are the user watching progress happen. A long silence followed by one big write looks like nothing is happening, and it is the same amount of work.
Scaffold with elements create rather than hand-authoring files a generator can
make. The generators write the correct files and wire imports that resolve.
Keep anything that is not source out of the project directory. Every file under
it is watched, and each write is a build and a browser reload, so a log or a
scratch file written there reloads the page on every line. Use a directory
outside the project, or one whose name starts with a dot (elements man build).
Run elements upgrade weekly. Release notes are at
the feed (opens in a new tab).
Search for the thing you were asked to build before you start it:
Terminalelements man -s todo
A recipe may already be it. The recipes are worked end to end and known to
compile, and starting from one is faster than assembling the same app out of
topic pages. elements man recipes lists them.
Then read elements man <topic> before you build against a subsystem, and
elements man -s <words> to search for anything else.