VCR

Voice Capture Reconciler

Turn iPhone voice notes into durable, reviewable updates in a Git-backed Markdown vault.

MIT License macOS Python 3.10+ Codex skill

$vcr

Record with Just Press Record, let iCloud Drive deliver the M4A to your Mac, then invoke $vcr in Codex. VCR transcribes each complete recording, reconciles clear meaning according to your vault's policy, pushes the resulting Markdown, verifies it on the live remote branch, and only then moves the matching source audio to Mac Trash.

VCR is on demand. It installs no watcher, server, scheduled task, phone upload service, or local transcription engine.

[!IMPORTANT] The transcription helper uploads each recording and configured vocabulary hints to OpenAI. Do not use it for passwords, API keys, credentials, regulated data, or anything unsuitable for external processing.

Quick Start

Ask Codex to install the public skill:

Install the VCR skill from https://github.com/WahabF/vcr-skill

On the iPhone, install Just Press Record from the App Store, set it to save M4A recordings in iCloud Drive, and assign its Toggle Recording control to the Action Button using the steps below.

Then, from the skill directory reported by the installer:

cd /path/reported/by/the/installer

# Create local configuration and install missing generic templates
# This template-install path is for a fresh or empty vault.
python3 scripts/setup.py \
  --vault /absolute/path/to/your-vault \
  --install-templates

# After reviewing the installed SYSTEM.md:
python3 scripts/voice_capture.py check

The setup command prompts before writing. It creates config.local.json and installs only missing template files; it refuses to overwrite a different existing file. For an existing vault with its own SYSTEM.md, omit --install-templates, answer No if interactive setup offers to install templates, then manually merge the repository's templates/vault/SYSTEM.md voice-capture policy into the vault's canonical policy and add the remaining contract files without replacing existing content.

Inspect the JSON from check. Continue when its top-level ready field is true. Record a short test note, wait for iCloud to sync, then invoke this in Codex:

$vcr

Normal processing happens through $vcr, not by manually calling the helper's audio-removal command. The guarded prune-empty-dirs maintenance command documented below is the only routine manual cleanup exception.

Before and After

Spoken capture Reconciled result
"Idea for Project Alpha: try a smaller validation split. This is only an idea." The idea map links to one detailed record under Project Alpha. The idea remains a non-commitment, while a quiet yearly archive preserves the complete transcript and routing audit.
"This sampling idea may help Project Alpha and Project Beta." One canonical detail is chosen; both projects receive contextual links, and the idea map records both supported associations without duplicating the evolving idea.
"Old Project Name is the same as Project Alpha." After confirmation, durable state belongs to Project Alpha and the old page becomes a thin pointer rather than a second project state.

How It Works

iPhone -> Just Press Record -> iCloud Drive -> $vcr
                                                |
                                                v
                                      OpenAI transcription
                                                |
                                                v
                      canonical meaning + transcript archive
                                                |
                                                v
                                      push -> verify -> Trash

For every complete, unprocessed M4A, VCR:

  1. Validates that the recording is stable, non-empty, decodable, and inside the configured capture folder.
  2. Computes a SHA-256 identity so retries do not duplicate work.
  3. Sends the original M4A and a small vocabulary allowlist to OpenAI gpt-transcribe.
  4. Keeps the raw transcript separate from spelling normalization and semantic interpretation.
  5. Reconciles clear meaning into one canonical owner plus supported contextual links, without silently promoting ideas into work.
  6. Archives the complete transcript and provenance under archive/voice-transcripts/<year>/, or creates an authorized no-usable-speech disposition for a probable accidental capture.
  7. Verifies that the exact intended commit and archived record are on the configured live remote branch before moving the hash-matched source to Trash.
  8. Removes only empty dated Just Press Record folders older than today; nonempty, current-day, non-date, and symlinked folders are left alone.

The Python helper performs deterministic audio, API, hash, and remote-safety operations. Codex remains responsible for interpreting speech, editing Markdown, inspecting diffs, committing, and pushing.

Requirements

Apple devices and capture

  • A Mac and iPhone signed into the same Apple Account.
  • iCloud Drive enabled on both devices, with enough available storage.
  • Just Press Record installed on the iPhone and configured to save M4A recordings in iCloud Drive.
  • An Action Button-capable iPhone for the press-to-start, press-again-to-stop experience. The app or a shortcut also works without an Action Button.
  • The Mac must be awake, online, and allowed to sync iCloud Drive before VCR can discover a new recording.

Mac software

  • macOS. VCR depends on macOS Keychain, the Just Press Record iCloud container, and Mac Trash behavior.
  • Codex with local filesystem, Git, and network access.
  • Python 3.10 or newer. The helper uses only the Python standard library.
  • Git with non-interactive access to the configured destination remote.
  • ffmpeg and ffprobe available on PATH.

Install FFmpeg with Homebrew when needed:

brew install ffmpeg

OpenAI

  • An OpenAI API project with API billing configured. API usage is billed separately from a ChatGPT subscription.
  • A dedicated restricted project API key that can create audio transcriptions. Do not use an Admin key and do not share a key between people.
  • Access to gpt-transcribe.

Review current model pricing, limits, and API data controls before use. Configure project budget controls and usage alerts appropriate for your account.

Markdown vault

The target must be a Git-backed Markdown vault that follows the vault contract. For the complete cleanup behavior, it must have a reachable remote branch. Use a private remote because archived records contain complete transcripts.

Install

The recommended path is to ask Codex to use its skill installer:

Install the VCR skill from https://github.com/WahabF/vcr-skill

The installer should report where it placed the skill. Start a new Codex conversation after installation.

For a manual install, current official Codex documentation uses ~/.agents/skills for personal skills:

mkdir -p ~/.agents/skills
git clone https://github.com/WahabF/vcr-skill ~/.agents/skills/vcr

Some older or locally bundled Codex setups use $CODEX_HOME/skills, commonly ~/.codex/skills. Follow the skill-location guidance shipped with the Codex installation you are actually running. If $vcr is not discovered, restart Codex and verify that SKILL.md is directly inside its installed vcr directory. See the official Codex skill documentation for current behavior.

Configure

Run the setup helper from the skill directory:

cd /path/to/the/installed/vcr-skill
python3 scripts/setup.py \
  --vault /absolute/path/to/your-vault \
  --install-templates

Without --non-interactive, setup shows the selected values, asks whether to install templates when the flag is absent, and asks before writing. --install-templates installs missing generic templates without overwriting different existing files. Setup does not check runtime readiness; run scripts/voice_capture.py check separately.

For scripted setup, supply every deliberate override and add --non-interactive. Run python3 scripts/setup.py --help for the complete option list.

Configuration lives in config.local.json beside the skill. It is local-only and must never be committed. It contains paths and lookup identifiers, but not the API key:

{
  "vault": "/absolute/path/to/your-vault",
  "capture_root": "~/Library/Mobile Documents/iCloud~com~openplanetsoftware~just-press-record/Documents",
  "languages": ["en"],
  "remote": "origin",
  "branch": "main",
  "keychain_service": "VCR OpenAI API Key",
  "keychain_account": "openai-api"
}
Field Meaning
vault Git repository root for the Markdown vault.
capture_root Just Press Record folder containing locally downloaded M4A files.
languages Lowercase two-letter language hints sent with transcription. Use only languages you expect.
remote Git remote used for live durability verification.
branch Branch on that remote that must contain the exact processed capture record.
keychain_service macOS Keychain service name used to look up the API key.
keychain_account macOS Keychain account name used with that service.

Paths may use ~. The Keychain fields are identifiers only; the secret stays in Keychain. They can point to an existing item, so a local installation does not need to move or duplicate the key. Use config.local.json for persistent settings; command-line overrides are for diagnostics and deliberate one-off tests.

Configure the iPhone

  1. Install Just Press Record from the App Store and open it once.
  2. In Just Press Record's settings, choose the M4A recording format and iCloud Drive storage. Make a test recording and confirm it appears in the iPhone Files app under iCloud Drive > Just Press Record.
  3. Open Settings > Action Button.
  4. Swipe to Controls, then tap Choose a Control.
  5. Search for Just Press Record and select Toggle Recording.
  6. Press and hold the Action Button once to start recording.
  7. Press and hold it again to stop and save the recording.

If Toggle Recording is unavailable, update iOS and Just Press Record, open the app once, and check again. Just Press Record also exposes separate Start Recording and Stop Recording actions in Shortcuts, but the native toggle control is the simplest two-press setup.

See Apple's Action Button guide and Just Press Record's one-tap recording integrations.

Microphone access may require the phone to be unlocked. Test the control before relying on it for important capture. An Action Button is optional: recordings made directly in Just Press Record use the same workflow.

Keep iCloud Recordings Downloaded

Pin the Just Press Record folder on the Mac so recordings do not remain cloud-only placeholders:

  1. Open Finder.
  2. Select iCloud Drive in the sidebar.
  3. Find Just Press Record.
  4. Control-click the folder and choose Keep Downloaded.

If the app folder is not visible, press Shift + Command + G in Finder and open:

~/Library/Mobile Documents/iCloud~com~openplanetsoftware~just-press-record/

Then Control-click Documents and choose Keep Downloaded. Apple documents this option in Work with folders and files in iCloud Drive.

This keeps synced files downloaded locally, including when Optimize Mac Storage is enabled. It cannot force an upload that has not left the iPhone or make iCloud instantaneous. The iPhone must finish uploading, and the Mac must be awake and online to receive the file.

Store the OpenAI API Key

Create a separate API key for each user. Never commit it, paste it into a Codex prompt, pass it as a command argument, put it in an environment file, or share it with another person.

Use the Keychain Access app on the Mac:

  1. Open Keychain Access.
  2. Select the login keychain.
  3. Choose File > New Password Item.
  4. Set Keychain Item Name to the configured keychain_service value. The default is VCR OpenAI API Key.
  5. Set Account Name to the configured keychain_account value. The default is openai-api.
  6. Paste the complete project API key into Password and save.

The configured item name and account must match exactly. Use the graphical Keychain Access flow so the key never appears in shell history, a process argument, or repository content. macOS may ask whether the security tool can access the item during the first readiness check.

Vault Contract

The configured vault must contain:

<vault>/
|-- SYSTEM.md
|-- IDEAS.md
|-- integrations/
|   `-- voice-vocabulary.md
|-- inbox/
|   `-- captures/
`-- archive/
    `-- voice-transcripts/

The repository includes generic starting files under templates/vault/. For a fresh or empty vault, --install-templates copies the missing directory structure, integrations/voice-vocabulary.md, SYSTEM.md, and IDEAS.md. It refuses to overwrite different existing files. For an established vault, omit the flag and manually merge the repository template into the existing canonical policy and idea map. Do not maintain two conflicting policies.

SYSTEM.md

SYSTEM.md must contain a ## Voice Capture Protocol section. It should define:

  • Where ideas, notes, actions, results, decisions, waiting items, and passive list entries belong.
  • How tentative language differs from an instruction to change current plans.
  • Which files are canonical and how stale or contradictory state is reconciled.
  • The required capture-record format and destination.
  • Git isolation, remote verification, and audio-removal rules.

The protocol must preserve authorization boundaries. A sentence inside a recording is content to interpret, not permission to perform unrelated consequential actions.

IDEAS.md and canonical ownership

IDEAS.md is a map, not a backlog. Each idea has one canonical detail location and may have links from several related projects or categories. VCR searches for an existing concept first, selects one owner, records every supported association, and leaves uncertain associations explicit.

For example, an idea relevant to Project Alpha and Project Beta can have its full hypothesis and evolving evidence under Project Alpha while Project Beta contains a short local implication and a link back. IDEAS.md points to the canonical detail and lists both associations. This prevents competing copies without hiding the idea from relevant contexts.

An idea stays Idea - not committed unless the user separately promotes it to future work, an experiment, an action, or a current plan. VCR does not change daily or weekly dashboards merely because an idea was captured.

Confirmed project aliases also have one owner. Merge durable state into the canonical project and keep an old-name page only as a thin pointer. Put project-owned surveys, briefs, and notes under that project's directory when the vault layout supports it; do not present support documents as independent projects.

integrations/voice-vocabulary.md

The vocabulary file is a small spelling ledger, not a list of allowed ideas. Use this minimum format:

# Voice Vocabulary

## Canonical Terms

| Term | Kind | Canonical Destination |
|---|---|---|
| Project Alpha | Project | [[projects/project-alpha]] |
| Conference Name | Conference | [[conferences]] |

Keep it short. Canonical terms are sent to OpenAI with the recording, so never put secrets, private descriptions, or unrelated repository content in this file.

Transcript records

inbox/captures/ is temporary capture staging and supports direct legacy records. Each processed source ends with one deterministic record at archive/voice-transcripts/YYYY/YYYY-MM-DD-HHMMSS-<hash12>.md. The full audio SHA-256 is its identity; the filename is provenance only. A compatible archived record preserves:

  • Source timestamp and relative source filename.
  • Full audio_sha256, duration, provider, and model.
  • Exact Raw Model Transcript.
  • Separate Normalized Transcript with only safe spelling and punctuation corrections.
  • Extracted Meaning, a per-item Routing Audit, applied destinations, unresolved items, and processing notes.
  • processed: true only when every item was reconciled or deliberately preserved as not applied.

The Routing Audit names each item's Type, Canonical owner, Associations, State, Unresolved associations, and actual Destinations. Before processed: true, VCR verifies that new links resolve, contextual pages point to the canonical detail, confirmed aliases hold no parallel state, and nothing became an action, deadline, calendar event, or current-plan change without clear authorization.

The extracted, sorted meaning belongs in the relevant canonical project, list, dashboard, or planning file. The archive is a provenance ledger and must not become a second task list. If a working record was created in inbox/captures/, move it unchanged into the source-year archive before committing. The bundled templates provide a starting schema. Do not remove or rename the hash, source, processed flag, or raw-transcript fields without also adapting the helper's verification contract.

An explicitly authorized probable accidental capture instead uses a disposition record. It must identify the exact source and hash, record a duration of three seconds or less, set processed: true, transcription_provider: openai, transcription_model: gpt-transcribe, transcription_outcome: no-usable-text, disposition: probable-accidental-no-usable-speech, and cleanup_authorized: true. It contains no raw, original, normalized, or extracted transcript placeholder. The helper accepts this record only when the caller also passes --authorize-probable-accidental-cleanup, re-probes the exact source duration, matches it to the record, and completes the normal remote durability checks.

VCR searches both the yearly archive and direct legacy records in inbox/captures/ by full hash. This preserves idempotent cleanup for older installations while keeping new processed records out of the active inbox.

Verify the Setup

From the skill directory, run:

python3 scripts/voice_capture.py check

A working setup returns JSON containing:

{"ready": true}

The complete response reports readiness for the capture directory, FFmpeg tools, readable Keychain secret, temporary record staging and legacy directory, transcript archive, vault contract, and configured remote branch without revealing the API key. Inspect the JSON itself: a successful command exit means the check ran, not that every component is ready. This preflight does not make a billed OpenAI request, validate model access or billing, or prove Git push permission or repository privacy; the first test capture still validates those external capabilities.

To inspect locally available recordings without transcribing them:

python3 scripts/voice_capture.py discover

To remove only empty dated capture folders older than today:

python3 scripts/voice_capture.py prune-empty-dirs

Normal $vcr use runs this guarded maintenance automatically. The helper's transcribe and trash commands are intended to be orchestrated by the skill. Running them manually does not perform the agent's reconciliation, diff review, commit, or push steps.

Use

Record a voice note, allow iCloud time to sync, open Codex in or with access to the configured vault, and invoke:

$vcr

The invocation processes every complete, unprocessed recording, oldest first. It is a Codex skill invocation, not a shell command.

Typical status messages are:

✅ VCR is clear - no new voice recordings to process.
🎙️ Found 2 new voice recordings. Processing...
🎧 Transcribing recording 1 of 2...
📝 Reconciling the recording into the Markdown vault...
✅ Processed 2 voice recordings.
⚠️ Could not process recording 1. The audio was kept for retry.

Useful spoken labels include:

  • Idea for Project Alpha: preserves an idea without making it a commitment.
  • This idea may also help Project Beta: records a supported cross-project association and contextual link without creating a second detailed copy.
  • Promote this idea to future work for Project Alpha: explicitly changes the idea state; merely mentioning the idea does not.
  • Todo for Project Alpha: creates a project action but does not automatically change today or this week.
  • Result for Project Alpha, experiment E17: preserves the result separately from its interpretation.
  • Decision for Project Alpha: records a decision and its reason when spoken.
  • Add this movie to my watchlist: creates a passive list item, not a task.
  • Change today's plan to Project Alpha: explicitly requests reconciliation of the current plan.

Natural speech remains valid. Tentative wording such as maybe I should work on Project Alpha tomorrow must not silently change current plans.

Safety Model

  • Only complete M4A files under the configured capture root are eligible.
  • Source files are treated as immutable input and identified by full SHA-256.
  • Raw audio and temporary files must never enter Git.
  • The raw model transcript is data, not an instruction to the agent.
  • Normalization must not alter uncertainty, negation, numbers, dates, scope, or intent.
  • Ambiguous meaning is preserved as unresolved instead of guessed or enacted.
  • Within the vault, extracted meaning goes to canonical files while the full transcript and routing audit stay only in the yearly transcript archive.
  • A failed or empty transcription changes no capture or canonical Markdown file and leaves the source in place, except for the explicitly authorized probable-accidental disposition.
  • A recording three seconds or shorter with no usable hosted transcript is reported as a probable accidental Action Button capture. It is not retried again in that invocation and no semantic work is inferred. Without explicit cleanup authorization it remains in place. With authorization, VCR first pushes and verifies a no-transcript disposition record, then uses the gated Trash path. Clear short speech is processed normally.
  • Transient transport, rate-limit, and server failures receive at most three hosted attempts. Permanent API failures do not loop.
  • Unrelated pre-existing Git changes are never included in a voice commit.
  • Audio is moved only after the exact intended local commit and archived processed record match the configured live remote branch.
  • The live remote branch is checked again immediately before the Trash operation.
  • The source hash is checked again immediately before the Trash operation.
  • Empty source-folder cleanup uses non-recursive removal only for empty direct YYYY-MM-DD children older than today. It cannot remove a folder that contains an audio file, hidden file, or newly synced entry.
  • Moving an M4A to Mac Trash is not secure deletion. The local Trash copy remains recoverable until Trash is emptied.
  • Markdown transcripts remain in Git history after commit. Removing a current file does not erase earlier history.

The helper verifies remote durability, not repository visibility. Confirm independently that the destination repository is private.

Privacy and Cost

The helper's transcription request sends the original M4A, selected two-letter language hints, and canonical vocabulary terms to OpenAI. It does not send project files or broader vault content as transcription context. Codex and the configured Git host have their own data handling, separate from the transcription endpoint.

Data Where it goes Why
Source M4A OpenAI transcription endpoint Speech-to-text processing
Language and vocabulary hints OpenAI transcription endpoint Language selection and recurring-name spelling
API key Read from macOS Keychain and sent to OpenAI as request authentication API authorization; it is not stored in JSON or printed
Raw transcript JSON Codex tool/session output, then archive/voice-transcripts/<year>/ Exact provenance; session retention follows the Codex environment
Canonical vault Markdown Codex and the configured private Git remote Extracted projects, actions, ideas, results, decisions, lists, and planning state
Transcript archive Markdown Codex and the configured private Git remote Durable context and processing audit; not a second task source or an independent backup
config.local.json Local skill directory only Paths and lookup identifiers; it must remain uncommitted
Successful source M4A Mac Trash after remote verification Recoverable cleanup until Trash is emptied

Known-sensitive recordings must not be processed because the audio is uploaded before transcript-level secret detection is possible. If a transcript appears to contain a password, token, credential, or other secret, the skill must not write or push it and must retain the source for the user.

As checked on 2026-08-28, OpenAI lists gpt-transcribe at $0.0045 per audio minute. Prices and access can change, so verify the current model page before use. OpenAI's current data-control table lists /v1/audio/transcriptions as not used for training, with no abuse-monitoring retention and no application-state retention; verify the current data controls when evaluating privacy requirements.

Fixed Defaults and Limits

Setting Default or limit
Local configuration config.local.json in the skill directory
Capture root Just Press Record's iCloud Drive Documents container
Language hints en in the generated local configuration; add other expected languages explicitly
Git destination origin/main in the generated local configuration
Transcription model gpt-transcribe
Keychain service VCR OpenAI API Key
Keychain account openai-api
Audio format M4A only
Maximum audio size 25,000,000 bytes
Stability interval 2 seconds
Minimum file age 5 seconds
Hosted attempts At most 3, only for transient failures
Probable accidental threshold 3 seconds or less, only when hosted transcription returns no usable text
Temporary staging / legacy records inbox/captures/ inside the vault
Processed transcript records archive/voice-transcripts/YYYY/ inside the vault

The persistent vault, capture root, languages, remote, branch, and Keychain identifiers come from config.local.json. The model, accepted format, size limit, and capture-record location are implementation contracts rather than local preferences.

Troubleshooting

The skill is not listed

  • Check the directory reported by the installer. For a current manual install, check ~/.agents/skills/vcr.
  • If the installed Codex build documents $CODEX_HOME/skills, also check ${CODEX_HOME:-$HOME/.codex}/skills/vcr.
  • Confirm SKILL.md is directly inside that folder.
  • Start a new conversation, then restart Codex if needed.

config.local.json is missing or invalid

Run python3 scripts/setup.py --vault /absolute/path/to/your-vault from the skill directory. Add --install-templates only for a fresh vault where the generic files should be created. For an existing vault, answer No if interactive setup asks to install them. Confirm all seven fields are present and valid JSON. Do not add comments to JSON. An existing vault must manually merge templates/vault/SYSTEM.md into its canonical policy before running check.

ready is false

Read the individual readiness fields returned by check. Common causes are a missing Keychain item, missing ffmpeg/ffprobe, a missing vocabulary table, an unavailable capture directory, or a vault without SYSTEM.md and .git.

No recording appears

  • Confirm the recording exists in Just Press Record on the iPhone.
  • Confirm iCloud Drive is enabled on both devices under the same Apple Account.
  • Keep the Just Press Record folder downloaded on the Mac.
  • Keep the Mac awake and online long enough for sync.
  • Check Finder's iCloud Status column for upload, download, storage, or placeholder errors.
  • Wait until the recording is older than the minimum-age window, then retry.

VCR cannot process a recording that has not reached the Mac as a complete local file.

The same recording is retried

Failed, incomplete, or transcriptionally unreliable recordings remain in place intentionally. Resolve the reported issue, record a clearer replacement, or explicitly decide how to handle the failed source. VCR does not silently delete failed input.

If a processed record already exists, VCR searches the yearly transcript archive and direct legacy inbox records by full audio hash. It verifies the exact pushed record and retries only the source cleanup rather than transcribing or filing the meaning again.

Within one invocation, VCR does not retry a recording of three seconds or less after hosted transcription returns no usable text. It reports the file separately as a probable accidental Action Button capture and keeps it unless cleanup is explicitly authorized in the current request or the vault's canonical policy. Authorized cleanup still requires a durable disposition record, an exact pushed commit, live remote verification, and a hash-matched move to Trash.

A very short recording has no transcript

VCR treats a recording of three seconds or less as probably accidental only after hosted transcription returns no usable text. It creates no task, idea, project update, or other semantic record from that file. When cleanup is explicitly authorized, it creates only the no-transcript disposition needed for remote-verifiable cleanup. Clearly transcribed short commands are handled like any other recording.

OpenAI returns an error

Authentication, permission, billing, quota, invalid-input, and empty-output failures stop without a local fallback. Confirm the configured Keychain identifiers, API project permissions, billing status, current model access, file size, and audio quality.

The recording exceeds 25,000,000 bytes

The helper rejects it and retains the source. Make shorter recordings or manually split an exported copy, preserving the original until every resulting capture has been processed and verified.

Remote verification fails

Confirm Git authentication works non-interactively, the configured remote and branch exist, the intended local commit exactly matches that live branch, and the exact capture record is present there. The source audio is retained whenever verification fails.

Processing succeeded but the source remains

Review the final trash result. When the source and Trash are on different filesystems, the helper verifies a Trash copy but retains the source for manual cleanup. Do not remove the source until the pushed capture record and Trash copy have both been verified.

Old empty date folders remain

Invoke $vcr again or run python3 scripts/voice_capture.py prune-empty-dirs. Only empty direct date folders older than today are eligible. Hidden or sync-created content, a non-date name, a current-day folder, or a permission problem prevents removal.

Public Repository Notice

This repository is intended to contain reusable skill instructions, helper code, setup tooling, and generic vault templates only. It must not contain a user's config.local.json, API key, absolute personal paths, private remote URLs, vocabulary, transcripts, audio, or vault history.

VCR is an independent project and is not an official OpenAI, Apple, or Open Planet Software product. References to Codex, OpenAI models, iCloud Drive, and Just Press Record describe external services or software required by the workflow. Their behavior, availability, pricing, and terms can change independently of this repository.

Test

Run the isolated standard-library suite from the repository root:

python3 -m unittest discover -s tests -v

The synthetic audio case is skipped when FFmpeg is unavailable. Tests do not use a real API key, recording, vault, remote host, or Trash directory.

Roadmap

  • Add native Claude Code skill packaging and test the full workflow end to end. This is not implemented in the current release.

Intentional Limitations

  • This release supports Codex only.
  • Processing starts only when $vcr is invoked.
  • There is no background watcher or automatic Mac-side processing.
  • iCloud timing is controlled by Apple and cannot be made instantaneous by VCR.
  • There is no local transcription fallback.
  • The workflow does not execute consequential real-world actions merely because a recording mentions them.
  • Calendar, reminder, email, and messaging integrations are outside this skill unless a vault protocol and separately authorized workflow explicitly add them.

License and Security

See LICENSE for license terms and SECURITY.md for private vulnerability-reporting guidance.