@primeuicom/agent-setup

@primeuicom/agent-setup is an internal PrimeUI package.

It is the shared source of truth for project-local AI setup assets used by @primeuicom/cli. It is not intended to be a general public end-user package, and its API may change to support PrimeUI CLI and preset maintenance workflows.

The package still ships a small standalone CLI for maintenance, smoke testing, and direct preset copy flows.

What this package does

• Stores committed, static per-agent preset snapshots under presets/<agent>.
• Installs presets into a target project by copying files only.
• Detects project-local agent setup from committed detection rules.
• Infers PrimeUI AI presets where that mapping is intentionally supported.
• Applies the managed PrimeUI AI setup for codex, claude, and cursor.
• Validates committed presets against add-mcp, skills, and PrimeUI detection.

Supported agents

Full setup:

• claude-code
• codex
• cursor
• gemini-cli
• opencode

MCP only:

• vscode
• zed
• mcporter

Important caveat:

• inferPrimeUiAiPreset(...) is intentionally narrower than agent detection.
• It only returns PrimeUI-managed AI presets for agents that map to codex, claude, or cursor.
• For gemini-cli, opencode, and MCP-only agents, detection works, but inferPrimeUiAiPreset(...) intentionally returns undefined.

Standalone CLI

Binary name:

• primeui-agent-setup

Supported commands:

primeui-agent-setup --help
primeui-agent-setup --list-agents
primeui-agent-setup --agent <name>
primeui-agent-setup --agent <name> --target <path>
primeui-agent-setup --agent <name> --target <path> --overwrite

Behavior:

• --agent <name> installs the preset into the current working directory.
• --target <path> overrides the destination directory.
• --overwrite allows replacing existing files when a target file already exists.
• --list-agents prints the supported agent names.

Examples:

primeui-agent-setup --list-agents
primeui-agent-setup --agent codex
primeui-agent-setup --agent cursor --target ./apps/web
primeui-agent-setup --agent codex --target ./apps/web --overwrite

Importable API

Import from the package root:

import {
  installPrimeUiAgentPreset,
  detectPrimeUiLocalAgentSetup,
  inferPrimeUiAiPreset,
  listPrimeUiSupportedAgentPresets,
} from "@primeuicom/agent-setup";

Main exports are grouped like this:

Preset metadata and discovery:

• listPrimeUiSupportedAgents()
• listPrimeUiSupportedAgentPresets()
• getPrimeUiSupportedAgentPreset(agent)
• getPrimeUiAgentPresetDirectory(agent)
• listPrimeUiAgentPresetFiles(agent)

Detection and inference:

• detectPrimeUiLocalAgentSetup(projectDirectory)
• detectPrimeUiAiPresetCandidates(projectDirectory)
• inferPrimeUiAiPreset(projectDirectory)

Install and apply flows:

• installPrimeUiAgentPreset({ agent, targetDirectory, overwrite })
• applyPrimeUiAiSetup(projectDirectory, { aiPreset, env })
• createPrimeUiAiSetupEnv(env, primeUiApiBaseUrl)

Config and helper exports:

• listPrimeUiAiSkillCollections()
• listPrimeUiAiSkillRefs()
• resolvePrimeUiMcpConfig(env)
• listPrimeUiAllowedMcpServers()
• listPrimeUiAllowedShellCommands()
• listPrimeUiClaudeAllowedPermissions()
• listPrimeUiCursorAllowedPermissions()
• buildPrimeUiCodexConfigToml()
• buildPrimeUiClaudeSettings()
• buildPrimeUiClaudeSettingsFileContent()
• buildPrimeUiCursorCliConfig()
• buildPrimeUiCursorCliConfigFileContent()

Errors, constants, and types are also re-exported from the package root.

Maintenance model

Presets are static and committed.

That is intentional.

• Do not run skills or add-mcp inside client projects during installation.
• Update the preset snapshots inside this package repository first.
• Then copy those committed files into target projects.

Preset roots are fake project roots:

• presets/codex
• presets/claude-code
• presets/cursor
• presets/gemini-cli
• presets/opencode
• presets/vscode
• presets/zed
• presets/mcporter

Refreshing skills in a preset

Skills are committed static files and should be refreshed in the preset directory itself.

Use --copy so the preset stays self-contained and commit-ready:

cd packages/agent-setup/presets/codex

pnpm dlx skills@latest add github/awesome-copilot --agent codex --skill git-commit --copy -y
pnpm dlx skills@latest add vercel-labs/next-skills --agent codex --skill next-best-practices --copy -y
pnpm dlx skills@latest add wshobson/agents --agent codex --skill tailwind-design-system --copy -y

Replace codex with the preset agent you are maintaining.

For claude-code, skills are written into .claude/skills. For the other full-setup agents, skills are written into .agents/skills.

Refreshing MCP entries in a preset

MCP snapshots are also committed static files.

Update them only when the curated PrimeUI MCP contract changes.

For example, from a preset root:

cd packages/agent-setup/presets/codex

pnpm dlx add-mcp@latest -a codex -n primeui @primeuicom/mcp@latest --yes
pnpm dlx add-mcp@latest -a codex -n chrome-devtools chrome-devtools-mcp@latest --yes
pnpm dlx add-mcp@latest -a codex -n next-devtools next-devtools-mcp@latest --yes

Replace codex with the preset agent you are maintaining.

If you intentionally need a non-default PrimeUI MCP endpoint while refreshing a preset, add the environment override explicitly:

pnpm dlx add-mcp@latest -a codex -n primeui @primeuicom/mcp@latest --yes --env PRIMEUI_API_BASE_URL=https://app.xui.se

Validating preset snapshots

After refreshing preset files, run:

pnpm run validate:presets

This checks:

• add-mcp can read the committed MCP snapshots
• skills can read the committed skills snapshots for full-setup agents
• PrimeUI detection sees the expected agent and support level

Smoke testing

Run the full preset smoke test:

pnpm run smoke:test

What it does:

1. Creates packages/agent-setup/test-repo
2. Installs one preset into that empty directory through the standalone CLI entrypoint: primeui-agent-setup --agent <name> --target ./test-repo
3. Compares the installed files against the committed preset snapshot
4. Detects the installed agent and verifies it matches
5. Verifies inferPrimeUiAiPreset(...) only where a PrimeUI preset mapping is expected
6. Clears test-repo
7. Repeats for the next supported agent
8. Leaves test-repo empty at the end

You can also run it for a subset of agents:

pnpm run smoke:test -- codex cursor vscode