Getting started

Prerequisites and installationCopy Anchor Link

Use Node.js 22.12 or newer with ffmpeg and ffprobe available on PATH. Guildscribe checks these tools but does not install them. Capture does not require a model or transcription server.

For users with access to the private source repository:

git clone https://github.com/twocentinc/guildscribe.git
cd guildscribe
npm ci
npm run build
node dist/index.js version
node dist/index.js help

There is no published npm package as of November 9, 2026. Do not use a bare npm install guildscribe as an installation step. An owner-supplied package can be built and checked with the distribution workflow. Examples below use the checkout executable; other guides use guildscribe for an installed executable. Substitute node /absolute/path/to/guildscribe/dist/index.js when working from source.

Prepare DiscordCopy Anchor Link

Create or select a Discord application with a bot, install it in the intended guild, and grant View Channel and Connect access to each recording channel. Copy the bot token and voice channel IDs into your private initialization request. Voice channel IDs form an allowlist, not a request to record every channel the bot can access. Let participants know the bot records and retains audio before starting it.

For optional text capture, enable the privileged Message Content intent and grant View Channel and Read Message History for the selected channels. Voice-only configuration does not request message intents. Message sending and slash commands have separate requirements in messaging.

Save the bot configurationCopy Anchor Link

Create a JSON request file outside the repository using a local editor and owner-only file permissions. Its required fields are discordToken and a nonempty voiceChannelIDs array. Inspect the exact schema before entering your credential. Optional fields include ownerUserID, emptyGraceMs, hooks, and message channels. Never put a token in a command-line argument or shell history.

node dist/index.js doctor --schema init.request
node dist/index.js init --request /absolute/path/to/private-init.json --dry-run
node dist/index.js init --request /absolute/path/to/private-init.json
node dist/index.js config show
node dist/index.js doctor

Initialization validates the request locally and creates .env only if it does not already exist. Dry-run creates nothing. Remove the temporary credential request when no longer needed.

The default runtime home is ~/.guildscribe. Supply --home /absolute/path on each command for another installation. The home and configuration must be owned by you, use restrictive permissions, and not be symbolic links.

doctor checks configuration, hooks, media tools, filesystem health, and live Discord token/channel permissions. doctor --schema is offline discovery. Review all check results before starting the daemon.

Start recordingCopy Anchor Link

node dist/index.js daemon run

The daemon joins an allowed channel when a human is present and no recording is active. After the last human leaves, it waits 30 seconds by default. A human returning to that channel continues the same meeting. When the grace period ends, Guildscribe finalizes audio and can select another occupied allowed channel.

In a separate terminal:

node dist/index.js status
node dist/index.js recordings list

The daemon is long-running. Use status for health rather than expecting a finite result while it records. Stop gracefully with SIGTERM or your supervisor to preserve captured intervals. See recordings and operations for recovery and macOS startup.