Paper Mono

Turn a Paper reference into a sharp implementation brief, get explicit approval, then carry it faithfully into production code.

Paper Mono is a local-first CLI for Paper Desktop. It reads the document open in Paper through Paper's local MCP server and runs the design-to-code specialist on your machine. No Paper Mono account, Convex backend, hosted workspace, or Paper Mono cloud service is required.

Quick start

You need Node.js 22.19.0 or newer, Paper Desktop, a Paper document open, and user-installed fd (or fdfind) plus rg on PATH. On macOS, install the search tools with brew install fd ripgrep; on Debian or Ubuntu, use apt install fd-find ripgrep. Paper Mono checks these prerequisites before specialist startup and never downloads executable dependencies automatically.

Open a terminal in the destination repository root before starting the specialist. That current working directory becomes the brief's project boundary for inspection, approved edit/write paths, command approval, and verification. An @file attachment must be a regular file inside that repository after symlink resolution; its contents are sent to the selected model provider as prompt context. Edit and write tools enforce approved project paths. An approved shell command must exactly match the brief and launches from the repository root, but it runs in the normal host shell—not an operating-system sandbox. Review every proposed command for absolute paths, parent traversal, redirection, subprocesses, and package lifecycle scripts that could reach outside the repository.

# Run the complete specialist now; no global install required
npx paper-mono

# Keep the short `paper` command
npm install -g paper-mono
paper

On first use, npm may ask you to confirm the temporary package install. Inside Paper Mono, enter /login and choose a supported model provider. Then tell it the outcome you want. Before the editor becomes ready, Paper Mono silently grounds the launch repository and up to 200 discoverable Paper files; the default face shows the selected workflow, exact local project root, and one honest readiness line. If the first request names a resolvable project outside that root, Paper stops before reference exploration, keeps the workflow unchanged, and prints shell-safe relaunch commands for the target repository. Ambiguous prose is not guessed: Paper asks you to confirm the target before high-volume reads. Use npx paper-mono --verbose when you need detailed startup resources and provider diagnostics.

The default workflow is deliberately gated:

1. confirm the exact Paper file, page, artboard, and relevant nodes;
2. inspect the reference and destination project without mutation;
3. produce a structured implementation brief with scope, uncertainty, and verification;
4. wait for the exact APPROVE PAPER BRIEF <brief-id> phrase;
5. implement only the approved scope through the destination's existing design system;
6. verify the real product route, viewport, state, and interaction—not only the Paper reference.

Closing or cancelling before approval leaves project files and Paper unchanged, except for a deterministic paper screenshot --out <file> export you explicitly requested.

What it is—and is not

Paper Mono is a local Paper specialist for humans and agents. It provides deterministic document reads, guarded model-powered chat, diagnostics, audit-only analysis, and approved Paper refinement.

It is not a hosted design service, a Paper replacement, a Chrome automation tool, or a promise to copy a reference's branding or CSS. It does not require the private Mono Factory UI, Rust TUI, backend workflows, Doppler, Bun, pnpm, GitHub Packages, or a source checkout.

Three supported paths

Reference-to-code is the default. Two explicit alternatives are available:

paper --audit-only
paper --copilot

• --audit-only is permanently read-only and can never unlock mutation.
• --copilot can propose guarded work inside Paper, including a Paper-only brief with empty project paths and commands, but the same brief approval boundary still applies.

paper_create_page and paper_open_page are real package-owned tools that stay gated until an exact approved brief binds the page operation. They are intentionally inactive before approval; Paper does not treat them as unsupported or expose them early.

paper --list-models is a model-inventory helper, not a fourth workflow.

The quick-start npx paper-mono command runs the same complete specialist as paper. It uses npm-managed cache and may create normal local state under ~/.paper/agent; it only avoids a global package install. The public artifact carries the Pi runtime with it, so npm installs only four small runtime dependencies instead of reifying Pi's full nested dependency tree on every fresh cache. The package exposes equivalent paper and paper-mono binaries. Documentation uses paper as the canonical command after installation.

Paper Snapshot

Paper Snapshot is Paper's separate Chrome extension. Get it from Paper's official page to bring a web reference into Paper. Paper Mono reads the resulting Paper nodes; it does not operate Chrome, run the extension, or capture the source site itself.

Start broad only long enough to resolve identity, then narrow: confirm the file and selection, inspect one artboard or small subtree rather than a Snapshot-scale document root, request a scale-1 screenshot, and read JSX or computed styles only for nodes needed by the current decision. Tree summaries have a dedicated 24 KiB text budget and suppress the whole response when it is exceeded, returning a targeted retry instead of partial structure. See the Paper MCP boundary for the large-Snapshot recovery path.

Deterministic commands

paper --help
paper --version
paper --about-json
paper doctor --json
paper info --json
paper selection --json
paper tree --json
paper node "replace-with-node-id" --json
paper screenshot --out reference --json

Machine-readable commands emit JSON without decorative stdout. Screenshot exports require an explicit --node or exactly one current selection, append the verified image extension when needed, and refuse to overwrite an existing path. Deterministic owner commands reject unknown subcommands, and the specialist rejects unsupported flags, invalid option values, path-like --session values, and conflicting session actions with a nonzero exit and an actionable error. Positional text on paper is prompt input unless its first word is a reserved owner command: show, info, selection, tree, node, screenshot, doctor, page, or help. Put -- before option-shaped or reserved-word prompt text; for example, paper -- --version or paper -- info about this layout.

Model authentication

Run paper, enter /login, and choose a provider. You may instead use that provider's documented environment variable. paper --list-models shows available model IDs; Paper Mono never prints credential values in diagnostics.

Credentials, settings, and sessions stay under ~/.paper/agent by default. Set PAPER_CODING_AGENT_DIR before the first run to use another local directory. --session <id> accepts a verified session ID only; public v1 rejects path-like values before session activation. Use --fork <path-or-id> when you explicitly intend to import a transcript into a new session scoped to the current project. --session-dir <dir> overrides session storage and lookup only; it may place transcripts outside the agent home and uses the runtime's explicit-directory lookup instead of Paper Mono's hardened implicit-session verification path. Use only a directory you trust. A resumed session is mutation-locked again until the current brief is reconfirmed.

Resume a previous interactive session with:

paper -r

Privacy and network boundaries

Paper document reads travel over the loopback MCP endpoint at 127.0.0.1. Paper Mono disables the inherited install ping, automatic version polling, provider-attribution telemetry, and executable downloader before startup; it adds no product telemetry or hidden backend and does not silently phone home. The public TUI also disables inherited /debug, /export, /import, and /share commands, so a locked session cannot write a raw debug log or export, replace itself from a file, or send a transcript to an external sharing service. Generated provider metadata names the current project as <repository-root> and uses repository-relative labels for attached and context files; Paper Mono does not add the absolute local project path to the model request. User-authored prompts, attached file contents, imported instructions, tool results, or approved commands can still contain paths. Prompts, relevant code/reference context, and tool results needed for reasoning are sent to the model provider you select, so that provider's privacy and retention terms apply.

Use PAPER_OFFLINE=1 or paper --offline to disable startup network operations. Local deterministic Paper reads remain available, but model work still requires a reachable configured provider unless you use a local one.

Compatibility and current limits

• Node.js 22.19.0 or newer is required.
• fd (or fdfind) and rg must already be executable on PATH before paper starts. Missing tools fail with install guidance in both default and offline modes; Paper Mono does not acquire them.
• Paper Desktop must be running with a document open for live MCP reads.
• Clean-room installation and offline CLI behavior are exercised on Apple-silicon macOS with Node.js 22.23.1. That receipt does not claim live Paper Desktop integration on any operating system. The package declares no OS restriction, but Linux and Windows live integration remain unproven.
• A static Snapshot cannot prove original motion, hidden application state, backend behavior, or inaccessible assets. The brief labels those details as unknown instead of inventing them.
• Paper's current MCP surface does not expose every possible page-management or design operation. Unsupported work is reported rather than routed through a raw-provider bypass.
• Public npm distribution comes first. Public source is intentionally deferred until the installed product has stabilized, so there is no source-repository link yet.

Troubleshooting

• Paper is closed or no file is open: open Paper Desktop and a document, then rerun paper doctor --json. Reinstallation is unnecessary.
• MCP is unreachable: confirm the document is open and that another process is not interfering with 127.0.0.1:29979, then rerun doctor. Restart Paper only if the local endpoint still does not recover.
• Model authentication is missing: start paper, enter /login, or configure the selected provider's documented environment variable. A missing key should produce guidance, not a stack trace.
• The Snapshot is too large: select or name one artboard, rerun bounded inspection, use scale 1, and request JSX/styles for a smaller subtree. Paper Mono suppresses over-budget rich parts whole; it never returns partial JSON, JSX, or base64.
• The requested project is outside the launch root: use the exact relaunch receipt Paper prints. It keeps the active mode unchanged, while also showing --copilot for Paper-only work and --audit-only for read-only inspection. Paper never changes cwd or workflow silently.
• The wrong file, page, or artboard is active: run paper info --json and paper selection --json, switch to the intended target in Paper, and request a fresh brief. Existing approval does not carry across target drift.
• The imported structure is malformed or incomplete: provide a narrower node or screenshot and let the brief record unsupported details explicitly.

The CLI reference contains full recovery steps and exit behavior.

Uninstall

npm uninstall -g paper-mono

Uninstalling the package intentionally leaves ~/.paper/agent in place so sessions and provider settings are not destroyed. Review that directory and remove it manually only if you also want to erase local Paper Mono state. If you set PAPER_CODING_AGENT_DIR, review that directory instead. Any directory passed with --session-dir is separate local state and must be reviewed or removed separately.

Support and security

For setup help, compatibility reports, or reproducible failures, email [email protected] with the Paper Mono version, Node version, operating system, command, and redacted output. Never send provider keys, auth files, or private document contents.

For a possible security or unsafe-mutation issue, use the same address with paper-mono security in the subject and follow the private-reporting guidance in SAFETY.md.

Public contract

See the CLI reference, Paper MCP boundary, runtime and privacy model, safety model, release notes, dependency inventory, and third-party notices. The package does not link to a private source repository or nonexistent public issue tracker.