zcf — Zero-Config Setup for Claude Code & Codex

Practical Notes

• Quant: keep a baseline of 3 commands (npx zcf, npx zcf i, npx zcf u) and measure “time-to-first-run” after a clean machine setup.
• Quant: track how many config files are touched in your repo; fewer moving parts usually means fewer breakages.

What “zero-config” should mean in practice

Treat it as a repeatable installer, not magic:

• It should be safe to re-run (update should not clobber local customizations).
• It should create a small number of well-known files.
• It should make failures obvious (clear logs + next action).

How to adopt in a team

1. Run initialization in a sandbox repo first.
2. Commit only the minimal workflow/config artifacts you actually want shared.
3. Document a rollback: what to delete to return to a clean state.

When not to use it

If your org already has an internal bootstrapper, keep one source of truth and integrate zcf as an optional module instead of competing installers.

FAQ

Q: Is npx required? A: The README promotes npx as the simplest path; keep Node.js available on your PATH.

Q: How do I keep custom config? A: Commit only the shared artifacts and document which files are owned by zcf vs owned by your repo.

Q: What should I test first? A: A clean install on a fresh machine/container and a one-command update path.