matthalltech/developing-with-claude
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: update GETTING-STARTED.md

Browse source
This commit is contained in:
matthalltech 2026-04-01 12:53:53 +00:00
parent c7f6eee516
commit 321a023c90
1 changed files with 53 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
GETTING-STARTED.md
View file

@ -190,9 +190,9 @@ This is genuinely useful once the system is running. It makes working with Claud
**macOS:** [SuperWhisper](https://superwhisper.com) with a local Parakeet model runs via WhisperKit on the Apple Neural Engine. Audio is processed entirely on-device. System-wide hotkey, inserts into any focused app. Free tier works well. This is the most turnkey option on Mac. Built-in Apple Dictation is a reasonable fallback if you want zero setup.
**Windows:** [OmniDictate](https://github.com/Turbo-Adib/OmniDictate) — free, open-source, uses faster-whisper as the backend. Push-to-talk via Right Shift (configurable), types directly into any focused Windows application. NVIDIA GPU with CUDA gives best performance; CPU-only mode works but is slower on larger models. Available as a `.exe` installer from the Releases page. Actively maintained — v2.0 shipped December 2025. Windows SmartScreen will warn on first run (unsigned binary); click through.
**Windows:** [OmniDictate](https://github.com/gurjar1/OmniDictate) — free, open-source, uses faster-whisper as the backend. Push-to-talk via Right Shift (configurable), types directly into any focused Windows application. NVIDIA GPU with CUDA gives best performance; CPU-only mode works but is slower on larger models. Available as a `.exe` installer from the Releases page. Actively maintained — v2.0 shipped December 2025. Windows SmartScreen will warn on first run (unsigned binary); click through.
**Linux:** [WhisperTux](https://github.com/medmunds/whispertux) — free, open-source, uses whisper.cpp as the backend. Global keyboard shortcut for start/stop, auto-injects text into the focused application. Works without a GPU — whisper.cpp runs on plain x86 with AVX. GPU acceleration supported if available. Works on GNOME and KDE. Install via `git clone` + `python3 setup.py` which handles dependencies, model download, and service registration. Last commit February 2026.
**Linux:** [WhisperTux](https://github.com/cjams/whispertux) — free, open-source, uses whisper.cpp as the backend. Global keyboard shortcut for start/stop, auto-injects text into the focused application. Works without a GPU — whisper.cpp runs on plain x86 with AVX. GPU acceleration supported if available. Works on GNOME and KDE. Install via `git clone` + `python3 setup.py` which handles dependencies, model download, and service registration.
One practical note: voice dictation produces transcription artefacts — misheard words, missing punctuation, run-on sentences. Claude handles this well if you prompt it naturally. You do not need to clean up every word before submitting.
@ -235,8 +235,8 @@ Once the baseline is stable, these are natural next layers — each independent,
| Layer | What it adds | Requires |
|---|---|---|
| Private Git hosting | Self-hosted Forgejo instead of GitHub | A VPS or home server |
| Infrastructure monitoring | Prometheus + Grafana + Alertmanager | A VPS |
| Log aggregation | Loki + Grafana Alloy | A VPS |
| Infrastructure monitoring | Prometheus + Grafana + Alertmanager | Any always-on machine — local to learn, VPS for reliability |
| Log aggregation | Loki + Grafana Alloy | Any always-on machine |
| Secure remote access | WireGuard VPN | A VPS |
| Local AI inference | Ollama + Open WebUI | GPU with adequate VRAM |
| Multi-agent workers | Codex + Gemini alongside Claude | Existing workspace |
@ -312,19 +312,55 @@ how they hand off work, and what prevents them from conflicting.
---
## Files to Create in Your Own Repo
## Bootstrap Your Repo with Claude
These are the documents that make an AI-assisted repo work well. None of them are magic — they are just Markdown files with clear purposes. Build them gradually as you need them.
Once the baseline is running, use these prompts to build the foundation documents. Each one is a single conversation — paste the prompt, answer Claude's questions, and commit the result.
| File | Purpose | Create it when… |
|---|---|---|
| `README.md` | Human-facing landing page — what this is, current state, key links | Day one |
| `ENTRYPOINT.md` | Agent session startup — what to read first, environment facts, execution boundaries | Once you have more than one doc |
| `AGENTS.md` | Operating contract for AI agents — what they can do, what requires approval | Before doing serious work with agents |
| `docs/system-plan.md` | Planning source of truth — what is built, what is open, what is next | When you have infrastructure to track |
| `docs/open-loops.md` | Persistent backlog across sessions — so nothing falls through the cracks | When unresolved items start accumulating |
| `bootstrap.sh` | Idempotent setup script — verifies the workspace is in the expected state after rebuilds | Once your setup has more than 3 steps |
| `.claude/rules/` | Repo-level rules loaded every Claude session — safety, style, workflow | When you have patterns you keep repeating |
| `docs/vendor-docs/` | Current third-party documentation fetched and stored locally | Before writing any code that uses an external library |
**Create your session entrypoint document:**
```
I am setting up a Git repo as a control plane for AI-assisted development.
**The most important habit:** Ask Claude to fetch current docs before writing any code that uses a third-party library, API, or tool. Training data is frozen. The docs are not.
Create an ENTRYPOINT.md for this repo that:
- Lists the key documents an AI agent should read before starting work
- States what this repo is and what it is for
- States the execution boundaries (what runs in the container vs what runs on the host)
- States where secrets are kept and that they must never enter the repo
Ask me questions about my setup before writing anything.
```
**Create your agent operating contract:**
```
Create an AGENTS.md for this repo that defines:
- What AI agents are permitted to do autonomously
- What requires explicit human approval before proceeding
- The Git branch model (who works on which branch)
- What agents must never do (commit secrets, push to main directly, etc.)
Ask me about my setup and which agents I am using before writing anything.
```
**Create your open loops document:**
```
Create a docs/open-loops.md for this repo.
This file tracks unresolved items across sessions — things that are in progress,
decisions that have not been made, or work that is blocked. It should be read at
the start of every session so nothing falls through the cracks between conversations.
Start it with the current open items from our conversation so far.
```
**Scaffold the full foundation in one pass:**
```
I have a new Git repo for AI-assisted development. I need you to create the
following foundation documents, asking me questions before writing each one:
1. README.md — what this repo is, current state, key links
2. ENTRYPOINT.md — agent session startup, read order, execution boundaries
3. AGENTS.md — what agents can and cannot do, branch model
4. docs/open-loops.md — persistent backlog of unresolved items
For each document: ask me the questions you need answered, write a first draft,
show it to me, and wait for approval before moving to the next one.
```