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 coding 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.

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
  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 coding 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());
await startServer({ engine, port: 7777 });

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, CI, and a project policy with "telemetry": false all disable export.

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.