UfoMiao/zcf: a zero-config setup CLI for Claude Code and Codex

The setup tax that zcf is trying to remove

Claude Code and Codex both expect configuration before they are useful: provider credentials, model selection, and whatever project-level workflow files the user wants the agent to follow. Doing that by hand means editing files in at least two different tools, remembering which key goes where, and repeating the process on every new machine. The README frames zcf as "Zero-config, one-click setup for Claude Code & Codex with bilingual support, intelligent agent system and personalized AI assistant." The audience is developers who have already decided to use one of those coding agents and want the surrounding configuration handled. It is not an agent, a model proxy, or a code generator. Everything it does happens before the agent starts working.

What npx zcf actually writes to disk

The package ships a bin entry, bin/zcf.mjs, and the published files list is bin, dist and templates. That layout tells you the mechanism: the CLI collects answers, then copies and edits files from templates/ into the user's environment. The dependency list includes @rainbowatcher/toml-edit-js, which is consistent with editing TOML configuration rather than regenerating it wholesale. The repository also carries a top-level .zcf/ directory and a .claude/ directory, so both the tool's own state and the Claude Code side of the configuration are versioned in the repo. The README describes a full initialization as "install + workflows + API/CCR + MCP", which is the clearest statement of scope: the command touches the agent installation path, drops workflow templates, configures API access including CCR, and sets up MCP servers. Each of those is a separate concern that would otherwise be four separate manual edits.

Installing zcf and running a first initialization

There is no global install step documented. The README recommends running the package through npx, which fetches it on demand and opens an interactive menu.

npx zcf

Running it with no arguments is the intended entry point: the README says to pick what you need from the menu. If you already know you want everything, the short form for a full initialization is:

npx zcf i

That one letter covers install plus workflows plus API/CCR plus MCP. Updating only the workflow templates, without touching the rest, is a separate command:

npx zcf u

For scripted or CI use, the README gives a non-interactive form that presets a provider and passes the key directly:

npx zcf i -s -p 302ai -k "sk-xxx"

Here -s selects the non-interactive path, -p names the provider preset, and -k supplies the API key. The interface language is switchable, for example npx zcf --lang zh-CN, and the README is published in English, Simplified Chinese and Japanese, so the bilingual claim is backed by actual translated files rather than a single README. After a run, expect new or modified entries under the Claude Code configuration directory and under .zcf/. The README does not enumerate the exact file paths it writes, so treat the first run in a scratch project as the way to find out.

Where the zero-config promise stops

The tool configures other software, and that has consequences. If your Claude Code or Codex setup is already hand-tuned, a full initialization is a write operation against files you care about, and the README documents no rollback, no dry-run flag, and no backup step. The safest reading is that npx zcf i assumes a fresh or disposable environment. A second limitation is that provider presets are exactly that: presets. The non-interactive example hardcodes 302ai as the provider, and the sponsor list in the README is full of relay services, which is a fair signal of who the tool is built around. If you use a provider without a preset, you are back to editing configuration by hand, which is the problem zcf was supposed to remove. Third, the workflow templates are opinionated content shipped by the project. You get whatever the maintainers consider a good workflow, not a neutral scaffold, so review templates/ before assuming the generated files match your team's conventions.

zcf versus configuring Claude Code by hand

The real alternative is not another CLI, it is the manual path: read the Claude Code and Codex documentation, create the configuration files yourself, and write your own workflow prompts. That approach costs an afternoon and buys full control. Every setting has a known origin, nothing is overwritten by a later command, and the configuration can be reviewed in a pull request like any other file. zcf trades that control for speed and repeatability: the same menu produces the same layout on a new laptop, and npx zcf u refreshes workflow templates without requiring the user to track upstream changes. The difference in approach is ownership. Manual configuration means you own every line and every future edit. zcf means the project owns the defaults and you own the decision to run it. For a solo developer setting up a second machine, the trade is easy. For a team with a shared, reviewed configuration, the manual path is the one that survives code review.

Maintenance, releases and the MIT licence

The repository is not archived, and the most recent push recorded is 2026-08-31, the same day as the [email protected] release. Before that, [email protected] landed on 2026-08-04 and [email protected] on 2026-07-20, so the release cadence across those three versions is roughly monthly. The project uses Changesets, visible in the .changeset/ directory and the changeset and version scripts in package.json, which means version bumps and changelog entries are generated from committed changeset files rather than written by hand. Practically, that is the upgrade story: pin a version in your tooling if you need stability, and read CHANGELOG.md before moving. The licence is MIT, declared in package.json and present as a top-level LICENSE file. MIT permits commercial use and modification with attribution and no warranty, but this is a description of the licence text, not legal advice; if you redistribute zcf inside a product, have your own counsel read the file. Note also that the README's sponsor section contains affiliate links and discount codes for API relay services. That is a funding model, not a technical property, but it explains why certain provider presets are prominent.

Editorial conclusion

Adopt zcf if you already run Claude Code or Codex and want the initial configuration and workflow files written by a single command instead of by hand. Skip it if you have a hand-tuned setup you do not want overwritten, or if you need a guarantee that a run can be undone: the README documents no rollback. Before trusting it, run npx zcf without arguments, read the interactive menu, and check what files it reports writing under .claude/ and .zcf/ in a throwaway project.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. UfoMiao/zcf on GitHub