Skip to content

GitHub Discussion Draft — to post on sageox/ox

This is the draft message to open a Discussion on github.com/sageox/ox/discussions before sinking serious implementation effort. Goal: confirm roadmap fit, agree on integration shape, get green light on capability constants.

Suggested category: Ideas (or Show and tell if a working prototype is ready). Suggested title:

Local audio capture / Vox-style integration interest?

Body

Hi sageox team —

I'm building Blackrim Vox (Apache-2.0, Go, open core), a local voice-to-LLM intent router. Vox captures audio from multiple sources — your own voice, in-person meetings via lapel/array mic, online calls via system audio loopback — transcribes locally (BYOK or fully local via Whisper.cpp / Ollama), and routes the resulting structured "intent envelopes" to user-configured sinks (LLMs with their own API keys, S3-compatible storage, email, bd task tracker, local file).

I'd love to integrate deeply with ox as a first-class sink. After reading through the codebase — pkg/adapterprotocol, internal/ledger/murmur.go, internal/whisper/store/, the adapter registry — the fit looks natural: Vox's intent envelopes map almost 1:1 onto MurmurFile, and the existing adapter protocol gives me a clean way to plug in. But there are four things I want to confirm with you before writing the implementation.

1. Does this conflict with your roadmap?

Your web app already records and transcribes team discussions. Are you planning to ship local audio capture in the CLI too? If yes, I'd love to contribute rather than build something parallel. If no, my integration plan is:

  • A ox-ledger sink inside Vox that writes murmurs into the local ox ledger directory (the file format from internal/ledger/murmur.go).
  • A cmd/ox-adapter-vox/ binary implementing your adapter protocol (pkg/adapterprotocol, ProtocolVersion = 1).
  • Registration entry in internal/adapter/registry.yaml pointing at the jsgerman-oss/blackrim-vox repo (so we own the release cadence; you curate inclusion).
  • Two new capability constants proposed for pkg/adapterprotocol: audio_capturer and murmur_writer. Both additive, non-breaking.

If you have a different shape in mind, I'd rather hear it now than rebuild later.

2. Trademark / branding — confirming our framing

I want to be explicit, upstream and in our docs, that Vox is a third-party adapter, not an official SageOx product. Planned framing everywhere we mention ox:

Vox is a third-party adapter for SageOx. Not affiliated with SageOx Inc.

Anything you'd want changed about that wording? Is your trademark policy documented somewhere I should link to?

3. Ledger write performance — coordinating with the daemon

I noticed internal/daemon/ handles ledger writes and IPC, and that ledger.WriteMurmurRaw() exists specifically to let the daemon delegate file I/O. Per-envelope git commits would clearly be a non-starter (repo bloat + slow GitHub sync). My plan:

  • Write murmur files immediately (file I/O is cheap, this is what enables real-time team-context updates).
  • Batch git commits, default every 30 seconds, configurable.
  • Never auto-push — that's the user's choice or your daemon's choice when it's running.
  • When the ox daemon is reachable, defer to it via the adapter protocol IPC rather than writing files directly. Direct file writes are the fallback when the daemon isn't running.

Is 30s a sensible default for the commit interval? Are there other contention concerns I'm missing (file locks, sparse-checkout edge cases, parallel writes from multiple adapter instances)?

4. Versioning compatibility — locking down the contract

I plan to declare protocol_version: 1 in Vox's adapter and gate on it strictly. A few questions:

  • What's your expected cadence for protocol bumps? I'd like to plan around at least one stable v1 release window matching Vox's v1 lifetime.
  • If pkg/adapterprotocol bumps to v2 with a breaking change, do v1 adapters get a deprecation window, or is the cut immediate?
  • The murmur SchemaVersion (currently "1") is versioned independently — same question for it.

Capability constants — small PR ask

Two new constants in pkg/adapterprotocol:

const (
    CapAudioCapturer = "audio_capturer"   // Adapter captures live audio
    CapMurmurWriter  = "murmur_writer"    // Adapter writes murmurs into the ledger
)

Both additive (no existing adapter declares them). Happy to send the PR when you green-light the integration shape.

What I'm asking for here

Just a thumbs-up (or pushback, or "let's call") before I sink the implementation effort. The Vox design has already locked the capture/v1 and sink/v1 contracts so an ox-ledger sink slots in cleanly — I just want to make sure we're not building at cross-purposes with whatever local-audio work you may have planned.

The full integration design lives at docs/integrations/ox.md in the Vox repo if you want the deep-dive version.

Thanks — really love what you're building. The "adapter binary + NDJSON protocol + git-tracked ledger" architecture is exactly the kind of disciplined plumbing the agentic-coding ecosystem has been missing.

— Jay github.com/jsgerman-oss

Status / send checklist

  • [ ] Verify Vox README is public and crawlable before linking
  • [ ] Confirm docs/integrations/ox.md is committed to main branch
  • [ ] Pick Discussion category (Ideas vs Show and tell vs General)
  • [ ] Post under jsgerman-oss GitHub identity
  • [ ] Subscribe to the thread; cross-link into Vox repo issue tracker if a Discussion conversation begins
  • [ ] If the team prefers email / a call, capture the outcome here and mirror back to this draft so the audit trail stays in the repo