DOCSEARCHbyAlgolia
Submit Docs

open-carrusel

repository·main·Indexed 18 days ago

https://github.com/hainrixz/open-carrusel

An open-source, local-first AI-powered Instagram carousel builder (v0.1.0). It integrates with Claude to design HTML/CSS-based slides and uses Puppeteer to export them as pixel-perfect PNGs at exact Instagram dimensions. Features include brand configuration, template management, reference image support, and a dedicated API for carousel and slide management.

Tokens
7.1K
Snippets
25
Records
35
Agent score
63%

What's inside open-carrusel

  1. How the AI Agent generates slides

    main

    The AI agent is implemented as a Claude CLI subprocess spawned from the /api/chat endpoint with --allowedTools Bash WebFetch.

    When a user requests a slide, the following workflow occurs:

    1. Context Loading: Claude reads your brand configuration and the active carousel state from the system prompt.
    2. HTML Generation: Claude writes the slide content as a complete HTML/CSS string (body-level only).
    3. Slide Submission: Claude uses its Bash tool to execute a curl POST request to /api/carousels/[id]/slides containing the HTML string.
    4. UI Update: The new slide is saved to the local data store and appears in the editor's filmstrip via Server-Sent Events (SSE).

  2. How slide preview and export work

    main

    Open Carrusel ensures that the preview in the editor is identical to the exported PNGs by using a unified HTML wrapping process.

    The Process:

    1. Slides are stored as raw body-level HTML (without <html>, <head>, or <!DOCTYPE> tags).
    2. The shared function wrapSlideHtml() in src/lib/slide-html.ts wraps this body into a full, valid HTML document.
    3. This wrapper adds necessary font loading, dimension constraints, and a box-sizing reset.
    4. The resulting document is used for two distinct paths:
      • Live Preview: Rendered inside a sandboxed <iframe> in the editor (preventing <script> execution).
      • Export: Processed by Puppeteer (headless Chromium), which takes a screenshot at the exact Instagram pixel dimensions specified.

    This architecture guarantees that "what you see is what you ship."

  3. Configure Brand settings

    main

    Brand settings define the visual identity used by the AI agent when generating slides. You can set these during the first run or via the gear icon in the top bar. Settings are stored in /data/brand.json and include:

    • Name: Your handle, company, or project name.
    • Colors: Primary, secondary, accent, background, and surface colors.
    • Fonts: Heading and body fonts (selected from a curated list served by the /api/fonts endpoint).
    • Logo: An optional image used by Claude for branded slides.
    • Style keywords: Free-text hints (e.g., "editorial, minimalist, warm tones") that are injected into Claude's system prompt to guide design output.

  4. Quickstart Open Carrusel Manually

    main

    If you do not use Claude Code, you can set up the project manually using npm. Note that without Claude Code, you will not have access to the AI chat agent, but the editor and export features for static slides will still function.

    1. Clone the repository:
      git clone https://github.com/Hainrixz/open-carrusel.git
cd open-carrusel
    2. Install dependencies and seed the data directory:
      npm run setup
    3. Start the development server:
      npm run dev
      The application will be available at http://localhost:3000.
    git clone https://github.com/Hainrixz/open-carrusel.git
cd open-carrusel
npm run setup
npm run dev

  5. Quickstart Open Carrusel via Claude Code (Recommended)

    main

    The fastest way to run Open Carrusel is using the Claude Code CLI. This method automates dependency installation, data seeding, and starts the development server and browser automatically.

    1. Install and authenticate Claude Code.
    2. Clone the repository and open it in Claude Code:
      git clone https://github.com/Hainrixz/open-carrusel.git
cd open-carrusel
claude
    3. Inside the Claude Code prompt, run:
      /start

    Note: The first run will take 1–2 minutes because Puppeteer must download approximately 300 MB of Chromium for the PNG export functionality.

    git clone https://github.com/Hainrixz/open-carrusel.git
cd open-carrusel
claude
# Then type /start inside the claude prompt

  6. Manage Templates and Reference Images

    main

    Templates

    Save any carousel as a template by clicking the bookmark icon in the editor toolbar. Templates are stored in /data/templates.json and can be accessed via the Templates tab on the dashboard.

    Reference Images

    You can provide visual context to the AI by dropping screenshots into the "Reference Images" section of the chat panel. These files are stored in /public/uploads/. The Claude Code agent can access these via WebFetch using their local URLs to assist in the design process.

  7. How slide version history works

    main
    When calling updateSlide, if the new html content differs from the existing content, the current HTML is pushed into the slide's previousVersions array. This allows for an undo mechanism via undoSlide. The history is capped by MAX_VERSIONS to prevent excessive data growth.

  8. Configure the Claude CLI path

    main

    If the setup script cannot automatically locate your Claude CLI installation, you must manually specify the path using the CLAUDE_CLI_PATH environment variable in a .env.local file.

    On Windows, you can find the path by running where claude in PowerShell (typically C:\Users\<you>\AppData\Roaming\npm\claude.cmd).

    CLAUDE_CLI_PATH=/path/to/claude

  9. Troubleshoot common installation and runtime issues

    main

    Use the following guide to resolve common problems:

    IssueSolution
    Node version error (e.g., "Node v18 detected, need ≥20")Install Node 20+ from nodejs.org or via nvm.
    Claude CLI not foundInstall Claude Code and authenticate. If the path is non-standard, set CLAUDE_CLI_PATH in .env.local.
    Port 3000 is in useRun /stop to kill existing processes, or start on a different port using /start 3001.
    Export fails or hangsThis is likely a Puppeteer/Chromium issue. Run rm -rf node_modules && npm install to re-trigger the Chromium download. On Linux, ensure dependencies like libnss3, libatk1.0-0, and libxss1 are installed via apt.
    AI ignores brand colorsVerify your colors and style keywords are saved in the Brand Setup (gear icon).

    Pro-tip: Run /doctor for a full environment diagnostic audit.

  10. Claude Code Slash Commands for Open Carrusel

    main

    When running Open Carrusel within the Claude Code environment, you can use the following slash commands to manage the application lifecycle:

    CommandDescription
    /start [port]Installs dependencies, seeds data, runs the server, and opens the browser. Idempotent.
    /stop [port]Kills the dev server. Defaults to :3000.
    /resetWipes all local carousels, templates, brand config, uploads, and exports, then re-seeds defaults.
    /doctorRuns setup diagnostics (Node version, Claude CLI path, dependencies, data seeding, and port availability).

  11. Run environment diagnostics with /doctor

    main
    The /doctor command is a Claude Code slash command that performs a full environment audit. It checks for common issues such as Node.js version compatibility, Claude CLI availability, and port conflicts to help you resolve setup problems quickly.

  12. NPM Scripts for Open Carrusel

    main

    The following npm scripts are available for managing the project outside of the Claude Code environment:

    CommandDescription
    npm run setupInstalls dependencies and seeds the /data/ directory. Equivalent to /start in Claude Code (but does not open the browser).
    npm run devStarts the local development server.
    npm run buildCreates a production build.
    npm run doctorRuns setup diagnostics via scripts/doctor.mjs. Can be run even before npm install is complete.
    npm run setup
npm run dev
npm run build
npm run doctor