Documentation in full

01What is Pcreative Studio

Pcreative Studio is a PyQt6 desktop app that automates the boring parts of starting a web template project to sell on marketplaces (ThemeForest, CodeCanyon, Gumroad…), driven end-to-end by AI coding agents.

• Scaffolds 84 modern stacks with each one's official CLI and up-to-date defaults.
• Drops a CLAUDE.md/AGENTS.md context file so any agent understands the goal from message one.
• Opens a per-project window with embedded preview, terminal, logs and the agent ready to chat.
• Packages, validates and deploys for the marketplace without leaving the app.

Pcreative Studio does NOT generate your template code — the agent does. It prepares the ground so the agent starts with maximum context and minimum boilerplate.

02Requirements

• Linux (Arch / CachyOS / Manjaro / EndeavourOS recommended; tested on KDE Plasma 6 Wayland; works on other DEs).
• Python 3.11+ and PyQt6 6.6+ (includes QtWebEngine for the embedded browser).
• Node.js 20+ and npm (embedded terminal, AI CLIs and most scaffolds).
• Git 2.40+.
• Optional: Docker (WordPress/e-commerce stacks), Composer + PHP 8.3+ (Laravel/WP), GitHub CLI (GitHub button).

For the agents you need at least one: claude · codex · gemini · opencode. They run as external processes; Pcreative Studio does not bundle them.

03Installation

Distributed as a Python project you clone and run with launch.sh.

# Arch / CachyOS
sudo pacman -S --needed python python-pyqt6 python-pyqt6-webengine

# Debian / Ubuntu
sudo apt install python3 python3-pyqt6 python3-pyqt6.qtwebengine

git clone https://github.com/pcreativedev/pcreative-studio.git
cd pcreative-studio
cd terminal && npm install && cd ..   # servidor de terminal embebida (Node)
./launch.sh

Alternative: copy or symlink a .desktop into ~/.local/share/applications/ pointing at your launch.sh for a menu entry.

04Your first project

• Launch Pcreative Studio and fill the form: Name, Stack (e.g. Next.js + Tailwind), Type and AI provider.
• Leave the mode on "From scratch" and click "Create project & launch agent".
• The official scaffold runs, context MDs are copied and CLAUDE.md is generated with metadata, market analysis and requirements.
• The project window opens with preview, terminal and the agent loaded.

Tip: tell the agent "Read CLAUDE.md and tell me what you understand before changing anything" to confirm context. When ready, hit ▶ Start preview to launch the dev server in the embedded browser.

05Project creation modes

From scratch

Pure greenfield: runs the stack scaffolder and gives you a clean project. Best for new ideas with no reference.

Recreate reference

Point at a folder, ZIP or URL. It's dropped in reference/ (gitignored) and CLAUDE.md includes strict anti-copy rules: the agent reimplements every line from scratch with your branding.

Adopt local

You have a template in a folder and want to work in-place. It copies the contents into the project and adds context on top, without altering your code. Auto-detects mono-repos.

Existing repo

Point at a GitHub repo (owner/name): it clones, detects the stack, adds context and opens the project window.

06Supported stacks (84)

The full list lives in stacks.py. Each stack has its official scaffold command, its skills, a preview profile (command + port) and stack-specific notes.

• Frontend: Next.js (Tailwind/shadcn/Mantine/HeroUI), Astro, Remix, Nuxt, SvelteKit, Qwik, SolidStart, React-Vite, Vue 3, Angular, HTML+Tailwind/Bootstrap.
• WordPress (×6): block, bricks, elementor, divi, breakdance, plugin — with WP+MariaDB auto-provisioned in Docker, autologin, free pack and the WordPress MCP.
• Shopify (×7): liquid (Dawn), hydrogen, polaris-app, liquid-blank, functions, storefront-webcomponents, checkout-extension.
• E-commerce (×17, unified category): Medusa, Saleor, Vendure, Magento Hyvä, BigCommerce, PrestaShop, OpenCart, Sylius, ForgeCommerce…
• Backend: Hono, NestJS+Prisma, FastAPI, Django, Phoenix, Rails, Spring Boot, Ktor, Go-Fiber, Rust-Axum.
• Mobile: Flutter, Expo/React Native, Ionic+Capacitor, Kotlin+Compose. Desktop: Tauri, Electron. Games: Phaser, PixiJS, React Three Fiber.

07AI providers

Pcreative Studio invokes external agent CLIs as subprocesses. You pick which one steers each project.

• Claude (claude · Anthropic) · Codex (codex · OpenAI) · Gemini (gemini · Google) · OpenCode (opencode).
• API keys: Settings panel → stored in ~/.config/pcreative-studio/keys.json at 0600; never logged, only shown as set/unset.
• autoskills: installs the stack's technical skills (Next.js, WordPress, Shopify…) into the agent.
• UI/UX Pro Max (uipro): design system — reasoning rules, UI styles, palettes and font pairings for the visual side.

08Design intelligence (UI pro)

For every React project, Pcreative Studio wires a visual layer on top of autoskills/uipro so sites look like studio work: it installs framer-motion and writes two guides (UI-MOTION.md and STACK-PREMIUM.md) the agent reads before touching UI.

• 21st.dev / Magic (MCP, with TWENTYFIRST_API_KEY): pro blocks and sections via /ui.
• React Bits (MCP, no key): the animated "wow" — aurora/particle backgrounds, animated text, effects.
• shadcn (MCP) + registries (Animate UI, SmoothUI, Cult UI…) and, by stack, Chakra UI / HeroUI.
• Uiverse and Preline: Tailwind micro-elements and blocks (context only, no MCP).
• Animation: framer-motion day to day, GSAP (ScrollTrigger/SplitText) for cinematic.
• 3D/WebGL: r3f + drei + postprocessing, only when the niche calls for it, with performance rules (lazy, poster, reduced-motion).

Everything is invoked at runtime (MCPs via npx, npm packages in your project), never bundled into Pcreative Studio; all sources are MIT/Apache-2.0.

09Reference analysis (conversational)

In recreate or adopt mode, the 🔍 Analyze with AI button scans the reference (build-system markers, marketplace structure, mono-repos) and launches the agent with the right prompt (anti-copy rules for commercial templates, or design-export mode if it looks like a Figma/Claude Design export).

• It's a real conversation: you reply and the agent refines the analysis (stack, market, gaps, plan) turn by turn.
• On save, the whole conversation is injected into the project's CLAUDE.md.
• The agent starts aware of your analysis and confirms what it understood before touching code.

10The project window

Every project opens its own window with an embedded multi-tab preview, embedded terminals and live dev-server logs.

• Preview: a tab widget of web views wired to the dev server; shared URL bar, reload, 🚀 open in external browser, 📸 screenshot, 🔧 DevTools.
• Viewport presets: 360, iPhone 14, Tablet, 1280, 1920, Full — responsive QA without another browser.
• Mono-repo: with multiple stacks, a Sub-project selector switches the preview profile/port.
• Terminals (xterm.js + node-pty): Setup, Shell and one per agent, with the CLI already loaded; switch tabs while the agent runs.
• ▶ Start / ■ Stop preview: runs the stack profile; for detached profiles (wp-env, docker) Stop stays active.

11Pre-flight checker (13 checks)

A 🔬 button that verifies the project is ready to upload to a marketplace (Envato, Gumroad…). Fast: filesystem + grep only.

• README present · LICENSE/licensing.txt · documentation/ HTML · screenshots/ (≥3).
• No legacy jQuery 1.x/2.x or Bootstrap 3/4 · no hardcoded trackers (GA, FB Pixel, Hotjar).
• prefers-reduced-motion respected · .env out of git · project size (<50 MB ideal).
• Scaffold placeholders replaced (__SLUG__, YOUR_DOMAIN…) · Lighthouse / html-validate (info).

Verdict: ✓ ready · ⚠ warnings · ✗ blocking fails (likely marketplace rejection). Each item expands with a how-to-fix hint.

12Package for the marketplace (ZIP)

A 📦 button that packages the project into an upload-ready ZIP, aggressively excluding dev noise.

• Excludes node_modules, .git, .next/.nuxt/dist/build, caches, .vscode/.idea/.cursor, vendor, target…
• Excludes .env*, CLAUDE.md, AGENTS.md, GEMINI.md, MEMORY.md, *.log, *.bak…
• Options: include documentation/, screenshots/, source/ (PSDs/Figma).
• Output at ~/Proyectos/themes-builds/<slug>-<date>.zip, wrapped in a <slug>/ folder (marketplace convention).

13Demo deploy

A 🚀 button that builds and deploys to a public host to share a preview with a client or reviewer.

• Targets: Netlify, Vercel, Cloudflare Pages, Surge (first time they open a browser for OAuth).
• Detects the stack (Next export, Astro/Vite, SvelteKit, Gatsby, CRA, Angular, Nuxt, Hugo, Jekyll, HTML) and pre-fills build + dist.
• Shows live build and deploy logs; on success copies the URL to your clipboard.
• Server-rendered stacks (Laravel, WordPress…) don't apply: for those use the ZIP + a host with a runtime.

14Gallery & productivity

The Gallery tab lists every project in ~/Proyectos/themes (+ archived). Each row shows name, stack, last modified, git status, CLAUDE.md and last AI session.

• Per-project tags + a tag:<name> filter in search.
• Archive/restore (reversible, non-destructive) · List or Cards view with thumbnails (from your 📸 or a per-stack placeholder).
• Command palette Ctrl+K: jump to any project, tab or action instantly.
• Actions: ★ favourite, 🔄 regenerate context, 🗑️ delete, open in VSCode/Claude/Codex, open folder.

15Cost tracker

The 💰 Cost tab aggregates tokens and cost across providers by reading ONLY local files in your home — it contacts no API.

• Scanners: Claude Code (.jsonl sessions, robust), Codex (best-effort). Gemini/OpenCode link to their dashboards.
• Embedded pricing per model; cost = input + output + cache write/read.
• Charts: donut by provider, top 10 projects, 30-day stacked. Tables by model/provider/project.
• Click ↻ Re-scan after using the agents (it doesn't auto-refresh while you work).

16Compare agents

The 🤝 Compare tab runs the same prompt across several CLIs in parallel and shows the outputs side by side in resizable panes.

• Per-pane streaming with status, TTFT (time-to-first-token) and total time.
• Use cases: pick the best agent for a task, spot ambiguous prompts (if they diverge), or generate competing solutions to merge.
• 📋 copies a pane's output; ■ cancels all; 🧹 clears.

17GitHub integration

The 📦 GitHub button discovers existing repos and offers update-or-create.

• Checks gh is installed and authenticated; finds repos matching the project name (your user + the configured org).
• Sanitizes the index: ensures .gitignore blocks node_modules, .next, dist, .env*, etc., and untracks anything that slipped in.
• Updates (push) or creates the private repo and pushes, showing the URL on success.

18App themes

Pcreative Studio's own UI is themable: 8 built-in themes (Dark, Light, Dracula, Nord, Tokyo Night, Brutalism, Linear, Soft UI), a visual editor and a Figma DTCG importer.

• Each theme exposes ~50 tokens (color, typography, spacing, shape, component variants).
• The visual editor applies changes instantly (the app is the live preview) and saves to ~/.config/pcreative-studio/themes/.
• The Web UI (inside QtWebEngine) ships its own themes: Neo-Tokyo, Matrix and Kawaii.

19Vibe scaffolder

Describe what you want in natural language and the AI pre-fills stack, type, theme and a ~200-word prompt for the agent.

Example: "Premium landing for a dental clinic in Madrid, warm palette" → Stack: Next.js · Type: Landing · Theme: Soft UI, with a brief ready for the agent to build.

20MCP servers

Pcreative Studio exposes itself as an MCP server (other agents can use its tools: list_stacks, create_project…) and also pre-configures a .mcp.json in each new project.

• Always: filesystem, fetch, memory, github, Pcreative Studio's own MCP.
• Web frontend: playwright, chrome-devtools, figma-context, browsermcp + the UI ones (magic, magicui, shadcn, reactbits).
• By stack: chakra-ui/heroui, shopify-dev, postgres…
• All MIT/Apache-2.0; MCP source is never bundled — the client downloads it at runtime via npx/uvx/docker.

21Remote engine / mobile

A FastAPI gateway (JSON-RPC + WebSocket) exposes the Pcreative Studio engine as an API, and a PWA reimplements the UI over it to drive the engine from your phone on your network.

Meant for launching missions, watching progress and reviewing results without being at the desktop.

22Operator (Hermes) — autonomous missions

Optional mode (requires Hermes Agent): describe a goal and the agent iterates ON ITS OWN — plans, scaffolds, edits and runs QA — with live preview and a chat to steer it.

• Mission Control: launch missions, see the plan and progress, and step in via chat.
• Brain (OpenRouter) + hand (Codex): splits reasoning from execution.
• Learns per project in a .hermes.md and improves mission by mission.
• 🚀 from the Gallery or the project window, even on projects you already have.

23Licensing system (optional, BYO)

Pcreative Studio can inject the license-verification CLIENT into every theme you generate (setup wizard + middleware + HTTP client). It does NOT include the backend: you bring your own or point at a service (Lemon Squeezy, Polar, Paddle, Gumroad…).

• URLs come from your ~/.config/pcreative-studio/licensing.json (YOUR_DOMAIN placeholders if not configured).
• Per stack it generates the right files (Next.js, Laravel, WordPress, Express…).
• If you don't sell with licenses, leave the checkbox off and nothing is added.

24Troubleshooting

• Preview won't load: confirm the dev server started (logs below) and the port matches the one in ~/.config/pcreative-studio/ports.json.
• Agent doesn't respond: check its CLI is on PATH and the API key is set in Settings.
• Scaffold fails: install the stack runtime (Node/PHP/Composer/Docker…) the dependency wizard asks for.
• WordPress/e-commerce stacks: need Docker running to auto-provision the database.