--- title: "Install Claude Code Bundles Without Breaking Your Own Files" author: "Harry" published: 2026-10-31T04:14:01.681Z updated: 2026-10-31T05:05:25.729Z category: "AI Agents: SDLC & STLC" tags: ["agentic-fx"] canonical: "https://fxblog.dev/posts/install-claude-code-bundles" --- # Install Claude Code Bundles Without Breaking Your Own Files ## Key takeaways - Copying Claude Code bundles by hand puts files in the wrong place, can leave a second bundle without its hooks, and gives no sign that a copy is stale. - npx agentic-fx@latest install copies a bundle's agents, commands and skills into .claude/, its workspace into .sdlc/, .stlc/ or .evals/, and merges its settings.json rules and hooks. - Every file the installer owns is recorded in .claude/.agentic-fx.json, and update and uninstall act only on files on that list. - Your profile and your own settings.json rules survive an update; a file a new version no longer ships is deleted only after you confirm. - doctor reports a missing .claude folder, and outdated shows installed against published versions for each bundle. > **TL;DR** Install Claude Code bundles by hand and files land in the wrong place, old versions go unnoticed, or an update overwrites your work. `npx agentic-fx@latest install` records every file it writes in `.claude/.agentic-fx.json`; `update` and `uninstall` touch only files on that list. > > **Do this:** in a project you can throw away, run `npx agentic-fx@latest install`, then open `.claude/.agentic-fx.json` to see what it owns. You copy a bundle's agents, commands and skills into `.claude/` on Monday. The bundles here are `dev` (software delivery), `qa` (testing) and `eval` (LLM evaluation). A month later a fix ships. You copy again, over the file you tweaked. Or you don't. Nothing tells you which. ## What goes wrong when you copy by hand None of it throws an error. A file in the wrong folder just sits there. Two bundles each ship a `settings.json`; copy the second over the first and one bundle runs without its hooks. And a copied folder has no version, so you can't tell it is stale. ## Five questions to ask of any installer | Question | agentic-fx | | ------------------------------- | ----------------------------------------------- | | Can I see what it wrote? | One list: `.claude/.agentic-fx.json` | | What about a file I edited? | Your profile is kept; bundle files are replaced | | And my settings? | Rules and hooks are added, none removed | | Will I hear about new versions? | The board and Claude Code read a notice file | | Can I remove it? | `uninstall` deletes listed files only | ## How the installer works, step by step ![The installer in five steps: --bundle dev,qa in, dev 1.10.0 copied into .claude/, settings.json merged, owned files recorded, workspaces and profiles out](https://fxblog.dev/media/01a18fc8-3193-75fb-a20a-b9c4a9f19f0f/1600) _Each step stops one hand-copy failure_ 1. **Input.** A project and `--bundle dev,qa,eval` or `all`; with no flag it asks. It checks Node 20+, Claude Code, Git Bash on Windows and Python for `eval`, and blocks on none. 2. **Copy.** Agents, commands and skills go to `.claude/`, the workspace to `.sdlc/`, `.stlc/` or `.evals/`. A profile is copied only if you have none. 3. **Merge.** New rules and hooks are appended to `settings.json`. 4. **Record.** Every owned file goes into the manifest. 5. **Output.** A profile per bundle to fill, and the VS Code board unless you pass `--no-addons`. Step 3 is where this differs from the installer I use in-house. That one leaves a second settings file for you to merge by hand. Fine for me. Someone installing two bundles from npm would run the second with its hooks silently off, so this one merges, and only ever adds. ## One real run: a deleted folder and an old version An empty git repo called `my-project`, then `npx agentic-fx@latest install --bundle dev,qa --no-addons --yes`: ![The install in my-project: machine checks pass, dev 1.10.0 and qa 2.5.0 installed into .sdlc/ and .stlc/](https://fxblog.dev/media/01a18fc8-481e-720f-9ff1-176159e4c2f7/1600) _No VS Code board, by flag_ `ls -AF -C -T 0 -w 76 .claude .sdlc .stlc` shows where it went. The manifest lists 507 files. ![.claude/ after install, with the manifest .agentic-fx.json, both profiles and the agents, commands, hooks and skills folders, beside .sdlc/ and .stlc/](https://fxblog.dev/media/01a18fc8-56f9-75d5-b28a-d8e79fbbfa72/1600) _The manifest sits next to the files it lists_ Then I broke it. A line in `DEV-PROFILE.md`, a permission rule of my own in `settings.json`, `rm -rf .claude/skills`, and `npx agentic-fx@latest doctor`: ![doctor after the delete: dev 1.10.0 and qa 2.5.0 both marked missing .claude/skills, run update](https://fxblog.dev/media/01a18fc8-660f-75c4-96ea-7f631cb9a62f/1600) `npx agentic-fx@latest update --no-addons` put the skills back. `tail -n 1 .claude/DEV-PROFILE.md` still printed my line, my rule was still there, and `doctor` went green. ![update restores both bundles, tail shows the profile line still in place, doctor marks dev and qa green](https://fxblog.dev/media/01a18fc8-707e-7436-a072-4b506427dc21/1600) _My profile line survived_ Last, I set `dev` to 1.8.0 in the manifest, standing in for an older install, and ran `npx agentic-fx@latest outdated`: ![outdated: dev 1.8.0 to 1.10.0, minor; qa 2.5.0 up to date](https://fxblog.dev/media/01a18fc8-7ff4-7328-81b7-67fcdc066fff/1600) `npx agentic-fx@latest update --bundle dev --no-addons` moved it to 1.10.0. A MAJOR release would ask first. > **Note** > > A file a new version no longer ships is deleted only after you confirm. ## Get it ```sh cd your-project npx agentic-fx@latest install claude ``` Fill the profile, then run `/sdlc-intake `, `/qa-analyze ` or `/eval-scope`. You need Node 20+ and Claude Code. > **Note** > > Limits: edit the profile, not bundle files; those are replaced on update. Per project only. `outdated` shows `unknown` offline. What does a gate in `dev` actually check? Read **Your AI Coding Agent Grades Its Own Homework. Add Gates.** Testing starts with **A QA Pipeline Your AI Agent Can't Fake**. ## Read this with your AI ```text Read the post "Install Claude Code bundles without breaking your own files". 1. Summarise it in 5 bullets for a tech lead. 2. Ask me 3 questions to check I understood; wait, then correct me. 3. Give me one 10-minute exercise for my own project. ``` > **Success** > > You can now install the three bundles, see which files they own, and update them without losing your profile. Next: **Your AI Coding Agent Grades Its Own Homework. Add Gates.** ## FAQ ### Which bundles does npx agentic-fx@latest install? It installs dev (software delivery), qa (testing) and eval (LLM and agent evaluation) with \`--bundle dev,qa,eval\` or \`--bundle all\`. With no flag it asks, and with \`--yes\` and no flag it installs all three. ### Does an update overwrite my profile or settings? No. The profile (\`DEV-PROFILE.md\`, \`PROJECT-PROFILE.md\` or \`EVAL-PROFILE.md\`) is kept, and settings.json only gains rules and hooks it lacks. Files the bundle owns are replaced, so edit the profile, not the bundle files. ### How do I skip the VS Code board? Pass \`--no-addons\`. Without it, the board is installed into VS Code, Cursor or Windsurf, whichever command is found on the machine.