Magicpath

MagicPath

A platform for building, sharing, and installing UI components via AI. Components are added as source code to the user's project via the magicpath-ai CLI.

MagicPath canvas components can also be created and edited directly from local code via the npx -y magicpath-ai code ... subcommands — see Edit or create canvas components from code. That path is strict: only src/App.tsx, src/index.css, files under src/components/generated/, and temporary image assets under assets/ in the code working directory are editable.

When this skill runs inside an agent host with an embedded browser, use a MagicPath project as a persistent visual canvas beside the agent when appropriate. If you create a project for canvas authoring, open that project in the embedded browser immediately after creation and before code start; see Working with embedded browsers.

Terminology: Users often refer to MagicPath components as "designs" — the two terms are interchangeable. When a user says "design," "my designs," or "that design," treat it as meaning a MagicPath component. Search, inspect, and install accordingly.

>

Users also refer to MagicPath design systems as "themes." When a user says "theme," "my themes," or "use the X theme," they mean a MagicPath design system — a set of CSS variables, fonts, and styling instructions. Use list-themes and get-theme to work with them.

>

Users may belong to teams (also called "workspaces"). When a user says "the team's designs," "our team's components," or mentions a team name like "Acme Inc," they mean the projects and components owned by that team. Use list-teams, --team, and --personal flags to navigate between personal and team workspaces.

>

Users may also ask about skills they created in MagicPath. These are reusable instruction bundles that can be invoked from MagicPath chat and managed with npx -y magicpath-ai skills .... Personal skills live in the user's workspace; team skills live in a MagicPath team. Public MagicPath skills are read-only unless the platform says otherwise.

First Step

Run npx -y magicpath-ai info -o json to check auth status and project context. The first invocation may take a few seconds as npx downloads the package; subsequent calls are fast.

• If auth.authenticated is false, run npx -y magicpath-ai login, wait for browser auth to finish, then verify with npx -y magicpath-ai whoami -o json.

Guest Sessions

If the user gives you a pairing code (a short code like gst_…, usually because they're trying MagicPath without an account), connect with it once:

npx -y magicpath-ai login --guest-code <code>

Then run npx -y magicpath-ai whoami -o json — it reports guest: true, the one projectId you can work with, and a canvasUrl. Build on that project with the normal code start --project <projectId> → code submit flow; every submit appears live on the canvas.

A guest session is scoped to that single project and expires. Within it:

• Use code start / code submit to create and edit designs on the project — this is the whole point of the session.
• A guest session includes a limited number of free builds (creating or editing a design each counts as one build). Once the limit is reached, the next attempt to create or edit returns an error right away saying the free builds are used up — relay it to the user and let them know they can sign up at https://magicpath.ai to keep building and save the project.
• In a host with an embedded browser, open the canvasUrl (from whoami) so the user can watch their canvas update beside you. The canvasUrl is the only way to open a guest canvas — do not use share or view, which require a full account.
• Other workspace features (teams, additional projects, themes) belong to full accounts. If a command reports it needs an account, or the session has expired, tell the user they can sign up at https://magicpath.ai to keep the project and unlock everything else. Never tell a guest to run login without a pairing code.

Working with Teams

Users may belong to teams that own shared projects and themes. By default, list-projects and search return results from all workspaces (personal + every team the user belongs to). Use filtering flags to narrow scope.

Discovering Teams

Run npx -y magicpath-ai list-teams -o json to see the user's teams:

{ "teams": [{ "id": "123", "name": "Acme Inc", "role": "ADMIN" }] }

Filtering by Team

• Default (no flag): list-projects, search include both personal and all team projects — no extra flags needed for broad discovery.
• `--team "Acme Inc"` or `--team <teamId>`: Filter to a specific team. Works on list-projects, search, list-themes, and get-theme.
• `--personal`: Show only the user's personal projects/components. Works on list-projects and search.

JSON Output

Projects and search results include ownerType ("personal" or "team") and ownerName (user email or team name). Use these to tell the user where a component lives.

Discovering People

Run npx -y magicpath-ai list-members --team "Acme Inc" -o json to see who's on a team:

{ "team": { "id": "123", "name": "Acme Inc" }, "members": [{ "id": "456", "displayName": "Chloe Smith", "email": "chloe@acme.com", "role": "MEMBER" }] }

Filtering by Person

• `--created-by <userId>` on list-components: Filter to components that a specific user has created or edited. Use this after resolving a person's name to their user ID via list-members.
• `createdBy` field on projects: Each project in list-projects includes createdBy: { id, displayName } showing who created it.
• `lastEditedBy` field on components: Each component in list-components includes lastEditedBy: { id, displayName } showing who last edited it.

Important: You can only see projects that the authenticated user has access to — your own personal projects and team projects you're a member of. You cannot access another user's personal projects. When looking for another person's work, only search team projects (--team), not personal projects. Personal projects are private to their owner unless someone is explicitly invited as a member.

Common Patterns

• "What was Chloe working on last?" → list-members --team "Acme Inc" -o json to find Chloe's user ID → list-projects --team "Acme Inc" -o json to get team projects only → list-components <projectId> --created-by <chloeId> --sort-by createdAt --order desc -o json for each project. Report the most recent components. Do not search personal projects for another user's work — personal projects are private to their owner.
• "Show me the team's designs" or "what has Acme Inc created?" → list-teams to find the team, then list-projects --team "Acme Inc" -o json, then list-components <projectId> -o json.
• "Show me the latest design from the team" → same as above, but use --sort-by createdAt --order desc --limit 1 on list-components.
• "Who created this project/component?" → check the createdBy field on projects or the lastEditedBy field on components from their respective list commands.
• "My designs" without mentioning a team → the default (all projects) is usually correct. Only use --personal if they explicitly want to exclude team projects.
• "Use the team's theme" → list-themes --team "Acme Inc" -o json, then get-theme <name> --team "Acme Inc" -o json.

Managing MagicPath Skills

Use this flow when the user asks to create, list, inspect, update, import, delete, enable/disable, or locally install skills stored in MagicPath. Prefer JSON mode for every data-returning command:

npx -y magicpath-ai skills list -o json
npx -y magicpath-ai skills list --team "Acme Inc" -o json
npx -y magicpath-ai skills get <skillIdOrSlug> -o json
npx -y magicpath-ai skills create --name "Skill name" --description "When to use it" --instructions-file ./SKILL.md -o json
npx -y magicpath-ai skills import ./skill-package.skill -o json
npx -y magicpath-ai skills update <skillIdOrSlug> --disable -o json
npx -y magicpath-ai skills delete <skillIdOrSlug> -y -o json

Scope and Ownership

• Use --team <nameOrId> when the user says the skill belongs to a team/workspace.
• Omit --team for personal skills.
• skills list includes public MagicPath skills by default because those are available to the user in chat. Pass --owned-only when the user wants skills they can edit.
• Public skills are read-only. Do not try to update or delete public skills unless the command output clearly identifies them as owned/editable.
• Imported .zip or .skill packages are content-immutable in MagicPath; they can still be enabled or disabled with skills update <id> --enable/--disable.

Creating or Updating Skills

• For more than a short one-line instruction, write the instructions to a local file and use --instructions-file. This avoids shell quoting problems and preserves Markdown.
• A MagicPath skill requires a non-empty name, description, and instructions. The description should say when the skill should be used; the instructions should say how to do the work.
• If a user is turning an observed workflow into a reusable skill, summarize the trigger, constraints, steps, examples, and any files or references the future agent should read.

Installing a MagicPath Skill Locally

When a user wants a skill from MagicPath installed into their external coding agent, first retrieve it, then recreate it as a local Agent Skills folder:

1. Run npx -y magicpath-ai skills get <skillIdOrSlug> -o json. 2. Create a folder named after the skill slug. 3. Write SKILL.md with frontmatter containing at least name and description, followed by the retrieved instructions:

---
name: example-skill
description: Use when ...
---

...instructions from MagicPath...

4. If the skill has bundled package files, run npx -y magicpath-ai skills get <skillIdOrSlug> --files -o json, then fetch each file with --file <path> and recreate the same relative paths in the local skill folder. 5. Install or register that folder using the current agent host's local skill workflow. If the host supports the Agent Skills CLI, install from the local folder with that tool; otherwise place the folder in the host's documented local skills directory.

Ask before writing outside the user's current project or into a global agent configuration directory.

Workflow

Always use `-o json` for all data-returning commands (search, list-projects, list-components, list-teams, list-themes, get-theme, skills, selection, active-project, info, add, inspect, code). This gives you structured output to work with instead of human-readable tables.

Phase 1: Discover

1. Check auth — run npx -y magicpath-ai whoami -o json to verify authentication. 2. Check current selection — if the user references "the selected component," "the selected image," "the design I have selected," or otherwise points at a specific canvas selection, run npx -y magicpath-ai selection -o json. If it returns components, use them directly — skip the search/confirm flow and proceed with the returned generatedName(s). Each returned component also includes selectedRevisionId, the revision currently shown for that component on the canvas. The response can also include selected images; when you subsequently run code start, those selected images are made available under assets/selected/** as described below. When a downstream command accepts a revision (such as code context --revision), pass this value through so the operation targets the version the user is looking at rather than whichever revision happens to be canonical in the database. 3. Check the active project — if the user references "the project I have open," "this project," "what I'm working on," or otherwise implies a working project context without naming a specific component, run npx -y magicpath-ai active-project -o json. It returns the project(s) the user currently has open in their browser, even when nothing is selected. If it returns one project, treat it as the working project and skip the project picker. If it returns multiple, list them and ask which one. If it returns an empty list, the user has no canvas open — reach for list-projects and ask the user. Pick the right command for what the user said: selection for a referenced component, active-project for a referenced project, list-projects + ask if neither. (Note that selection also returns the active projects in its output, so when the user references a component you already get the project for free — no separate active-project call needed.) 4. Find components — use npx -y magicpath-ai search <query> -o json to search across all projects, or list-projects -o json then list-components <projectId> -o json to browse. If active-project already gave you a project, scope your search to it via list-components <projectId> -o json instead of searching every workspace. 5. See a project's images — to know which standalone images already live on a project's canvas (to reference them, avoid duplicating them, or describe them to the user), run npx -y magicpath-ai image list <projectId> -o json and download each url to view it — the same way you use previewImageUrl for components. (These are canvas images, separate from the assets/ build inputs in the code flow.) 6. Understand components visually — search and list-components results include a previewImageUrl field. Download and analyze these images to understand what each component looks like before recommending it. Preview images are for your own understanding — do not navigate the embedded project canvas to an individual design preview unless the user explicitly asks to see that design there. 7. Confirm with the user (STOP and wait) — unless the user specified an exact generatedName, tell the user what you found (name, generatedName, project) and ask if it's the right component. When an embedded project canvas is active, keep it on the project and only open or share an individual design if the user explicitly asks. Without an embedded project canvas, open a browser preview with npx -y magicpath-ai view <generatedName> as the normal confirmation fallback. If multiple matches, list them all and ask which one. This is a STOP point — end your response here and wait for the user to reply. Do NOT proceed until the user explicitly confirms. Do not run add or inspect yet.

Phase 2: Understand the Target Context

This phase is critical. Before installing anything, you MUST understand where the component is going and what it needs to do there. Skipping this leads to components that look right but behave wrong.

7. Inspect the MagicPath component source — use npx -y magicpath-ai inspect <generatedName> -o json to read the source code. Identify what it renders, what props it expects, and what assumptions it makes about layout (fixed widths, absolute positioning, etc.). 8. Read the target codebase context — before installing, read the file(s) where the component will live. Understand:

• Existing functionality: If replacing a component, what does the current one do? What callbacks, state, API calls, navigation, validation, or side effects does it handle? Every piece of existing behavior must be preserved or consciously addressed.
• Layout context: What is the parent layout? Is it a flex/grid container? What are the responsive breakpoints? How does spacing work? A component that looks perfect in isolation can break a layout if its sizing assumptions don't match.
• Data flow: What props, context, or state does the surrounding code provide? What does it expect back (callbacks, form data, events)?
• Design system: What styling patterns does the project use (Tailwind, CSS modules, theme tokens)? The MagicPath component's styles need to harmonize, not clash.

Applying a Theme (if applicable)

If the user has a theme they want applied, or references a brand/design system by name:

1. List available themes — run npx -y magicpath-ai list-themes -o json to see all themes. 2. Get the theme definition — run npx -y magicpath-ai get-theme <id-or-name> -o json to fetch the full definition. 3. Read the `prompt` field — if present, this contains natural-language styling instructions from the designer (e.g., "use rounded corners, prefer shadows over borders, use the brand blue for CTAs"). Follow these instructions when adapting components. 4. Apply CSS variables — the theme's light and dark objects map CSS variable names to values (e.g., --background: #ffffff, --primary: #3b82f6). When adapting MagicPath components, use these CSS variables instead of hardcoded colors: bg-[var(--background)], text-[var(--primary)], etc. Ensure the component respects defaultTheme (light or dark). 5. Handle fonts — if the theme includes fonts, ensure the project loads these fonts (Google Fonts link or @font-face declarations for custom fonts) and that components reference them via the theme's font CSS variables (e.g., font-family: var(--font-body)). 6. Non-React/JS projects — theme data is a reference, not a stylesheet. Translate CSS variables into the target platform's equivalent: SwiftUI Color assets, Android theme XML, Python template context, etc. The prompt field and color/font values express platform-agnostic design intent — map them to native patterns rather than using CSS directly.

Create or Edit Canvas Components From Code

Use this flow only when the user wants to author a MagicPath canvas component directly:

npx -y magicpath-ai code start --project <projectId> --dir . --name "Component Name" -o json
npx -y magicpath-ai code start --component <componentId> --dir . -o json
npx -y magicpath-ai code context <componentId> --dir . -o json  # read-only
npx -y magicpath-ai code submit --dir . --wait -o json

code start is the only command that begins a stateful coding session. Use --project to create a new component, or --component to edit an existing one. It writes editable files, creates or reuses a pending revision on the canvas, and shows agent presence.

code context is read-only. Use it only to inspect existing component source; it must not be used as the submit path.

Edit only these surfaces: src/App.tsx, src/index.css, src/components/generated/**, and temporary image assets under assets/**.

src/App.tsx is pre-wired to render the generated component. Only edit it to change the top-level theme value.

If image shapes are selected on the canvas when you run code start, the JSON response may include selectedImages. The CLI downloads those short-lived image URLs into assets/selected/**. Use the local assetPath from the response in TSX/CSS, and never paste the temporary accessUrl into component source because it expires.

Tailwind v4 Rules

The MagicPath template uses Tailwind v4. Style this way:

• src/index.css must contain @import 'tailwindcss';, not @tailwind base;, @tailwind components;, or @tailwind utilities;.
• Theme tokens (bg-background, text-foreground, border-border, bg-primary, etc.) are wired via the @theme inline { ... } block in index.css. Do not remove it.
• The :root and .dark blocks define the actual token values. Do not remove them.
• To add custom utility classes, append them to index.css instead of replacing existing content.
• There is no tailwind.config.js. Configuration lives in index.css via Tailwind v4's @theme directive.

Phase 3: Install and Adapt

9. Add to project — use npx -y magicpath-ai add <generatedName> -y to install component files. Always pass -y in non-interactive contexts. If this is a non-React project (Swift, Python, etc.), do not run `add` — use npx -y magicpath-ai inspect <generatedName> -o json to read the source as a reference, then recreate the component in the target language and framework. 10. Adapt the component for production use — MagicPath components are design artifacts: they capture visual intent and structure, but they are often not production-ready out of the box. After adding, you MUST edit the component files to:

• Make it responsive: Replace any hardcoded widths/heights (e.g., w-[300px]) with responsive utilities (w-full max-w-sm, responsive breakpoints like md:w-64 lg:w-80). A design may show a single viewport — your job is to make it work across all viewports.
• Add real interactivity: Replace static/placeholder content with actual props, state, and event handlers. A MagicPath button that says "Submit" needs an onClick prop and loading state. A form needs validation and onSubmit.
• Wire up data flow: Connect the component to the app's actual data — props from parents, context providers, API calls, router state. Don't leave mock data in place.
• Preserve existing functionality: When replacing an existing component, audit every feature the old one provided (form submission, error handling, loading states, accessibility, keyboard navigation, analytics events) and ensure the new component handles all of them.
• Match the project's patterns: Use the same state management, error handling, and styling approaches as the rest of the codebase.

Phase 4: Integrate into the Page

11. Import and render — import the component using the importStatement from the add output. Pass the props you've defined. 12. Verify layout fit — after placing the component, review the parent layout to ensure it integrates cleanly. Check that the component doesn't overflow, create unexpected gaps, or break the responsive flow of the page.

Design-to-Production Mindset

MagicPath is a design tool. Components from MagicPath represent what something should look like and how it should be structured — they are the design spec expressed as code. But a design comp and a production component are different things:

The golden rule: a MagicPath component tells you WHAT to build. Your job is to make it WORK — responsively, accessibly, and fully wired into the application.

Common Scenarios

Replacing an existing component (e.g., swapping an old login form for a MagicPath design): 1. Read the old component thoroughly — list every prop, callback, validation rule, and side effect 2. Inspect the MagicPath component source with npx -y magicpath-ai inspect <generatedName> -o json 3. Install the MagicPath component with npx -y magicpath-ai add <generatedName> -y 4. Edit the MagicPath component to accept all the same props/callbacks 5. Ensure every feature from the old component exists in the new one 6. Swap the import in the parent — the parent code should barely change

Building a new page from a MagicPath design library: 1. Browse the project's components with list-components 2. Plan the page layout first — identify which MagicPath components map to which sections 3. Install needed components one at a time with npx -y magicpath-ai add <generatedName> -y 4. Build the page layout, importing each component 5. Adapt each component: responsive sizing, real data, proper routing, state management 6. Ensure consistent spacing, typography, and color usage across all components

Using a single MagicPath component as inspiration: 1. Inspect the source with npx -y magicpath-ai inspect <generatedName> -o json 2. Understand the design intent — colors, spacing, layout structure, typography 3. Install and adapt it, or use it as a reference to build something custom that follows the same design language

Critical Rules

• `add` means install-to-use. Only run add when you intend to import and render the installed component. If you just want to read the source code, use inspect instead.
• After `add`, always import the component. The whole point of add is to get source files you then import. Never add a component and then copy its styles/markup into another file — import and render the component directly.
• MagicPath components are source code you own. After add, the component files live in your project at src/components/magicpath/<name>/. You can and should edit them directly to add props, change behavior, adjust styles, or integrate with your app's state.
• When a component needs integration: (1) add the component, (2) edit the component file to accept the props you need (e.g., onSubmit, placeholder, className), (3) import it from the parent and pass those props. Do NOT copy the component's JSX/styles into the parent file.
• Never just drop a component in. Always read the surrounding code, understand the layout constraints, and adapt the component to fit. A MagicPath component placed without adaptation is a bug, not a feature.
• `inspect` is read-only. Shows full source code without writing any files. Use this when deciding whether a component fits your needs before committing to install.
• `add` is for React/TypeScript projects only. The add command writes .tsx files to src/components/magicpath/ and installs npm dependencies. Only use add in JavaScript/TypeScript projects. For non-JS projects (Swift, Python, etc.), use inspect to read the component source, then translate the design and behavior into the project's language and framework.
• Never run `view` commands in parallel. The view command opens a browser window for the user. Only open one target at a time.
• Keep an embedded browser on the project canvas. Do not navigate it to individual design previews unless the user explicitly asks; return a design share link instead when that is sufficient.
• Open a newly created project before authoring into it. When an embedded browser is available and the request includes work inside a new project, show the project canvas immediately after create-project and before code start or code submit.

Creating a project

A project is the workspace that holds designs/components. Use this when the user explicitly asks to create a project ("make a new project called …", "create a project for …"), or when they ask for a new design but no project context exists yet and a fresh project is the right home for it.

Picking the workspace

Before creating, decide whether the project is personal or belongs to a team:

• If the user names a team ("create a project in Acme Inc"), resolve that team and pass it through.
• If the user says "create a personal project" or doesn't mention a team and has no teams, default to personal.
• If the user is ambiguous and belongs to one or more teams, run npx -y magicpath-ai list-teams -o json and ask which workspace — personal or one of the teams. Don't guess. STOP and wait for the user to reply.

Running the command

npx -y magicpath-ai create-project --name "My Stuff" -o json                       # personal
npx -y magicpath-ai create-project --name "My Stuff" --team "Acme Inc" -o json     # team

• --name is optional. If omitted, the project gets an auto-generated placeholder name. Always pass --name when the user told you what to call the project.
• --team accepts a team name or team ID. Resolve the user's intent to one of the teams returned by list-teams.
• JSON output: { project: { id, name, ownerType, ownerName, ... } }. The id is what subsequent commands need.

After the project exists

If the user also asked for a design inside the new project, take the id from the response and continue with the canvas-component creation flow described under Edit or create canvas components from code (code start --project <id> --name "...", fill in the scaffolded files, code submit --wait). Do not re-create the project per design — one project holds many components.

When the task includes creating or editing designs inside a newly created project, treat that project as the canvas. In an embedded-browser host, the order is mandatory: immediately after create-project returns an id, run npx -y magicpath-ai share <projectId> -o json, open the returned project URL in the embedded browser, and only then begin code start or code submit. Keep that project canvas visible while work appears there; do not navigate to the generated design preview after submission unless the user explicitly asks to see that design alone. If no embedded browser exists, use npx -y magicpath-ai view <projectId> when user-facing navigation is needed.

Use a MagicPath project as an embedded canvas when available

Some agent hosts, including Codex and some Cursor workflows, can provide an embedded or in-app browser. When that capability is available, a MagicPath project can remain open beside the agent as a persistent canvas: the agent works from local code and context while the user sees and selects work on the canvas.

Use this for opening a newly created project, reconnecting to the user's active project, or beginning canvas authoring in a named project. Do not automatically navigate the embedded browser to an individual design or component; only show one there when the user explicitly asks to open that specific design.

For a project, do not call view first in an embedded-browser host: view opens the operating-system browser. Instead, run npx -y magicpath-ai share <projectId> -o json to get its URL without opening a window, then navigate the host's embedded browser to the returned url. If no embedded browser exists, it cannot be controlled reliably, or the user explicitly wants their normal browser, use view <projectId>.

CLI authentication and embedded-browser authentication are separate. A successful whoami or create-project command does not mean the visible browser pane is signed into MagicPath. If opening the returned /files/<projectId> URL redirects to the home or sign-in experience, keep the task focused on that project: tell the user to sign into MagicPath in the embedded browser, then navigate back to the same project URL after sign-in. Do not substitute a public individual-design preview just because it loads without the project-canvas session.

Do not open a project automatically for background work such as info, whoami, listing/searching data, retrieving themes, inspecting source, or installing a component into an application. Full decision guidance and recipes live in Working with embedded browsers.

Bring an existing repository into MagicPath

When the user wants to take UI that already exists in a Git repository — local or online — and reproduce it on their MagicPath canvas (e.g. "bring the sidebar of my app into MagicPath", "render this project in MagicPath", "recreate my landing page here"), recreate it as a canvas component via the code start → code submit flow.

This is the inverse of add/inspect: the source of truth is the user's repository and the destination is the canvas. Do not use add, inspect, or code context for this. The short version:

1. Get the code — read a local path directly, or git clone --depth 1 <url> an online repo into a scratch directory (kept separate from your --dir). Private repos need the user's credentials — ask, don't guess. 2. Read the design foundation first — global CSS (globals.css/index.css/app.css), design tokens (tailwind.config.*, CSS variables, token files), fonts, theming strategy, and shared UI primitives. This is what makes the recreation faithful rather than approximate. 3. Resolve the target — for a single element (e.g. the sidebar), open its file and follow all its imports (child components, icons, styles, data) plus the layout parent that gives it size and position. For a whole page/project, identify the entry and decide one interactive frame vs. separate frames per screen (Design Default rule 5) — ask if ambiguous and stop and wait. 4. Recreate on the canvas — code start --project <id> --dir <workdir> --name "..." --width <px> --height <px>, fill src/components/generated/<Name>.tsx faithfully (translate the repo's framework and styling into React + Tailwind v4), match colors/spacing/typography exactly, wire real interactivity, mock data locally, then code submit --wait. Honor the Design Defaults (responsive, centered, no device mockups, single screen, fully interactive). 5. Verify the result against the source app with view.

Full step-by-step guidance — the styling-translation table, edge cases (monorepos, non-React sources, server components, Tailwind v3→v4), and quick recipes for "bring the sidebar of my app" and "render this project" — lives in Working with repositories.

Edit or create canvas components from code

Use this workflow when the user wants you to author or modify a MagicPath canvas component itself — not install an existing component into a separate application. The code subcommands operate on a working directory and a small manifest file (magicpath-code.json) that tracks which component and revision the directory belongs to.

*When authoring on the MagicPath canvas, you are an expert design engineer who builds beautiful, functional, interactive React components.* Components you produce on the canvas (via code start / code submit) should be real working mini-apps, not static design comps: state-driven, hover / focus / active states wired up, buttons that do something, forms that validate, transitions that feel deliberate. A pretty but lifeless component is a failed component. (This persona applies only to the code flow — when you're installing components into a user's project with add/inspect, follow the Design-to-Production Mindset instead.)

SUPER IMPORTANT — Design Defaults

These rules apply to every canvas component you create or edit with the code subcommands, unless the user explicitly overrides them in the request. They do not apply to the add/inspect install flow — for that, see the Design-to-Production Mindset. These rules override anything else in this skill for canvas authoring.

1. NEVER add device mockups

Do NOT wrap components in iPhone / Android / laptop / desktop / browser frames, status bars, notches, home indicators, address bars, or any other device chrome. Only add a device mockup if the user explicitly asks for one ("show this inside a phone frame", "wrap it in an iPhone mockup", "make it look like a Mac window"). Designing for a mobile viewport is not a request for a mockup — the canvas itself is the device frame. Never draw a second device inside it.

2. Everything is responsive — always

Every component must work at any width, including small primitives like buttons, inputs, badges, and cards. Use w-full, max-w-*, percentage widths, flex/grid sizing, and breakpoint utilities (sm:, md:, lg:). Do not hardcode pixel widths/heights on outer containers. The only exceptions are intrinsically fixed elements (avatars, icons, fixed-size media).

3. Always centered inside the canvas

The root of the component should center itself in its frame — horizontally, and vertically when the design is short. Use min-h-screen flex items-center justify-center, mx-auto, or grid centering on the root. The design must never stick to a corner when the canvas is larger than the content, and must never overflow when it's smaller.

4. Canvas size ≠ device mockup

You may (and should) pass --width/--height to code start / code submit to reflect the target device — e.g. --width 390 --height 844 for a mobile design, --width 1440 --height 900 for desktop. That's how you signal "this is a mobile design." But the content inside must remain fluid: if the same component is dropped into a wider or narrower container later, it should adapt — not stay locked to the original pixel size.

5. NEVER stack multiple screens inside one frame

A MagicPath component is one frame. Do not draw "Screen 1 / Screen 2 / Screen 3" side-by-side, vertically stacked, or as a slideshow inside a single canvas. That output is broken — it doesn't render, it doesn't navigate, and it wastes the user's canvas.

When the user wants something that spans multiple views, pick one of these two patterns and stick to it:

A. Self-contained app in ONE frame (preferred when the views belong to the same flow). A single component can hold many views, screens, modals, tabs, steps, or routes by using React state, conditional rendering, tab components, client-side routing, or useState-driven view switching. A login → signup → forgot-password flow, a multi-step wizard, a settings page with tab navigation, a dashboard with a slide-out detail panel — all of these belong in one component with internal state, not several frames glued together.

B. Multiple frames (one component per screen) when the screens are truly independent. If the user is asking for distinct deliverables — "design the login screen, the dashboard, and the settings page" — each one is its own MagicPath component. Create them as separate code start --name "..." sessions, each with its own `--dir` (parallel sessions that share a working directory will overwrite each other's magicpath-code.json). Build them concurrently — if your environment supports parallel sub-agents, spawn one per frame; otherwise run the sessions in parallel however your runner allows. Do not try to render them all in a single canvas to "save time" — it produces a broken artifact.

If you're unsure which pattern fits, ask the user: "Should this be one interactive component with internal navigation, or separate frames for each screen?" — and stop and wait for the answer.

6. Build interactive components, not static markup

You are an engineer, not a screenshot generator. Every canvas component must be fully interactive — buttons trigger real actions, inputs are controlled, forms submit and validate, hover / focus / active / disabled states are styled, modals open and close, tabs switch, drawers slide, dropdowns expand, toggles flip, accordions collapse. Use useState / useReducer for local state, real event handlers (onClick, onChange, onSubmit, onKeyDown, onBlur), aria-* attributes for accessibility, and meaningful transitions (Tailwind transition-*, Framer Motion, or CSS animations) where they add polish. A component left with placeholder onClick={() => {}} or static markup of an interactive surface is not done — wire it up before code submit. If the component represents a multi-view flow, make the navigation between views work via state (see rule 5.A).

Editable file boundary. The code API only accepts full-file replacements for:

• src/App.tsx
• src/index.css
• src/components/generated/**
• assets/** for temporary image assets only

Never edit or submit package.json, vite.config.*, src/main.tsx, lockfiles, or any other file — they will be rejected.

Image assets. Put local image files in <workdir>/assets/ and reference them from code or CSS, for example ../../../assets/hero.png, /assets/hero.png, or url("../../assets/hero.png"). MagicPath uploads these temporary assets, rewrites references to stable public asset URLs, and removes the assets/ staging folder before build. Do not inline data:image/...;base64,...; if you encounter base64 image data, move it into an asset file instead.

Selected canvas images. When the user has selected image shapes on the canvas before code start, the CLI includes them in selectedImages and downloads each one into assets/selected/** using a short-lived access URL. Use the downloaded assetPath in imports or CSS. Do not use accessUrl directly because it expires.

Deleting and renaming source files is supported in edit mode. To delete an editable source file, just remove it from <workdir> — code submit detects the deletion and propagates it. A rename is a delete + a write in the same submit. Assets are temporary staging inputs and are not deleted from the server by removing local files. In create mode, there's nothing to delete; just don't write the file.

Do not use `add` or `inspect` for this workflow. add/inspect are for installing reusable registry components into another app. code ... is for editing components on the user's MagicPath canvas — they are separate flows and must not be mixed.

Edit an existing component

1. Run npx -y magicpath-ai code start --component <componentId> --dir <workdir> -o json. This creates or reuses a pending edit revision, shows agent presence on the canvas, writes the editable files, and writes magicpath-code.json into <workdir>. By default, the CLI starts from the component's currently selected revision. To start from a specific revision instead, pass --revision <revisionId> — useful when the user is viewing or referring to a non-current revision (e.g. a value carried through from npx -y magicpath-ai selection). 2. Edit, add, or delete allowed files inside <workdir> (see the boundary above). Put any new images under <workdir>/assets/ and reference them from the generated component or CSS. When you remove the last usage of a sub-component file, delete its source file too — don't leave orphan files in the revision. Renames are delete-plus-write. 3. Run npx -y magicpath-ai code submit --dir <workdir> --wait -o json. If your edit changes the intended canvas size, pass both --width <px> and --height <px> on submit. 4. If the job result is failed, read the returned sanitized diagnostics, fix only allowed files, and submit again. Do not create a new component to work around a build failure. 5. If the submission reports a conflict or stale base, run npx -y magicpath-ai code start --component <componentId> --dir <workdir> -o json again to refresh the stateful edit session before re-applying your edits.

Create a new component

Important experiential rule: always run code start before writing component files. This registers the pending component on the canvas so the user sees your work-in-progress presence, not a silent agent.

Expected file structure. A MagicPath component has a slim src/App.tsx that imports and renders a top-level component from src/components/generated/. The actual implementation lives in src/components/generated/<ComponentName>.tsx (PascalCase filename, named export). Larger components should be split into additional sibling files under src/components/generated/, each importing what it needs. This is how every existing MagicPath component is structured — compare against what code context returns for any existing component.

The CLI scaffolds this structure for you on `code start`. After code start returns, the working directory already contains a pre-wired src/App.tsx and a stub src/components/generated/<ComponentName>.tsx. The component filename matches the PascalCase form of --name (e.g. --name "Hero Card" → HeroCard.tsx). Your job is to fill in the stub — do not rewrite `App.tsx`, it's already correct. The only reason to edit App.tsx is to change the theme ('light'/'dark') value at the top.

Steps: 1. Run npx -y magicpath-ai code start --project <projectId> --dir <workdir> --name "Component Name" --width <px> --height <px> -o json. Choose dimensions that fit the component you plan to build instead of relying on the default canvas size. Creates the pending component, scaffolds the slim App.tsx + stub, and writes magicpath-code.json. Reminder: the component must be responsive, centered, free of device mockups, a single screen (use internal state for multi-view flows, or parallel code start sessions for separate screens), and fully interactive (real handlers, controlled inputs, state-driven views, hover/focus/active states). See the Design Defaults above. 2. Fill in <workdir>/src/components/generated/<ComponentName>.tsx with the component implementation. Split into additional files in the same directory if the component is substantial. 3. Optionally edit <workdir>/src/index.css for custom styles. Put image files in <workdir>/assets/ and reference them from TSX or CSS instead of embedding base64. 4. Run npx -y magicpath-ai code submit --dir <workdir> --wait -o json. If the final implementation needs a different canvas size than you chose at start, pass both --width <px> and --height <px> here. 5. If the build fails, fix the component files and re-run code submit --wait. Do not start a second component unless the user explicitly asks.

The code create command is a convenience that combines start and submit in one call. Prefer the explicit two-step flow — it makes your progress visible on the canvas while files are still being written, and it gives you the scaffolded starting point to work from.

Polling a job separately

If you need to check job status after the fact (for example, after submitting without --wait), use npx -y magicpath-ai code status <jobId> -o json. It returns one of pending, processing, completed, failed, or cancelled.

Quick Reference

# Auth
npx -y magicpath-ai login                    # one-click browser login
npx -y magicpath-ai whoami -o json           # check auth status
npx -y magicpath-ai info -o json             # full project context

# Teams and people
npx -y magicpath-ai list-teams -o json                  # list teams you belong to
npx -y magicpath-ai list-members --team "Acme" -o json  # list members of a team

# Create a new project
npx -y magicpath-ai create-project --name "My Stuff" -o json                    # personal
npx -y magicpath-ai create-project --name "My Stuff" --team "Acme" -o json      # team

# Find components (always use -o json)
npx -y magicpath-ai search "input box" -o json          # search across all workspaces
npx -y magicpath-ai search "button" --team "Acme" -o json   # search within a team
npx -y magicpath-ai list-projects -o json               # list all projects (personal + team)
npx -y magicpath-ai list-projects --team "Acme" -o json     # list only team projects
npx -y magicpath-ai list-projects --personal -o json        # list only personal projects
npx -y magicpath-ai list-components <id> -o json      # list components in a project
npx -y magicpath-ai list-components <id> --created-by <userId> -o json  # filter by person

# Inspect / open components and projects
npx -y magicpath-ai view <generatedName>              # open a component preview in browser
npx -y magicpath-ai view <projectId>                  # open a project in browser
npx -y magicpath-ai share <generatedName> -o json     # print a shareable URL for a component (no browser open)
npx -y magicpath-ai share <projectId> -o json         # print a shareable URL for a project (no browser open)
npx -y magicpath-ai inspect <generatedName> -o json   # show source code (no install)
npx -y magicpath-ai add <generatedName> --dry-run     # show what would be installed

# Install and use components
npx -y magicpath-ai add <generatedName> -y         # add to project (no prompts)

# Themes (design systems)
npx -y magicpath-ai list-themes -o json                 # list personal themes
npx -y magicpath-ai list-themes --team "Acme" -o json   # list team themes
npx -y magicpath-ai get-theme <id-or-name> -o json    # get theme CSS vars, fonts, prompt

# Current canvas context
npx -y magicpath-ai selection -o json                 # get currently selected component(s)
npx -y magicpath-ai active-project -o json            # get the project(s) the user has open

# Project canvas images
npx -y magicpath-ai image list <projectId> -o json            # list images on the project canvas (download each `url` to see it)
npx -y magicpath-ai image add <projectId> ./hero.png -o json  # add a local image (or an http(s) URL) to the canvas

# Author/edit canvas components from code (external-agent)
npx -y magicpath-ai code start --project <projectId> --dir <workdir> --name "Name" --width <px> --height <px> -o json # start a new pending component with chosen canvas size
npx -y magicpath-ai code start --component <componentId> --dir <workdir> -o json                 # start editing an existing component
npx -y magicpath-ai code start --component <componentId> --revision <revisionId> --dir <workdir> -o json # start editing a specific revision
npx -y magicpath-ai code context <componentId> --dir <workdir> -o json                           # read-only source fetch; not for submit
npx -y magicpath-ai code submit --dir <workdir> --width <px> --height <px> --wait -o json         # submit edits/size + wait for build
npx -y magicpath-ai code status <jobId> -o json                                                  # poll a build job

Key Concepts

• Each component has a generatedName (e.g., wispy-river-5234) — this is the identifier for all operations
• Components are added as source code to src/components/magicpath/<name>/
• The add command returns importStatement and usage — use these in code
• Use inspect to inspect source code without installing — don't use add just to read code
• MagicPath components are React/TypeScript source code — use add in JS/TS projects, use inspect + translate for other languages
• Themes (design systems) contain CSS variables (light/dark maps), optional fonts, and an optional prompt with styling instructions for agents. "Theme" and "design system" are interchangeable. Use list-themes to browse, get-theme to fetch the full definition
• The code subcommands are for canvas-component source workflows, not app installation. Use code start + code submit to publish edits back to the MagicPath canvas; code context is read-only inspection. They are unrelated to add/inspect, which install reusable component source into an app.

Current Project Context

!`npx -y magicpath-ai info -o json 2>/dev/null || echo '{"error": "Could not run magicpath-ai via npx. Ensure Node.js is installed and the registry is reachable."}'`

The JSON above contains auth status, projects, and CLI version. If auth.authenticated is false, the user needs to log in before any other operations.

References

• CLI Reference
• Working with repositories — bring an existing local or online Git repository's UI onto the MagicPath canvas (e.g. "render this project in MagicPath", "bring the sidebar of my app into MagicPath")
• Working with embedded browsers — use a MagicPath project as the persistent canvas inside Codex, Cursor, or another host with an in-app browser

MagicPath CLI Reference

IMPORTANT: Always pass -y to skip interactive prompts when running from an agent context. Use -o json for structured output.

Commands

info — Project and auth context

magicpath-ai info              # human-readable
magicpath-ai info -o json      # structured JSON

Returns auth status, user info, teams, projects (personal + team), and CLI version. The teams array shows which teams the user belongs to and their role. Use list-members for full member details of a specific team.

login — Authenticate

magicpath-ai login                       # one-click browser login (auto-completes)
magicpath-ai login --code <code>         # exchange auth code directly (headless fallback)
magicpath-ai login --guest-code <code>   # connect to a guest project (no account)

Opens the browser and completes login automatically when the user authorizes.

whoami — Check authentication

magicpath-ai whoami
magicpath-ai whoami -o json

list-teams — List teams

magicpath-ai list-teams
magicpath-ai list-teams -o json

Lists all teams the user belongs to, with their role in each.

JSON output: { teams: [{ id, name, role }] }

list-members — List members of a team

magicpath-ai list-members --team "Acme Inc"
magicpath-ai list-members --team "Acme Inc" -o json
magicpath-ai list-members --team <teamId> -o json

Lists all members of the specified team. The --team flag is required and accepts a name (case-insensitive) or ID.

JSON output: { team: { id, name }, members: [{ id, displayName, email, role }] }

Use list-members to resolve a person's name to their user ID, then use --created-by <userId> on list-components to find their work.

skills list — List skills

magicpath-ai skills list
magicpath-ai skills list -o json
magicpath-ai skills list --owned-only -o json
magicpath-ai skills list --team "Acme Inc" -o json

Lists skills available in the user's personal workspace, or in a team when --team is passed. Public MagicPath skills are included by default because they are invocable in chat; pass --owned-only to hide public skills and show only editable user/team skills.

JSON output: { skills, workspace }. Each skill includes id, name, slug, description, instructions, sourceFormat (EDITOR or ARCHIVE), enabled, isPublic, and owner fields.

skills get — Retrieve a skill

magicpath-ai skills get <skillIdOrSlug> -o json
magicpath-ai skills get <skillIdOrSlug> --files -o json
magicpath-ai skills get <skillIdOrSlug> --file reference/examples.md
magicpath-ai skills get <skillIdOrSlug> --team "Acme Inc" -o json

Shows a skill by ID, slash-command slug, or exact name. Use --files to list bundled files on imported package skills. Use --file <path> to print one bundled file's content.

JSON output without file flags: { skill }. With --files: { skill, files }. With --file: { skill, file }.

skills create — Create an editable skill

magicpath-ai skills create --name "Skill name" --description "Use when ..." --instructions "Do this..." -o json
magicpath-ai skills create --name "Skill name" --description "Use when ..." --instructions-file ./SKILL.md -o json
magicpath-ai skills create --name "Team skill" --description "Use when ..." --instructions-file ./SKILL.md --team "Acme Inc" -o json

Creates an editable personal or team skill. For anything longer than a short instruction, prefer --instructions-file so Markdown formatting is preserved.

JSON output: { skill, workspace }.

skills import — Import a skill package

magicpath-ai skills import ./my-skill.skill -o json
magicpath-ai skills import ./my-skill.zip --team "Acme Inc" -o json

Imports a .zip or .skill package into the user's personal workspace or a team. Package skills are content-immutable after import, but can still be enabled or disabled.

JSON output: { skill, workspace }.

skills update — Update or enable/disable a skill

magicpath-ai skills update <skillIdOrSlug> --description "New description" -o json
magicpath-ai skills update <skillIdOrSlug> --instructions-file ./SKILL.md -o json
magicpath-ai skills update <skillIdOrSlug> --disable -o json
magicpath-ai skills update <skillIdOrSlug> --enable --team "Acme Inc" -o json

Updates an editable skill by ID, slug, or exact name. ARCHIVE package skills cannot have name, description, or instructions edited; use this command only to enable/disable them. Public MagicPath skills are read-only.

JSON output: { skill, workspace }.

skills delete — Delete an owned skill

magicpath-ai skills delete <skillIdOrSlug>
magicpath-ai skills delete <skillIdOrSlug> -y -o json
magicpath-ai skills delete <skillIdOrSlug> --team "Acme Inc" -y -o json

Deletes an editable personal or team skill. Always pass -y in non-interactive agent contexts. Public MagicPath skills cannot be deleted through this command.

JSON output: { skill, workspace }.

Installing MagicPath skills into a local agent

To install a MagicPath-hosted skill locally, reconstruct the Agent Skills folder from CLI output:

1. Run magicpath-ai skills get <skillIdOrSlug> -o json. 2. Create a local folder named with the returned skill.slug. 3. Write SKILL.md using the returned skill.name, skill.description, and skill.instructions. 4. If the skill has bundled files, run magicpath-ai skills get <skillIdOrSlug> --files -o json, then fetch each path with magicpath-ai skills get <skillIdOrSlug> --file <path> and write it under the local skill folder. 5. Register that local folder with the current agent host using the host's supported local skill install flow.

Ask before writing into global agent configuration directories.

search — Search components across all projects

magicpath-ai search "input"
magicpath-ai search "button" -o json
magicpath-ai search "card" --limit 5
magicpath-ai search "header" --team "Acme Inc" -o json
magicpath-ai search "nav" --personal -o json

Searches component names (case-insensitive substring match) across all accessible projects (personal + team). Returns matches with project and workspace context. Each result includes previewImageUrl — use list-components or search results to get preview images when visual context is needed.

JSON output includes ownerType ("personal" or "team") and ownerName on each result.

list-projects — List all projects

magicpath-ai list-projects
magicpath-ai list-projects -o json
magicpath-ai list-projects -o json --limit 10
magicpath-ai list-projects --team "Acme Inc" -o json
magicpath-ai list-projects --personal -o json

By default, lists all accessible projects (personal + all teams). Use --team or --personal to filter.

JSON output: { projects, pagination: { total, limit, offset, hasMore } }. Each project includes:

• ownerType ("personal" or "team") and ownerName (user email or team name)
• createdBy (object or null) — { id, displayName } of the user who created this project

create-project — Create a new project

magicpath-ai create-project --name "My Stuff" -o json
magicpath-ai create-project --name "My Stuff" --team "Acme Inc" -o json
magicpath-ai create-project --team "Acme Inc" -o json   # auto-generated name

Creates a project in the user's personal workspace, or in a team if --team is passed. With --team, the user must be a member of that team.

JSON output: { project } — the same project shape returned by list-projects (includes id, name, ownerType, ownerName, visibility, etc.). Use project.id as the --project argument for code start to add the first component.

Visibility is set automatically: personal projects default to PRIVATE, team projects default to SHARED.

list-components — List components in a project

magicpath-ai list-components <projectId>
magicpath-ai list-components <projectId> -o json
magicpath-ai list-components <projectId> -o json --limit 20
magicpath-ai list-components <projectId> -o json --after <lastId>
magicpath-ai list-components <projectId> --created-by <userId> -o json
magicpath-ai list-components <projectId> --created-by <userId> --sort-by createdAt --order desc -o json

Uses cursor-based pagination. To get the next page, pass pagination.lastId as --after.

JSON output: { components, pagination: { limit, hasNext, lastId } }. Each component includes:

• previewImageUrl (string or null) — a screenshot of the component's latest revision
• lastEditedBy (object or null) — { id, displayName } of the user who last edited this component

list-themes — List all themes (design systems)

magicpath-ai list-themes
magicpath-ai list-themes -o json
magicpath-ai list-themes --team "Acme Inc" -o json

Lists design systems (themes) for the current user, or for a specific team with --team.

JSON output: { themes: [{ id, name, isPublic, createdAt, updatedAt }] }

get-theme — Get a theme definition

magicpath-ai get-theme <themeId>
magicpath-ai get-theme <themeId> -o json
magicpath-ai get-theme "My Brand Theme" -o json    # lookup by name
magicpath-ai get-theme "Brand" --team "Acme Inc" -o json  # lookup in team

Fetches the full theme definition including CSS variables, fonts, and styling prompt. Accepts a numeric ID or a theme name (case-insensitive match). Use --team to look up themes within a specific team.

JSON output: { id, name, theme: { light: { "--var": "value", ... }, dark: { ... } }, defaultTheme, prompt?, fonts?, version }

Key fields for agents:

• theme.light / theme.dark — CSS variable maps to apply to components
• prompt — Natural language styling instructions from the designer (e.g., "use rounded corners, prefer shadows over borders")
• fonts — Font metadata with source (google or custom) and weight URLs
• defaultTheme — Whether the theme defaults to "light" or "dark"

view — Open a component or project

magicpath-ai view <generatedName>              # component preview
magicpath-ai view-component <generatedName>    # alias
magicpath-ai view <projectId>                  # open the project

Opens the target in the default browser. In JSON mode, returns the URL without opening. The argument is a component generatedName (e.g. wispy-river-5234) or a project id (numeric) — a numeric id opens the project, anything else opens the component preview.

share — Get a shareable URL

magicpath-ai share <generatedName>
magicpath-ai share <generatedName> -o json     # { type: "component", url, generatedName }
magicpath-ai share <projectId> -o json         # { type: "project", url, projectId }

Prints the URL to stdout (one line). Doesn't open a browser — use view if you want that. Accepts the same identifiers as view: a component generatedName (from search, list-components, selection, or the code flow) or a project id (from list-projects, create-project, or active-project).

inspect — View component source code

magicpath-ai inspect <generatedName>              # human-readable with file contents
magicpath-ai inspect <generatedName> -o json      # structured JSON with source code

Shows the component's source code, dependencies, and import info without installing anything. This is read-only — no files are written, no package.json is required.

inspect works in any project type. For non-React projects (Swift, Python, etc.), use inspect to read MagicPath component source code as a reference for recreating the component in your target language.

JSON output includes { component, generatedName, files: [{ path, name, content }], dependencies, importStatement?, usage? }.

add — Add a component to your project

IMPORTANT: Only use add in React/TypeScript projects where you intend to import the component afterward. For non-JS projects, use magicpath-ai inspect to read source code and translate it. After adding, always import and use the component — never add and then manually replicate its styles.

magicpath-ai add <generatedName>
magicpath-ai add <generatedName> -y              # skip prompts
magicpath-ai add <generatedName> --dry-run       # preview file list only
magicpath-ai add <generatedName> -y --overwrite  # replace existing

JSON output (-o json) automatically implies -y (no prompts).

list-installed — List installed MagicPath components

magicpath-ai list-installed
magicpath-ai list-installed -o json
magicpath-ai list-installed --path src/components/custom

Lists MagicPath components already installed in the current project by scanning the components directory. Useful for checking what's already been added before installing new components.

JSON output: { components: [{ name, folder, path, files, exportName, importStatement }], total, componentsPath }

selection — Get current canvas selection

magicpath-ai selection
magicpath-ai selection -o json

Returns the component(s) and image(s) currently selected in the MagicPath web app canvas, along with the project(s) the user has open. Returns empty components/images if the user has nothing of that type selected, and empty projects if no canvas is open.

JSON output: { projects: [{ id, name, ownerType, ownerName }], components: [{ id, name, generatedName, clientId, projectId, projectName }], images: [{ id, shapeId, name, projectId, projectName, width, height }] }

Notes:

• projects is the same shape returned by active-project — calling selection gives you both signals in one round-trip.
• components may be empty while images or projects are non-empty. Use that to decide whether to start a code session with selected image context, or fall back to listing/searching components.
• If only the open project is needed (not the selection), prefer active-project — it is faster than selection.

active-project — Get the project(s) the user currently has open

magicpath-ai active-project
magicpath-ai active-project -o json

Returns the project(s) the user currently has open in the MagicPath web app. Use this when you need the user's working project but no specific component has been selected. Returns an empty list if the user has no active canvas session.

JSON output: { projects: [{ id, name, ownerType, ownerName }] }

Notes:

• Multiple projects can be returned if the user has multiple tabs open.
• active-project is the lighter of the two commands — it returns only the open project(s), while selection returns those plus any selected components and is more expensive. Prefer selection when the user references a component; use active-project when they only need the project.
• If a project is open but cannot be resolved against the user's accessible projects, the entry is returned with name, ownerType, and ownerName set to null and only the id populated.

code — Create/edit canvas components from local code

The code subcommands let an external agent author or edit a MagicPath canvas component's source files locally, then submit them back to the platform. This is unrelated to add/inspect, which install reusable component source into an application.

code start is the stateful entrypoint for both create and edit. With --project, it creates a pending component revision and writes a scaffolded Component Forge app. With --component, it creates or reuses a pending edit revision and writes editable source files. code context is read-only and does not create a revision, canvas presence, or submit manifest. code submit uploads changed files and waits for the build when --wait is passed.

All stateful code sessions operate against a working directory and persist state in <dir>/magicpath-code.json (written by start, create, and successful submit; read by submit).

Editable file boundary

The code API only accepts full-file replacements for:

• src/App.tsx
• src/index.css
• src/components/generated/**
• assets/** for temporary image assets only

Image files in <dir>/assets/ are staging inputs. The backend uploads them to stable public asset URLs, rewrites TSX/CSS references, and removes the staging folder before build. Reference assets from component code or CSS with paths such as ../../../assets/hero.png, /assets/hero.png, or url("../../assets/hero.png"). Do not inline data:image/...;base64,... in source files.

When image shapes are selected on the canvas before code start, JSON output may include selectedImages. Each selected image has a short-lived accessUrl plus a local assetPath; the CLI downloads the URL into that assets/selected/** path. Use the local assetPath in source, not the expiring accessUrl.

It does not accept dependency installation, package.json edits, src/main.tsx, Vite config changes, lockfile edits, raw patches, or arbitrary repo files.

Tailwind v4 requirements

• Keep @import 'tailwindcss'; in src/index.css.
• Do not use @tailwind base;, @tailwind components;, or @tailwind utilities;.
• Do not remove @theme inline { ... }, :root, or .dark token blocks.
• Append custom utilities or theme additions to src/index.css; do not replace the whole file.
• There is no tailwind.config.js; configuration lives in src/index.css.

code start — Start a pending create or edit session before writing code

npx -y magicpath-ai code start --project <projectId> --dir ./mp-new --name "Hero Card" --width 960 --height 640 -o json
npx -y magicpath-ai code start --component <componentId> --dir ./mp-work -o json

For creates, creates a component and pending revision on the canvas immediately, enables external-agent canvas presence (Liveblocks cursor), and scaffolds the starting file structure into <dir>:

• magicpath-code.json — manifest with component/revision IDs
• src/App.tsx — pre-wired slim entry file that imports and renders the top-level component from src/components/generated/<ComponentName>
• src/index.css — Component Forge Tailwind v4 setup with @import 'tailwindcss';, @theme inline, token definitions, base layer, and fallback image styles
• src/components/generated/<ComponentName>.tsx — stub named-export component ready to fill in

The component filename is derived from --name (PascalCase, e.g. "Hero Card" → HeroCard). JSON output includes scaffoldedPaths listing the files that were written.

For edits, creates or reuses one pending edit revision for the component, enables external-agent canvas presence, writes the editable source files into <dir>, and writes magicpath-code.json. Run this before generating files for a new or existing canvas component.

If selected canvas images were available, code start also writes them into <dir>/assets/selected/ and includes selectedImages in the JSON result and manifest. Those files are normal temporary assets and will be uploaded/referenced durably on code submit.

code context — Fetch existing component source read-only

npx -y magicpath-ai code context <componentId> --dir ./mp-work -o json

Writes src/App.tsx, src/index.css, and src/components/generated/** into <dir> for inspection only. It does not create a pending revision, does not show canvas presence, and does not write magicpath-code.json. Use code start --component <componentId> before submitting edits.

code submit — Submit local edits

npx -y magicpath-ai code submit --dir ./mp-work --width 960 --height 640 --wait -o json

Reads magicpath-code.json, computes both the set of changed editable files and any files that were removed from <dir> since the last start/successful submit, and submits them together (changes as full-file replacements, removals as deletedPaths). Prints the resulting job/revision. Use --wait when the agent should fix build failures in the same turn.

To delete a file, just remove it from <dir> before running submit — the deletion is inferred from the manifest baseline. Deletion propagation is active only in edit mode; in create mode, simply don't write the file. The JSON output includes deletedPaths: [...] listing what was removed.

If no editable files have changed, nothing has been deleted, and no dimensions were provided, returns { status: "unchanged", componentId, revisionId } without submitting.

code create — Create a new component from already-written files (convenience)

npx -y magicpath-ai code create --project <projectId> --dir ./mp-new --name "Hero Card" --wait -o json

Convenience wrapper: internally runs code start and then uploads the files from <dir>. Prefer explicit `code start` followed by `code submit` — the split gives better canvas feedback (the pending component is visible while the agent is still writing code). <dir> must include src/App.tsx.

code status — Poll an external-agent build job

npx -y magicpath-ai code status <jobId> -o json

Returns pending, processing, completed, failed, or cancelled. Failed jobs include sanitized build diagnostics when available.

image — List and add images on a project canvas

Standalone images that live directly on a project's canvas (alongside components). This is distinct from the assets/ files in the code flow, which are build inputs for a single component — image operates on the project canvas itself.

image list — List the images on a project canvas

npx -y magicpath-ai image list <projectId> -o json

JSON output: { images: [{ id, name, url, position: { x, y, z, width, height }, createdAt, updatedAt }] }. The url is a public image URL — download it to visually inspect what an image looks like (the same way previewImageUrl is used for components). Use this to "see" the images already present in a project.

image add — Add an image to a project canvas

npx -y magicpath-ai image add <projectId> ./hero.png -o json
npx -y magicpath-ai image add <projectId> https://example.com/hero.png --name "Hero" -o json

Uploads a local image file or a remote URL to the project and places it on the canvas, where it appears automatically. Requires editor access to the project.

Width and height default to the image's real pixel dimensions so it isn't stretched; pass --width/--height only to override. JSON output: { image: { id, name, url, position } }.

Working With Embedded Browsers - Keep a MagicPath Project Open as a Canvas

Use this reference when MagicPath runs through an external agent host that exposes an embedded browser, browser pane, or webview, such as Codex or Cursor when that capability is available.

Purpose

A MagicPath project can become a persistent visual canvas beside the agent: the agent reasons across the user's local repository, assets, notes, skills, and tools while the user sees and selects work on the MagicPath canvas in the same workspace.

This guidance applies to projects/files, not individual design previews. Keep the browser focused on the project canvas. Only open an individual component or design in the embedded browser when the user explicitly asks to see that specific design.

Do not assume a named host always has an internal browser capability. Check the capabilities available in the current session and use this workflow only when the host can actually show or navigate that surface.

When to use the embedded project canvas

Open or keep a MagicPath project in the host's embedded browser when:

• The user asks to create a new MagicPath project/file and will work on it visually.
• The user asks to build, edit, iterate on, or select designs in a named or currently open project.
• A new project has just been created and the requested next step is canvas authoring.
• The user asks to open a project in MagicPath inside Codex, Cursor, or the current agent.
• You need the user to make a selection on the canvas for a follow-up edit.

This should feel like one workflow: the agent works with local code and context while MagicPath remains visible as the visual canvas beside it.

When a request creates a new project and asks for any design work inside it, opening the project canvas is not an optional final preview step. Open it immediately after project creation and before starting the design work.

Do not navigate to individual designs by default

• Creating, submitting, or editing a component does not require leaving the project canvas. The new or edited design appears in that project.
• Do not open each design or component in its own preview page after code submit.
• Do not replace the project canvas with a single-design preview merely to show progress.
• If the user explicitly asks to open a particular design or see it on its own, open it as requested.
• If the user asks for a single-design link, return the link without navigating away from the project canvas unless they also ask to open it.

Resolve a project URL without opening an external browser

view <projectId> opens a project in the operating-system browser. In an agent host with an embedded browser, obtain the project URL without opening another window:

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

The response includes the project URL:

{ "type": "project", "url": "https://www.magicpath.ai/files/<projectId>", "projectId": "<projectId>" }

Navigate the host's embedded browser to the returned url. Prefer the URL returned by share; do not guess URL shapes or open a blank home page when the project is already known.

When no embedded browser is available, it cannot be controlled reliably, or the user explicitly wants their normal browser, use:

npx -y magicpath-ai view <projectId>

Browser sign-in is separate from CLI sign-in

The CLI can be authenticated while the embedded browser is not. whoami, create-project, or code submit succeeding does not prove that the browser pane has a MagicPath login session.

The project URL returned by share <projectId> -o json is the intended canvas URL. If opening /files/<projectId> in the embedded browser redirects to the MagicPath home or sign-in flow:

1. Do not switch to a single-design preview as a workaround. 2. Tell the user that the embedded browser needs its own MagicPath sign-in. 3. Let the user sign in within that browser pane. 4. Navigate back to the same returned project URL after sign-in and continue work on the canvas.

Project-canvas workflows

Work in the active project

1. If the user refers to the project they have open, run npx -y magicpath-ai active-project -o json. 2. If it resolves to one project and it is not already visible in the embedded browser, run share <project.id> -o json and open that returned project URL there. 3. Keep that project visible while using selection, code start, and code submit for the user's requested work. 4. If multiple projects are active or none is active, resolve the intended project before navigating.

Create a new project and begin visual work

1. Create the project with npx -y magicpath-ai create-project --name "<name>" -o json. 2. Read the returned project.id. 3. Before authoring a design, in an embedded-browser host run npx -y magicpath-ai share <project.id> -o json and open that project URL in the internal browser. 4. If the project URL redirects because the embedded browser is not signed in, complete the browser sign-in flow and reopen that same project URL. 5. If no embedded browser is available, run npx -y magicpath-ai view <project.id> only when user-facing project navigation is needed. 6. Continue the requested canvas workflow with code start --project <project.id> ..., keeping the project canvas visible for review and selection. 7. After code submit, verify progress on the open project canvas; do not navigate to a single-design preview unless the user expressly asks for it.

The user asks for one design

1. If the user asks for a link to an individual design, resolve it with npx -y magicpath-ai share <generatedName> -o json and return its url. 2. Navigate the embedded browser to that individual design only if the user explicitly asks to open or see that design on its own. 3. Keep the project canvas available for continued creation and editing.

Keep browser navigation quiet when

• Running info, whoami, list-projects, list-components, list-teams, list-members, search, list-themes, or get-theme only to make an internal decision.
• Using inspect, add, or other app-integration commands where the requested result is repository code rather than visible canvas work.
• Running automated checks or polling a code submit job before the project contains a viewable result.
• The project canvas is already visible and the next command does not require navigation.

Host-specific handling

• Codex: If its Browser capability is available, show the MagicPath project there when the user will work with or review the canvas. This enables the native-canvas workflow: Codex and local context on one side, MagicPath on the other.
• Cursor or another agent host: Use its internal browser capability only when it is exposed in the current session. Do not invent commands or assume browser access.
• No embedded browser: Continue with the CLI and use view <projectId> for intentional project navigation.

Boundaries

• Use the main https://www.magicpath.ai product surface returned by the CLI.
• Do not replace or reroute magicpath-ai login; authentication owns its browser flow.
• Do not confuse CLI authentication with the login session in the embedded browser pane.
• Keep one project canvas open rather than navigating to separate single-design previews as work is generated.
• Do not repeatedly refresh or navigate away from the user's active project while generation or selection work is in progress.
• Use selection and active-project to connect what the user is looking at in MagicPath back to the agent's next action.

Working With Repositories — Bring an Existing Codebase Into MagicPath

IMPORTANT: This flow is the inverse of add/inspect. With add/inspect the source of truth is the MagicPath registry and the destination is the user's app. Here the source of truth is the user's repository and the destination is the MagicPath canvas. You recreate the repo's UI as a canvas component using the code start → code submit authoring flow. Do not use add, inspect, or code context for this — they are for other workflows (see the boundaries section below).

This reference tells an external agent (MagicPath's own agent, Claude Code, Codex, Cursor, etc.) exactly what to do when the user wants to take UI that already exists in a Git repository — local or online — and reproduce it faithfully as a React component on their MagicPath canvas.

When this applies (triggers)

Reach for this reference when the user points at existing code and asks to get it onto the canvas. Examples:

• "Bring the sidebar of my app into MagicPath."
• "Render this project in MagicPath." / "Import my repo." / "Recreate my landing page in MagicPath."
• "Design from my existing dashboard." / "Pull my <Header /> into a MagicPath design."
• Any message that pairs a local path (e.g. ~/code/acme-web) or an online repo URL (GitHub/GitLab/Bitbucket) with MagicPath intent.

If the user is instead asking to install a MagicPath registry component into their app, that is the add/inspect flow — not this one.

The mental model

A MagicPath canvas component is a single, self-contained, interactive React + Tailwind v4 mini-app (see the skill's Design Defaults). Your job is to read the relevant slice of the repo, understand both its visual output and its behavior, and reproduce that as faithfully as possible inside the canvas authoring template — translating whatever framework and styling system the repo uses into the canvas's React + Tailwind v4 conventions.

Fidelity is the goal: the canvas result should look like the same product, not a reinterpretation of it.

---

Phase 0 — Get the code

Local repository. Confirm the path with the user if it isn't explicit. Read files directly. If the path is read-only (e.g. an uploads mount), copy the slice you need into your working directory before doing anything stateful. Do not assume the repo root — ask or detect it (look for package.json, .git/, a framework config).

Online repository. Clone it shallowly into a scratch directory, then read from there:

git clone --depth 1 <repo-url> ./_repo
# specific branch:
git clone --depth 1 --branch <branch> <repo-url> ./_repo

• If the user gave a URL to a specific file or folder (e.g. a GitHub /blob/ or /tree/ link), you only need that slice plus its imports — fetch the raw file(s) rather than cloning the whole repo when that's cheaper.
• Private repos need the user's credentials. If a clone fails on auth, stop and ask the user to either make it accessible, provide a token, or point you at a local checkout. Never guess or hardcode credentials.
• Monorepos: identify which package/app the user means (apps/*, packages/*). Don't recreate the whole monorepo — scope to the target.

Keep the cloned repo and your MagicPath working directory (--dir) separate. The repo is read-only input; the canvas working directory is where you author the recreation.

Phase 1 — Map the project (read the design foundation first)

Before touching the target component, understand the project's styling system. Read the global design layer first — this is what makes the recreation faithful instead of approximate.

1. Detect the stack. Read package.json dependencies. Note the framework (React, Next.js, Vite, Vue, Svelte, SvelteKit, Angular, Astro, plain HTML, SwiftUI, etc.) and the styling approach (Tailwind, CSS Modules, styled-components, Emotion, vanilla-extract, Sass/SCSS, plain CSS, CSS-in-JS). 2. Read the global CSS. Find and read the global stylesheet(s): global.css, globals.css, index.css, app.css, styles/*.css, or the equivalent. This is where resets, base typography, and CSS custom properties live. 3. Read the design tokens. Capture the actual values, not just names:

• tailwind.config.{js,ts} theme/extend (colors, spacing, radii, shadows, fonts, breakpoints).
• CSS variables / :root blocks and any .dark overrides.
• Dedicated token files (tokens.*, theme.*, design-system exports).

4. Read the fonts. Note how fonts load — next/font, @font-face, a Google Fonts <link>, or a font package — and which families map to body vs. headings. 5. Note the theming strategy. Light/dark handling, ThemeProvider, class="dark" toggling, prefers-color-scheme. 6. Find shared UI primitives. Look for a components/ui, design-system, or primitives folder. The target component almost certainly composes these (Button, Card, Icon, etc.), and you'll need them to reproduce it.

If the user has a MagicPath theme that corresponds to this brand, prefer reconciling against it: run list-themes / get-theme and use the theme's CSS variables, fonts, and prompt as the styling target. Otherwise, derive the tokens straight from the repo as above.

Phase 2 — Resolve the target

Pin down exactly what the user asked for and read everything it depends on.

A single element ("the sidebar", "my <Header />"):

1. Locate the component file (search by name/route). 2. Trace all of its dependencies: imported child components, CSS/CSS-module files, icon imports (lucide, heroicons, custom SVGs), and any constants/data it renders. 3. Read the layout context it sits in — the parent that gives it width, position, and spacing. A sidebar pulled out of its flex/grid parent will look wrong unless you reproduce the relevant container behavior inside the canvas frame. 4. Resolve styling to concrete values: what do the Tailwind classes / CSS variables actually evaluate to (colors, px, rem)? Faithful recreation means matching the rendered result, not copying class strings blindly.

A whole project / page ("render this project"):

1. Identify the route/page entry the user means (a specific page, or the app's primary screen). If "this project" is ambiguous, ask which page or screen — and stop and wait. 2. Walk the component tree from that entry to understand structure and scope. 3. Decide scope against Design Default rule 5 (never stack multiple screens in one frame):

• One cohesive screen/flow → one interactive canvas component with internal state.
• Several genuinely independent screens → separate canvas components, one per screen, each with its own --dir.

Confirm the split with the user before building many frames.

Phase 3 — Plan the recreation

1. Choose the frame(s) and canvas dimensions from the source's intended viewport — e.g. --width 1440 --height 900 for a desktop app, --width 390 --height 844 for a mobile screen. The content stays fluid; the dimensions just signal the target form factor. 2. Map the styling system → Tailwind v4 (the canvas requirement):

• CSS variables → keep as variables in src/index.css (inside the existing :root/.dark/@theme inline blocks) and reference them, e.g. bg-[var(--background)].
• styled-components / Emotion / CSS-in-JS → equivalent Tailwind utilities.
• CSS Modules / SCSS → flatten to Tailwind utilities, or append plain CSS to src/index.css.
• Tailwind v3 config in the source → translate its tokens into v4's @theme directive in src/index.css. There is no `tailwind.config.js` on the canvas.

3. Plan fonts: add the required Google Fonts @import/<link> equivalents or @font-face declarations to src/index.css and wire the families to the right elements. 4. Plan assets: real images go into the working directory's assets/ folder and get referenced from code/CSS. Do not hotlink repo blob URLs and do not inline data:image/...;base64,.... 5. Non-React sources (Vue, Svelte, Angular, plain HTML, SwiftUI, etc.): translate the markup semantics, visual output, and behavior into React + Tailwind. Reproduce what it looks like and does — not the original framework's directives/constructs.

Phase 4 — Build it on the canvas

Use the create path of the code flow. (Full command details live in cli-reference.md.)

1. Resolve a project. You need a projectId. Use active-project -o json if the user has one open, otherwise ask or create-project. (See the skill's Creating a project section.) 2. Start the session before writing files so the user sees agent presence on the canvas:

   npx -y magicpath-ai code start --project <projectId> --dir ./mp-build --name "Sidebar" --width <px> --height <px> -o json

3. Fill in the scaffold faithfully. Implement the recreation in src/components/generated/<Name>.tsx, splitting sub-components (nav item, avatar, etc.) into sibling files under src/components/generated/. Edit src/index.css for tokens/fonts/custom CSS. Do not rewrite `src/App.tsx` — it's pre-wired; only touch it to change the theme value. Only these surfaces are editable: src/App.tsx, src/index.css, src/components/generated/**, and assets/**. 4. Honor the Design Defaults while reproducing the look:

• No device mockups — never wrap the recreation in a phone/browser/laptop frame even if the source app has one. The canvas is the frame.
• Responsive — replace hardcoded outer widths/heights with fluid sizing; the appearance should stay identical at the target width.
• Centered in the frame.
• Single screen — multi-view flows use internal React state, not stacked frames.
• Fully interactive — reproduce real behavior with real state: a collapsible sidebar collapses, the active nav item is driven by state, hovers/focus/active/disabled states are styled, dropdowns and toggles work. A static screenshot of an interactive surface is not done.

5. Match the visual details precisely: colors, spacing, border radii, shadows, typography (family/size/weight/line-height/letter-spacing), and transitions. Pull the concrete values you resolved in Phase 1–2. 6. Mock the data realistically. The canvas component has no backend — replace server/data-fetching with representative local mock data and local state so the component is self-contained and looks populated, not empty. 7. Submit and fix:

   npx -y magicpath-ai code submit --dir ./mp-build --width <px> --height <px> --wait -o json

If the job fails, read the returned diagnostics, fix only the allowed files, and re-submit. Don't start a new component to work around a build failure.

Phase 5 — Verify fidelity

• Open the result (view <generatedName>) and compare it against the source app side by side.
• Check that tokens resolved (no stray defaults), fonts loaded, dark mode matches if relevant, and interactions behave like the original.
• Confirm it stays centered and intact at the target width and degrades sensibly when the frame is resized.

---

Fidelity principles

The golden rule: read the global CSS and the full component (with its dependencies) first, reproduce the visual output and behavior exactly, and express it through the canvas's React + Tailwind v4 conventions and Design Defaults.

Boundaries — what NOT to do

• Don't use `add`. That installs registry components into an app; it's the opposite direction.
• Don't use `inspect` or `code context`. Those read MagicPath-side source. Here you're reading the user's repo and creating a new canvas component via code start → code submit.
• Don't edit forbidden files in the working directory: no package.json, vite.config.*, src/main.tsx, lockfiles, or arbitrary repo files — only src/App.tsx, src/index.css, src/components/generated/**, and assets/**.
• Don't dump the whole repo onto the canvas. Scope to what the user asked for; confirm the screen split before creating multiple frames.
• Don't invent credentials for private repos — ask.
• Don't pixel-lock or add device chrome even when the source does.

Quick recipes

"Bring the sidebar of my app into MagicPath" 1. Get the code (Phase 0). 2. Read global CSS + tokens + fonts (Phase 1). 3. Open the Sidebar component, follow its imports (child items, icons, styles) and read its layout parent for width/position (Phase 2). 4. code start --project <id> --dir ./mp-build --name "Sidebar" --width <px> --height <px>. 5. Recreate it faithfully in src/components/generated/Sidebar.tsx — real collapse/active-item state, matched colors/spacing/typography, fluid + centered, no device frame. 6. code submit --wait. 7. Verify against the app.

"Render this project / this page in MagicPath" 1. Get the code (Phase 0). 2. Read the design foundation (Phase 1). 3. Identify the page entry; if ambiguous, ask which screen and stop. Walk the tree and decide one interactive frame vs. multiple frames (Phase 2 / Design Default rule 5). 4. For each frame: code start with viewport-appropriate dimensions, recreate faithfully with internal navigation state for multi-view flows, mock data realistically. 5. code submit --wait each. 6. Verify each against the source.