metrists

  Metrists

---

Metrists publishes text artifacts — written and refined with the help of AI agents — from markdown source. The primary way to work with Metrists is the desktop app — a local editor that facilitates you and your agents collaborating on the same files in real time.

This repo also contains the Metrists CLI, which powers the desktop app under the hood (builds, publishing, agent pairing) and remains fully usable on its own if you'd rather drive things from the terminal.

Getting Started

The fastest way in is the desktop app: download it from metrists.com, open a folder, and start writing — agents can read and edit the same files you do.

Prefer the terminal? Create a new directory and run:

npx metrists watch --noob

Modify the markdown files. You can then publish:

npx metrists publish

That's it. You can push your files to a repository and connect your CI/CD pipeline. From now, every time you push to your repository, Metrists will automatically publish your artifact.

Using AI agents from the web app (metrists agent)

The Metrists web app can drive AI coding agents (Claude Code, OpenCode, …) that run on your machine. The browser can't spawn processes, so a small local worker does it for you:

npx metrists agent

This starts a local worker in the current folder, prints a QR code + pairing link, and opens your browser to pair. The agent runs on your machine and edits files directly; the web app talks to it over an end-to-end-encrypted connection (the pairing code never reaches any server — it rides the link fragment). Leave it running while you work; Ctrl-C stops it.

This is the same pairing flow the desktop app uses under the hood — the CLI command is there for anyone who wants it without installing the app.

Options:

Flag	Purpose
--dir <path>	Folder the agent operates on (default: current dir).
--port <n>	Pin the local WebSocket port (default: ephemeral).
--app-url <url>	Web app to open/pair with (default: https://app.metrists.com; or set METRISTS_APP_URL).
--no-open	Don't auto-open the browser.
--tunnel-url <url>	Pair over a wss:// tunnel you provide (ngrok, Tailscale Funnel, your own proxy) instead of ws://127.0.0.1 — for reaching the worker from another device.

The worker only ever spawns the harnesses it already knows about (Claude Code / OpenCode / …) and never runs anything received over the connection. See the app's "Connect a machine" dialog for pairing.

Documentation

Follow the full documentation to get started building your own project.

Features

• Live reload while in watch mode
• Fast and incremental builds
• Static web export
• .epub export

Roadmap

See our docs for more information about where we are taking metrists.

Contributing

This package is a beginner-friendly package. If you don't know where to start, visit Make a Pull Request to learn how to make pull requests.

Please visit Contributing for more info.

Code of Conduct

Please visit Code of Conduct.

---

License

MIT