Skip to content

feat(cli): install the framework for every project with setup --global - #1142

Open
alexsoyes wants to merge 16 commits into
nextfrom
feat/global-install
Open

alexsoyes wants to merge 16 commits into
nextfrom
feat/global-install

Conversation

@alexsoyes

@alexsoyes alexsoyes commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

🎯 What & why

Install the framework once for every project on a machine, with the framework's own CLI:

aidd setup --global --ide claude,codex,copilot,cursor,kilo,opencode --plugins all
aidd sync --global    # after a framework update
aidd clean --global --force   # remove what --global installed

This did not exist. On next, setup --scope user only registered the framework source:

  • it refused --plugins (setup-flow.ts:94 throws UserScopePluginModeError for any mode but none);
  • it refused OpenCode and Kilo (setup-flow.ts:93; cli/README.md:121: "opencode, kilo: Unsupported: use project scope");
  • it installed nothing (setup-machine-scope-use-case.ts:52: install: { results: [] }, "no tool content install");
  • Copilot was refused outright: its marketplace source was never proven ("output shape is not verified").

Plugin install existed per project only. The machine-wide install lived in make reload alone, with hand-written copies and builds per tool (scripts/dev-sync.sh), and the shared OpenCode server reimplemented the same copy in its own script.

🛠️ How it works

  • Claude Code, Codex, Copilot: the chosen plugins are enabled through each tool's own CLI at user scope (enablePlugins, threaded into the existing native activation). Copilot 1.0.98 answers plugin marketplace list --json, so its local source is now proven; 1.0.83, which rejects --json, is still refused.

  • OpenCode and Kilo have no plugin system: each plugin's skills and agents are copied into ~/.config/opencode/ or ~/.config/kilo/. Codex plugins cannot carry agents: its agents are copied into ~/.codex/agents/. A profile declares this as PluginsCapability.machineFiles; only the agents a plugin's source ships are taken.

  • Cursor gets each plugin in ~/.cursor/plugins/local/, its existing user plugins directory.

  • The copies are recorded in the machine manifest as user-scope plugins and written by the existing user-scope plugin writer (UserPluginFileUpdater). So sync --global rebuilds them from the framework source, clean --global removes them, and a file aidd did not write is never overwritten.

  • --global is the spelling of --scope user on setup, sync, doctor, clean; --ide names every tool (--ai stays as a hidden former spelling).

  • make reload is now a thin wrapper: aidd setup --global --source local for every installed tool, after releasing Claude's and Codex's plugins, since an edited plugin keeps its version; Copilot reads its plugins live and needs no release. Its own Copilot and Cursor build and copy are gone.

  • make check-hosts tables what each installed tool really loads (plugins, global instructions, skills, agents), asked of the tool where it can answer, read from its documented files where it cannot, and exits 1 when something is missing.

🧪 How to verify

  • make reload && make check-hosts: exit 0, five runs byte-identical on a Mac with all six tools. Removing a skill and an agent in an empty HOME shows ❌ naming both. Until fix(aidd-vcs): name the resolve-conflict skill after its folder #1148 merges, Codex and Cursor show aidd-vcs/05-resolve-conflict missing.

  • cd cli && pnpm typecheck && pnpm test: 6,920 tests pass. node --test scripts/__tests__/dev-sync.test.js: 23 pass. Mutation floors hold (copilot 95.7, opencode 94.6, kilo 72.8, presentation 95.7).

  • In an empty HOME, with the real claude, codex and opencode: aidd setup --global --source local --path <checkout> --ide claude,codex,opencode --plugins all --yes enables the 9 plugins in Claude Code and Codex, puts the 4 agents in ~/.codex/agents/, and copies 52 skills and 4 agents into ~/.config/opencode/. OpenCode v2.2.5 lists them; the project directory stays empty.

  • Same, with the real copilot 1.0.98: the 9 plugins are registered and enabled. With --ide cursor,kilo: 9 plugins in ~/.cursor/plugins/local/, 52 skills and 4 agents in ~/.config/kilo/. sync --global then clean --global --force refresh and remove everything.

  • The e2e tests/e2e/setup-scope-user.e2e.test.ts covers OpenCode setup, sync and clean end to end.

⚠️ Heads-up

  • Kilo 7.8.18 and OpenCode 2.2.5, run for real in an empty HOME, load the copied skills and agents and answer through them.
  • Copilot does not resolve symlinks in the source path it lists: a HOME reached through a symlink (/tmp on macOS) leaves its source unproven and activation skipped, with a warning.
  • At --global, OpenCode files go to ~/.config/opencode whatever XDG_CONFIG_HOME says.
  • Kilo documents no global AGENTS.md, so make reload writes it no global instructions.
  • On a machine where an earlier make reload copied Cursor plugins by hand, setup --global refuses to overwrite them, naming each file: move ~/.cursor/plugins/local/aidd-* away once.
  • Bundle budget 734 KB (719.8 KB measured), reason in cli/scripts/check-bundle-size.mjs.
  • The agents' provider (--provider) is a separate PR stacked on this one: feat(cli): run the main session and the agents on a chosen provider's models #1119.

✅ I certify

  • I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.

@alexsoyes

Copy link
Copy Markdown
Contributor Author

c'était nécessaire pour la feautre des sous agents :)

@alexsoyes

Copy link
Copy Markdown
Contributor Author

Car j'ai un poste où je les setup en global et ils bossent sur /framework, /operation-system, /ai-driven-dev.fr ou /gouvernail sans que je doive le résinstaller à chaque fois.

ça me permet aussi de le faire sur le serveur.

@alexsoyes
alexsoyes marked this pull request as ready for review November 4, 2026 02:11
@alexsoyes
alexsoyes requested a review from a team as a code owner November 4, 2026 02:11
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-04T23:33:20.915362Z 7ef514d New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 42e1d0cfc3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

mode: "native",
pluginsDir: ".codex/plugins/",
pluginManifestRelativePath: "plugin.json",
machineFiles: { dir: (homedir) => join(homedir, ".codex"), map: codexMachineFilePath },

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Honor CODEX_HOME when installing machine-wide agents

When CODEX_HOME points somewhere other than ~/.codex, machine-wide agents are copied into the wrong configuration directory and are unavailable to that Codex installation. This also regresses make reload, whose previous agent-copy destination explicitly honored ${CODEX_HOME:-$HOME/.codex} before this commit delegated copying to setup. The same profile already honors the override in nativeActivation.userSettingsPath; resolve the machine-file directory consistently for installation, sync, and cleanup.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pas corrigé ici : reporté avec XDG_CONFIG_HOME, décision d'Alex, car c'est le même sujet (un dossier de config déplacé par une variable d'environnement). Je laisse le fil ouvert. Tant que ce n'est pas fait, avec CODEX_HOME, les agents partent dans ~/.codex.

Comment thread cli/src/presentation/commands/sync.ts Resolved
Comment thread scripts/dev-sync.sh Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7ef514d5d7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread cli/src/presentation/commands/sync.ts Resolved
Comment thread cli/src/presentation/commands/sync.ts Resolved

@alexsoyes alexsoyes left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

revue Alex

@alexsoyes

Copy link
Copy Markdown
Contributor Author

Revue OpenCode

Commit examiné : a5b8d09d14507f79b53c73976263089bef8b1c19 ; la PR peut avoir évolué depuis.

La revue est partielle ; les fichiers restants seront réessayés.

Lot 1

Verdict: blocked

Findings

  • 🔴 Global setup can take ownership of pre-existing user files. cli/src/contexts/framework/application/ownership/global-plugin-files.ts:80-83 permits an unowned file when its bytes match the generated file. The installer then records it as owned (cli/src/contexts/framework/application/setup/install-global-plugins-use-case.ts:95-99), so a later global clean can delete a file aidd did not create. The same issue exists for Cursor at cli/src/contexts/framework/application/ownership/user-plugin-file-updater.ts:159-165. Refuse unowned existing files, or explicitly preserve their foreign ownership through update and clean.

  • 🟡 A failed native activation cannot be recovered by the documented sync. cli/src/contexts/framework/application/setup/setup-machine-scope-use-case.ts:41-48 passes the selected plugin names only to the current activation run. Native-only tools do not receive plugin records (install-global-plugins-use-case.ts:68-70), and failed or skipped enables do not produce claims (marketplace-sync-settings-use-case.ts:640-650). Consequently, after installing a missing Claude or Copilot executable, sync --global has no selection to enable, contrary to cli/README.md:64-69. Persist the requested selection independently of successful activation and retry it during sync.

Limits: Review was read-only; runtime behavior and the PR’s reported test results were not independently verified.

Verdict de ce lot : blocked

@alexsoyes

Copy link
Copy Markdown
Contributor Author

Revue OpenCode

Commit examiné : a5b8d09d14507f79b53c73976263089bef8b1c19 ; la PR peut avoir évolué depuis.

La revue est partielle ; les fichiers restants seront réessayés.

Lot 1

Review: global setup

Verdict: approve — no actionable defects identified in the supplied batch.

Reviewed the supplied diffs and PR context. Runtime behavior was not independently verified; this was a read-only review. The implementation files outside this batch were not available for tracing the tests’ assumptions.

Verdict de ce lot : approve

@alexsoyes

Copy link
Copy Markdown
Contributor Author

Revue OpenCode

Commit examiné : a5b8d09d14507f79b53c73976263089bef8b1c19 ; la PR peut avoir évolué depuis.

Lot 1

Verdict: blocked

  • 🔴 Reload can remove an unrelated marketplace and its plugins. In scripts/dev-sync.sh, release_native_plugins() uninstalls plugin names and removes the aidd-framework marketplace before setup can verify which source owns it. A user with a different source registered under that name can lose its registration and installed plugins. Verify the registered source belongs to this checkout before releasing anything; refuse a foreign source.

  • 🟡 Existing OpenCode reload installations cannot be upgraded in place. The old scripts/dev-sync.sh copied skills and agents directly into the OpenCode user directory; the replacement delegates to the ownership-protecting global installer. Those earlier copies have no machine-manifest ownership, so the installer will refuse to overwrite them. Provide a safe migration or explicitly detect and explain the required cleanup for OpenCode, as well as Cursor.

  • 🟡 OpenCode content and instructions diverge with XDG_CONFIG_HOME. scripts/dev-sync.sh still puts instructions under $XDG_CONFIG_HOME/opencode, while the supplied PR context says global installation always writes OpenCode plugin files under ~/.config/opencode. On a custom XDG configuration, the host and check-hosts use the native config directory, so the newly installed skills and agents are not available there. Resolve both destinations using the same native config path.

  • 🟡 Managed OpenCode reload is no longer invoked. scripts/dev-sync.sh removes detection and invocation of aidd-opencode-reload. On a managed host exposing that helper without an opencode executable, reload now reports no supported host and exits successfully without refreshing OpenCode. Preserve the helper path or provide an equivalent managed-host integration.

Review limited to the supplied diff chunks and PR snapshot; no runtime checks were performed.

Verdict de ce lot : blocked

Until now `setup --scope user` only registered the framework source: it refused --plugins, refused
OpenCode, and installed nothing, so every machine-wide install lived in make reload's own copies.

`aidd setup --global --ide claude,codex,opencode --plugins all|recommended|<names>` now installs:
Claude Code, Codex and Copilot enable the plugins through their own CLI at user scope; OpenCode,
which has no plugin system, gets each plugin's skills and agents copied into ~/.config/opencode,
and Codex, whose plugins cannot carry agents, its agents into ~/.codex/agents. A profile declares
those copies as `machineFiles`; they are recorded in the machine manifest as user-scope plugins
and written by the existing user-scope plugin writer, so `sync --global` rebuilds them from the
framework source and `clean --global` removes them without touching files aidd did not write.

`--global` is the spelling of `--scope user` on setup, sync, doctor and clean, and `--ide` names
every tool, AI assistants included (`--ai` stays as a hidden former spelling).
… setup --global

The reload hands this checkout to aidd setup --global --source local --plugins all, the way a user installs machine-wide, instead of copying skills and agents by hand. Claude and Codex get their plugins afresh each run, since an edited plugin keeps its version. Copilot and Cursor are unchanged.
…nymore

Since the generic sub-agents shipped, every profile declares its agent frontmatter in agent-format.ts; agent-frontmatter-strip.ts and its test were left with no caller.
…o too

- Kilo copies skills and agents into ~/.config/kilo, as OpenCode does.
- Cursor copies plugins into ~/.cursor/plugins/local.
- Copilot 1.0.98 answers marketplace list --json: its local source is now proven,
  so setup --global enables the plugins through its CLI.
- Plan user-scope plugin updates one at a time: plans for one tool share its built tree.
- Copilot and Cursor leave the script's own build and copy: setup --global installs them,
  with Kilo now detected too. Copilot is released afresh each reload, like Claude and Codex.
- Kilo documents no global AGENTS.md, so the reload writes it no instructions.
- Docs: INSTALL.md shows the machine-wide install, update and removal; the CLI README,
  memory and smoke-real tool list follow every tool now supporting --global.
…gins in place

- setup --global runs from HOME: the checkout's own .claude/settings.json enables the plugins
  at project scope, which the hosts report and the CLI refuses as refs it does not own.
- Copilot is no longer uninstalled each reload: its uninstall leaves every plugin disabled
  rather than gone, which the next setup --global refuses the same way.
- doctor --global stops asking a project to declare the marketplace, which a machine-wide
  install never writes there, and its messages name setup --global.
…ilot

- Claude 2.1.312's marketplace remove --scope user drops the settings declaration and keeps
  the registration: a user-scope remove now names no scope, from the home directory
  (NativeActivation.userRemoveArgs), so clean deletes it and the next setup declares it again.
- Copilot's uninstall leaves each ref disabled rather than gone: a disabled ref there is no
  longer taken for a plugin in use (NativeActivation.uninstallLeavesRefDisabled), so setup
  after clean enables the plugins again. Claude keeps refusing a ref the person disabled.
- make reload removes Claude's marketplace from every scope, from HOME, for the same reason.
…of the plugins

Plugins enabled, global instructions, skills and agents, per installed tool: asked of the tool
where it can answer, read from the files its documentation names where it cannot. Exits 1 when
an installed tool misses something.
- Claude's plugins, skills and agents come from its session's init event, compared by name; the
  session runs without hooks or a saved transcript.
- A listed skill counts only under the tool's config directory and while its file exists.
- Cursor reads names from the frontmatter alone; global instructions need the managed block.
- No plugin to expect, or a tool answering no config directory, is a failure, not 0/0.
- OpenCode's service is read again while it starts cold, until it lists every skill.
- A test per tool, and one per false positive.
Removing Claude's marketplace from every scope also uninstalls what a project installed from it,
with its saved options. clean --global and make reload now do that only when no project uses the
marketplace, and stay at user scope otherwise, or when the list cannot be read.
The README's clean --global example names --force, without which it previews or asks.
…hing later

Every plugin's plan is checked before the first write, the manifest is saved
after each plugin, and a rerun takes over identical files on Cursor as it
already did on the flat tools.
…touch only what it names

sync --global writes back a recorded file that was deleted. A remote source's
clone and plugin fetches live in the user's cache, never the current directory.
Only the tools a run names get the chosen plugins. A rerun takes the source it
resolved. Without the shared source, global files are refused rather than rebuilt
in a project's layout. make reload shows what setup skipped.
alexsoyes and others added 2 commits November 6, 2026 05:34
--global is the word people know. The names already on next stay for their own change.
Keep successful native plugin selections recoverable, protect unowned files, and complete global cleanup without removing other marketplace sources. Restore managed OpenCode reload compatibility.

Refs: #1142
@alexsoyes
alexsoyes enabled auto-merge (squash) November 6, 2026 23:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants