Sonorance

Sonorance is a local web application for reviewing and addressing work stored in Markdown files. It provides an Explorer, editing, search, git diff, inline comments, and a comment bridge for agents.

Run it

Node.js 22.5 or newer is required.

npx sonorance init
npx sonorance serve /path/to/folder --open

# From a source checkout:
npm install
node src/cli.mjs init
node src/cli.mjs serve /path/to/folder --open

Add --file "<project-relative-path>" to either serve command to open a specific Markdown artifact immediately.

Sonorance asks the operating system for an available port by default and records the selected port in .sonorance/local/serve.json for the comment bridge. Pass --port <n> or set DELIBERATE_PORT only when you need a fixed port.

Every .md file appears in the Explorer, along with only the folders needed to reach Markdown descendants. Frontmatter is preserved and hidden from the editor, links open separately, images resolve relative to their file, and autosave writes to disk. Git repositories also expose changed files, per-file diffs, and guarded discard.

Project state

.sonorance/
  config.json          project identity and settings
  plugins.json         enabled bundled plugin ids
  sources.md           hand-editable grounding sources and repository-safe access hints (never credentials)
  local/
    state.json         machine-local tabs and Explorer state
    comments.jsonl     machine-local inline comments
    serve.json         running-server discovery

Only .sonorance/local/ is disposable and gitignored.

Runtime and comment-bridge diagnostics are written locally to ~/.sonorance/sonorance.log (or $SONORANCE_HOME/sonorance.log). Bridge failures print this path and preserve server error details there.

node src/cli.mjs source add <location> ["<description>"]
node src/cli.mjs source list
node src/cli.mjs source remove <location>

Review workflow

1. Select text and leave a comment.
2. Run /sonorance address in the agent.
3. The agent reads the open comments, answers or edits the referenced file, and resolves completed items.
4. Review the result in Document or Diff mode.

The low-level bridge is:

node src/cli.mjs comment list
node src/cli.mjs comment <commentId> resolve [--note "…"] [--revised]

Transport, HTTP, payload, server, and response-schema failures exit nonzero.

Plugins

Sonorance resolves enabled bundled plugins from .sonorance/plugins.json:

{ "plugins": [{ "id": "deliberate", "enabled": true }] }

Plugins contribute document kinds, record storage, and gitignore behavior to the generic engine. They cannot load executable paths from vault configuration, replace the engine, or change the application identity.

import { startServer } from 'sonorance';
import { resolveEngine } from 'sonorance/plugins';

const engine = await resolveEngine(process.cwd());
const { port } = await startServer({ engine });

port is the available port selected by the operating system; pass an explicit port when embedding Sonorance behind a stable local endpoint.

Privacy and telemetry

Privacy is foundational to Sonorance. Anonymous usage telemetry is on by default in the official npm package so we can understand which features help, improve performance, fix issues, and keep developing the product.

Sonorance collects only a small amount of content-free data: feature usage, performance measurements, and redacted error signals. All exported telemetry is anonymized, allow-listed, and stripped of sensitive information. Sonorance never logs your work—not even project, file, or folder names. File and document contents, titles, paths, prompts, completions, error messages, and stack traces always stay private.

Telemetry is written to a local JSONL audit trail before export so you can inspect what Sonorance records. You can turn telemetry off at any time in Settings, through the CLI/environment, or with a committed project policy. Feedback is separate and is sent only when you explicitly submit it.

Source checkouts have no embedded destination. To export from a source checkout or override the package destination:

export APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=…;IngestionEndpoint=https://<region>.in.applicationinsights.azure.com/"
# Or:
export SONORANCE_OTLP_ENDPOINT=https://collector.example

SONORANCE_TELEMETRY=off, DO_NOT_TRACK=1, and a project policy with "telemetry": false disable passive telemetry export. CI, NODE_ENV=test, and SONORANCE_AUTOMATION=1 are harder safety boundaries: they disable every network export, including explicit feedback, while retaining local mirrors needed for tests.

Repository map

• src/server/ — local HTTP API, SSE, git, files, comments, and telemetry ingestion.
• src/ui/ — source shell/app, editor integration, Markdown conversion, comments, diff, and interaction plugins.
• src/engine-default.mjs — generic folder engine.
• src/plugins.mjs — bundled-id additive plugin composition.
• src/plugins/deliberate/ — the Deliberate contribution and file-backed record store.
• src/cli.mjs and src/grammar.mjs — CLI implementation and command/filesystem grammar.
• skill/ — the shipped /sonorance skill.
• test/ — engine, server, CLI, telemetry, and jsdom UI coverage.

Development checks

Run npm test for the complete package suite. For UI runtime or layout changes, also run npm run benchmark; it drives a local production build in Chrome, verifies search alignment, Explorer scroll retention, delayed editor activation, and enforces median startup, document-open, typing, scrolling, long-task, and bundle-size budgets. Set CHROME_PATH when Chrome, Chromium, or Brave is not installed in a standard location. The benchmark always runs with automation telemetry isolation and writes its JSON result only when --output <path> is supplied.