README.md
4,491 bytes
| 1 | # VoiceTask |
|---|---|
| 2 | |
| 3 | VoiceTask turns a conversation about an idea into a build brief that a developer, agency, or coding assistant can use. |
| 4 | |
| 5 | You speak or type. VoiceTask asks one focused question at a time, tracks which parts of the idea are clear, and creates a zip with the requirements, plan, tasks, checks, and handoff notes. Each requirement points back to the exact part of the interview it came from. |
| 6 | |
| 7 | VoiceTask runs on your computer. It needs no account and saves each interview locally. |
| 8 | |
| 9 | ## Start it |
| 10 | |
| 11 | ``` |
| 12 | npm install |
| 13 | npm run dev |
| 14 | ``` |
| 15 | |
| 16 | Open the printed Vite URL in Chrome or Edge. The first screen asks how you want to run it: |
| 17 | |
| 18 | - **Paste your own keys.** An Anthropic key for the interview (console.anthropic.com) and an OpenAI key for speech-to-text (platform.openai.com). VoiceTask saves them to a local `.env` file and starts using them right away, without a restart. |
| 19 | - **Try the demo without keys.** The whole flow runs on built-in sample answers, offline. |
| 20 | |
| 21 | You can switch between the two at any time from the button in the top right of the home screen. |
| 22 | |
| 23 | Two other ways to configure it, if you prefer the terminal: |
| 24 | |
| 25 | ``` |
| 26 | npm run demo # always offline, ignores whatever .env selects |
| 27 | npm run setup # asks the same questions in the terminal and writes .env |
| 28 | ``` |
| 29 | |
| 30 | You can also copy `.env.example` to `.env` and fill in the values yourself. |
| 31 | |
| 32 | ## How a session works |
| 33 | |
| 34 | 0. On first run, choose your keys or the offline demo. |
| 35 | 1. Give the idea a short name and choose the project folder. |
| 36 | 2. Click `Start talking`, speak, then click `Send recording`. You can type instead, or hold Space while you talk. |
| 37 | 3. Answer one question at a time. The progress panel shows what is ready, in progress, and still to discuss. |
| 38 | 4. Select `I'm done, wrap it up` when you have said enough. |
| 39 | 5. Create the build brief and download the zip. |
| 40 | 6. Copy the handoff message and send both to whoever will build the project. |
| 41 | |
| 42 | ## What the build brief contains |
| 43 | |
| 44 | | File | Purpose | |
| 45 | |---|---| |
| 46 | | `SPEC.md` | Goals, users, requirements, limits, and source markers | |
| 47 | | `PLAN.md` | Technical approach, structure, and implementation decisions | |
| 48 | | `TASKS.md` | Ordered work items with verification commands | |
| 49 | | `VERIFICATION.md` | Checks that define when the project is finished | |
| 50 | | `HANDOFF.md` | The starting instructions for the person or coding assistant doing the work | |
| 51 | | `sources.json` | The interview text and timestamps referenced by source markers | |
| 52 | |
| 53 | A source marker such as `[S7]` means the requirement came from interview segment S7. This makes it clear which decisions came from the user and which still need confirmation. |
| 54 | |
| 55 | ## Local data and privacy |
| 56 | |
| 57 | - VoiceTask has no accounts and no hosted sessions. |
| 58 | - Interview sessions are stored under `data/sessions/` on this computer. |
| 59 | - Generated files are written to the chosen project folder under `spec/`. |
| 60 | - The completed brief and transcript can be downloaded from the app. |
| 61 | - In real mode, audio is sent to OpenAI for transcription and interview text is sent to Anthropic for interview and file generation. |
| 62 | - API keys are read from environment variables or the local `.env`. They are not written to sessions, generated files, or logs. |
| 63 | - Keys entered in the app go to the same local `.env`, which is gitignored. The app never sends a key back to the browser; the settings screen shows only the last four characters of a saved key. |
| 64 | |
| 65 | ## Providers and models |
| 66 | |
| 67 | | Purpose | Provider | Environment variables | Default model | |
| 68 | |---|---|---|---| |
| 69 | | Interview and file generation | Anthropic Messages API | `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL` | `claude-opus-4-8` | |
| 70 | | Speech-to-text | OpenAI audio transcriptions | `OPENAI_API_KEY`, `STT_MODEL` | `gpt-4o-mini-transcribe` | |
| 71 | | Spoken questions | Browser `speechSynthesis` | none | Installed browser voice | |
| 72 | |
| 73 | `claude-sonnet-4-6` is a lower-cost Anthropic alternative. `gpt-4o-transcribe` and `whisper-1` are supported speech-to-text alternatives. |
| 74 | |
| 75 | ## Development commands |
| 76 | |
| 77 | ``` |
| 78 | npm run demo # start the full app with offline mock providers |
| 79 | npm run dev # start the app with the mode selected in .env |
| 80 | npm run typecheck # check TypeScript across shared, server, and client |
| 81 | npm test # run tests with mock providers and no network |
| 82 | npm run build # build the production client and server |
| 83 | npm run check # run typecheck, tests, and build |
| 84 | ``` |
| 85 | |
| 86 | Product requirements and implementation decisions live in `spec/`. Conventions and commands are in `CONTRIBUTING.md`. The blocker format is in `BLOCKED.md`. |
| 87 | |