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.
• 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, tell the user to sign up from the canvas open in their browser — that's what saves this project to their account and unlocks everything else. (If their session has already expired, the project can't be saved and they'd start fresh.) 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