docs: document the remaining external tools (gh, ffmpeg, yt-dlp, fabric, jq) and add them to Doctor - #1661
Open
elhoim wants to merge 2 commits into
Open
Conversation
Follow-on to the ripgrep/ImageMagick pass. Audited every binary shipped code actually spawns — Bun.spawn/execFile array literals, shell scripts, and the `command -v`/`Bun.which` guards that mark a tool as optional — then compared that set against GETTING-STARTED.md and Doctor's registry. Five were load-bearing and undocumented: - gh — the Work System keeps its system of record in a private GitHub repo. WorkSweep, CommitmentSweep, CommitmentLog, RetagSweepTypes, the Pulse work module and ReminderRouter all spawn `gh`, none with a fallback, so absence fails work capture outright rather than degrading. - ffmpeg — AudioEditor, SplitAndTranscribe and Conveyor spawn it directly. - yt-dlp — the Feed YouTube source and the Upgrade channel scan. - fabric — the Fabric skill's pattern library and transcript fetch. - jq — shell hooks that parse JSON, including the rtk rewrite. All five added to Doctor so they report live/broken with a fix command, and documented in GETTING-STARTED.md in the existing shape. Five narrower ones (rtk, kitten, cmux, mkcert, gws) go in a short table instead: each is tied to one terminal, platform or opt-in workflow and skips cleanly when absent, so a Doctor row would be noise on most hosts. Not included: `whisper` reads as a dependency in the source but is the OpenAI `whisper-1` API model, not a local binary — an API-key concern, not an external tool.
Installed rtk and ran it against the hook to check the row was accurate. Three things were worth recording that the placeholder row didn't say: - The install source, and that a release binary works as well as brew. - `rtk init -g` installs rtk's own global Claude Code hook, which would sit alongside LifeOS's ContextReduction.hook.sh — two rewriters on the same command. Anyone following rtk's own README will hit this. - It keeps a local history.db of proxied commands, and telemetry is opt-in but starts as 'never asked'; `rtk telemetry disable` settles it. Also states the compression rule the hook already enforces — compress what the model watches, never what it reads — since that is the reason the row exists at all.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-on to #1660, applying the same logic to the rest of the tree.
Method
Rather than grep for tool names, I enumerated what shipped code actually spawns:
Bun.spawn/spawnSync/execFilearray literals across*.ts*.shcommand -v/Bun.whichguard — the strongest signal, since a guard means the code already knows the tool may be absentThat guard set came back as:
bash bun bunx claude codex fabric gws interceptor jq kitten magick rtk wrangler. Four were documented,bunis in INSTALL.md, andbash/claudeare foundational. The rest, plus the unguarded spawns, are what this PR covers.Load-bearing and undocumented — added to Doctor and the page
ghffmpegyt-dlpfabricjqghis the significant one.WorkSweep,CommitmentSweep,CommitmentLog,RetagSweepTypes, the Pulse work module andReminderRouterall spawn it, none with a fallback — andWorkSystem.mdstates the GitHub repo is the system of record. So on a host withoutgh, work capture doesn't degrade, it fails, and nothing said so in advance. On the machine I audited from,ghis genuinely absent.Narrower ones — short table, no Doctor row
rtk,kitten,cmux,mkcert,gws. Each is tied to one terminal, one platform, or one opt-in workflow, and each skips cleanly when absent — a Doctor row would be a red ❌ on most hosts for something the user never wanted. They're listed so nothing is undocumented, without turning the check into noise.Deliberately excluded
whisperreads like a dependency — it appears inExtractTranscript.ts,SplitAndTranscribe.tsandConveyor/Runner.ts. It is the OpenAIwhisper-1API model, not a local binary (model: "whisper-1"atSplitAndTranscribe.ts:98). That's an API-key concern, not an external tool, so documenting it here would have been wrong.Verified
Doctor.tsruns clean with all 11 capabilities and exits 0, honouring its never-install-fatal contract.ghbroken with its fix command, whileffmpeg,yt-dlp,fabricandjqreport live — so both branches are exercised by a real run, not just the happy path.idin Doctor's registry has a corresponding mention inGETTING-STARTED.md— 11/11.