MagicPath

MagicPath is a canvas and component platform. Use this skill when the user mentions MagicPath, designs, UI components, themes/design systems, team projects, selected canvas items, or bringing local/repository UI into a MagicPath canvas.

Always run MagicPath CLI commands as:

npx -y magicpath-ai <command> -o json

Use JSON output for data-returning commands and -y for non-interactive installs.

First Step

Run:

npx -y magicpath-ai info -o json

If the user is not authenticated, run:

npx -y magicpath-ai login
npx -y magicpath-ai whoami -o json

Pick the Workflow

• Find or install a MagicPath component: search/list, confirm the right component, inspect it, then add/adapt it.
• Work with the current canvas: use selection -o json for selected components/images, or active-project -o json for the open project.
• Use team work: run list-teams -o json, then pass --team "<nameOrId>" to project, search, theme, or member commands.
• Use a theme/design system: list-themes -o json, then get-theme <id-or-name> -o json; apply CSS variables, fonts, and prompt guidance in the target app.
• Create or edit canvas components from code: use code start, edit only allowed files, then code submit --wait.
• Bring an existing repo UI into MagicPath: follow Working with repositories.
• Keep a MagicPath project open inside Codex's Browser when doing canvas work: follow Working with embedded browsers.

Find and Confirm Components

1. If the user refers to a selected design/component/image, run selection -o json.
2. If the user refers to the project they have open, run active-project -o json.
3. Otherwise search or browse:

npx -y magicpath-ai search "button" -o json
npx -y magicpath-ai list-projects -o json
npx -y magicpath-ai list-components <projectId> -o json

Search/list results include generatedName, project context, owner fields, and often previewImageUrl. Use previews when visual context matters.

Stop and ask for confirmation before installing or editing unless the user gave an exact generatedName, selected canvas item, or component/project id.

Create or Edit Canvas Components

Use this when the MagicPath canvas is the destination.

npx -y magicpath-ai code start --project <projectId> --dir <workdir> --name "Component Name" --width <px> --height <px> -o json
npx -y magicpath-ai code start --component <componentId> --dir <workdir> -o json
npx -y magicpath-ai code submit --dir <workdir> --wait -o json

Rules for code work:

• Run code start before writing files so the canvas shows the pending work.
• Edit only src/App.tsx, src/index.css, src/components/generated/**, and temporary image assets under assets/**.
• Usually leave src/App.tsx alone except for the theme value.
• Put real implementation in src/components/generated/<Name>.tsx; split larger pieces into sibling files there.
• Use Tailwind v4 through src/index.css; do not add tailwind.config.js.
• Keep output responsive, centered, and free of device/browser mockups unless explicitly requested.
• Build one screen per component. For related multi-view flows, use local React state inside one component; for independent screens, create separate components in separate workdirs.
• Make interactive surfaces actually interactive: controlled inputs, real handlers, toggles, tabs, dialogs, form validation, hover/focus/disabled states, and useful transitions.
• If selected canvas images are returned by code start, use the downloaded assetPath, not the short-lived accessUrl.
• If code submit fails, fix only allowed files and resubmit.

code context is read-only. Do not use it as the submit path.

Teams, People, and Ownership

• list-teams -o json: discover teams/workspaces.
• list-members --team "<team>" -o json: resolve people to user ids.
• list-projects --team "<team>" -o json: see team projects only.
• list-components <projectId> --created-by <userId> -o json: find work by a person in a team project.

Personal projects are private to their owner unless shared. Do not search another person's personal work; search team projects instead.

Project and Share Links

Use share when you need a URL without opening a browser:

npx -y magicpath-ai share <generatedName> -o json
npx -y magicpath-ai share <projectId> -o json

Use view only when intentionally opening the OS browser:

npx -y magicpath-ai view <generatedName>
npx -y magicpath-ai view <projectId>

Never run view commands in parallel.

References

• CLI reference
• Working with repositories
• Working with embedded browsers

Install Into an App

Use this when MagicPath is the source and the user's app is the destination.

1. Inspect first:

npx -y magicpath-ai inspect <generatedName> -o json

2. Read the target code before installing. Understand current props, callbacks, validation, layout, data flow, styling system, and accessibility behavior.
3. For React/TypeScript apps, install:

npx -y magicpath-ai add <generatedName> -y -o json

4. Import and render the installed component using the returned importStatement and usage.
5. Adapt the installed source in src/components/magicpath/<name>/:
   • Replace static text and mock data with props or real project data.
   • Wire events, loading, error, empty, disabled, focus, and keyboard states.
   • Make fixed dimensions responsive.
   • Preserve existing behavior when replacing an existing component.
   • Match the app's styling and state-management patterns.

Do not run add just to read code. Use inspect for read-only source. For non-JS projects, inspect and translate the design into the target framework instead of running add.