{"id":46702455,"url":"https://github.com/clawvisual/clawvisual","last_synced_at":"2026-03-12T10:00:45.146Z","repository":{"id":342469695,"uuid":"1173500133","full_name":"clawvisual/clawvisual","owner":"clawvisual","description":"Turn long text into visual summaries. AI-powered image generation from articles, reports, or documents.","archived":false,"fork":false,"pushed_at":"2026-03-10T07:57:06.000Z","size":13755,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-10T14:08:25.061Z","etag":null,"topics":["agent","ai","automation","carousel","content-creation","llm","mcp","open-source","openclaw","social-media","workflow"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clawvisual.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-05T12:41:50.000Z","updated_at":"2026-03-10T07:57:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/clawvisual/clawvisual","commit_stats":null,"previous_names":["clawvisual/clawvisual"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/clawvisual/clawvisual","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawvisual%2Fclawvisual","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawvisual%2Fclawvisual/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawvisual%2Fclawvisual/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawvisual%2Fclawvisual/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clawvisual","download_url":"https://codeload.github.com/clawvisual/clawvisual/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawvisual%2Fclawvisual/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30376755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","automation","carousel","content-creation","llm","mcp","open-source","openclaw","social-media","workflow"],"created_at":"2026-03-09T07:09:14.185Z","updated_at":"2026-03-11T09:01:02.406Z","avatar_url":"https://github.com/clawvisual.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"public/logo.png\" alt=\"clawvisual logo\" height=\"36\" style=\"border-radius:8px; vertical-align:middle;\" /\u003e clawvisual AI\n\n中文文档: [README.zh-CN.md](README.zh-CN.md)\n\nclawvisual AI is an open source **URL to social carousel** generator for creators, growth teams, and builders of **agent workflow** automation.\n\nTurn a long article or URL into a social-ready carousel with hooks, captions, hashtags, slide copy, and generated visuals. It runs as an **MCP**-compatible service, so other agents can call it as a reusable skill.\n\n### Feature Preview\n\u003cp\u003e\n  \u003cimg src=\"screenshots/quickstart.gif\" alt=\"clawvisual feature preview\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n## Features\n\n- URL or long-form text in, finished carousel structure out\n- Generates real slide images and prompts, not just text summaries\n- Async job pipeline with progress events, revisions, and downloadable output\n- Supports portrait, square, story, and landscape output ratios\n- MCP-compatible, so other agents can call it as a tool\n\n## Docs\n\n- [Quickstart Guide for URL to Social Carousel](docs/Quickstart-URL-to-Social-Carousel.md)\n- [MCP Integration Guide for clawvisual](docs/MCP-Integration-Guide-for-clawvisual.md)\n- [Use Cases for Agent Workflow Automation](docs/Use-Cases-Agent-Workflow-Automation.md)\n\nDefault output constraints (fast mode):\n- `post_title`: one-sentence hook\n- `post_caption`: concise body, normalized to 100-300 characters\n- `hashtags`: 1-5 tags\n- `aspect_ratios`: choose from `4:5`, `1:1`, `9:16`, `16:9`\n- `slides`: generated visual slides are required, not text-only output\n  - each slide should include `image_url` and `visual_prompt`\n  - cover slide (`slide_id: 1`) should prioritize first-glance clarity and hook strength\n\n## Real Example\n\nTested locally against this public article:\n- [How to fix your entire life in 1 day](https://letters.thedankoe.com/p/how-to-fix-your-entire-life-in-1)\n\nGenerated output (`output_language: en-US`, `max_slides: 4`):\n\n```json\n{\n  \"post_title\": \"Why 90% of New Year’s resolutions fail (and how to fix yours).\",\n  \"post_caption\": \"Most people don't actually want to change—they just want to impress others. True transformation isn't about discipline; it's about digging into your psyche to uncover what you actually want.\",\n  \"hashtags\": [\"#Psychology\", \"#AI\", \"#Productivity\", \"#MindsetShift\", \"#IdentityDesign\"]\n}\n```\n\nGenerated slide previews:\n\n\u003cp\u003e\n  \u003cimg src=\"screenshots/readme-cover-en.png\" alt=\"Generated cover slide\" width=\"49%\" /\u003e\n  \u003cimg src=\"screenshots/readme-slide-2-en.png\" alt=\"Generated second slide\" width=\"49%\" /\u003e\n\u003c/p\u003e\n\n## Quick Start (Web)\n\n1. Install dependencies:\n\n```bash\nnpm install\n```\n\n2. Create local env file:\n\n```bash\ncp .env.local.template .env.local\n```\n\n3. Fill required key in `.env.local`:\n- `LLM_API_KEY`\n\n`LLM_API_URL` and `LLM_MODEL` already default to OpenRouter + Gemini Flash:\n- `LLM_API_URL=https://openrouter.ai/api/v1/chat/completions`\n- `LLM_MODEL=google/gemini-3-flash-preview`\n\nImportant local-dev note:\n- `.env.local.template` now leaves `CLAWVISUAL_API_KEYS` empty by default.\n- Local requests do not require `x-api-key` unless you explicitly configure `CLAWVISUAL_API_KEYS`.\n- If you enable API-key validation, send the same configured value in the `x-api-key` header.\n- For real image generation instead of fallback gradients/SVGs, also set a valid `GEMINI_API_KEY` and `NANO_BANANA_MODEL`.\n- If `LLM_COPY_POLISH_MODEL` is unavailable on your provider, the copy-polish stage may be skipped.\n\n4. Start dev server:\n\n```bash\nnpm run dev\n```\n\n5. Open in browser:\n- `http://localhost:3000`\n\nIf `3000` is already occupied, Next.js will move to another port such as `3001`. Use the actual port shown in the terminal.\n\n## CLI (npm -g)\n\nInstall global CLI:\n\n```bash\nnpm install -g clawvisual\n```\n\nThen run:\n\n```bash\nclawvisual set CLAWVISUAL_LLM_API_KEY \"your_openrouter_key\"\n# optional\nclawvisual set CLAWVISUAL_LLM_MODEL \"google/gemini-3-flash-preview\"\nclawvisual initialize\nclawvisual stop\nclawvisual restart\nclawvisual status\nclawvisual tools\nclawvisual convert --input \"Paste long-form text or URL here\" --slides auto\nclawvisual status --job \u003cjob_id\u003e\n```\n\n`clawvisual initialize` will auto-start a local service when `CLAWVISUAL_MCP_URL` points to localhost. It prints the web URL after startup, then you can continue with `clawvisual xxx` commands.\n`clawvisual stop` stops the local service started by CLI managed process tracking. `clawvisual restart` performs stop + initialize.\n`clawvisual status` checks service identity (must be `clawvisual`) and avoids false positives from other local MCP servers on the same port.\n`clawvisual set/get/unset/config` stores local CLI config at `~/.clawvisual/config.json` (keys are case-insensitive, e.g. `clawvisual set clawvisual_llm_api_key ...`).\n\nCLI environment variables:\n- `CLAWVISUAL_MCP_URL` (default: `http://localhost:3000/api/mcp`)\n- `CLAWVISUAL_API_KEY` (required only when API key validation is enabled)\n- `CLAWVISUAL_LLM_API_KEY` / `CLAWVISUAL_LLM_API_URL` / `CLAWVISUAL_LLM_MODEL` (CLI-level aliases mapped to server `LLM_*` envs)\n- `CLAWVISUAL_GEMINI_API_KEY` (CLI-level alias mapped to server `GEMINI_API_KEY`)\n  - If `GEMINI_API_KEY` is not configured, image generation falls back to OpenRouter and is usually slower.\n\n## Docker\n\nBuild image:\n\n```bash\ndocker build -t clawvisual:1.0.0 .\n```\n\nRun container:\n\n```bash\ndocker run --rm -p 3000:3000 \\\n  -e LLM_API_KEY=your_openrouter_api_key \\\n  -e GEMINI_API_KEY=your_gemini_api_key \\\n  -e NANO_BANANA_MODEL=gemini-3.1-flash-image-preview \\\n  clawvisual:1.0.0\n```\n\nGHCR release-style run command:\n\n```bash\ndocker run --rm -p 3000:3000 \\\n  -e LLM_API_KEY=your_openrouter_api_key \\\n  ghcr.io/\u003cowner\u003e/clawvisual:\u003ctag\u003e\n```\n\n## Workflow\n\n1. Input URL or long-form text\n2. Run skill pipeline to generate hooks, slide copy, visuals, and hashtags\n3. Poll async job status until completion\n4. Review output and optionally run revision actions (`rewrite_copy_style`, `regenerate_cover`, `regenerate_slides`)\n5. Export/download final assets\n\nIn the web composer, use the `Aspect ratio` selector to switch between portrait, square, story, and landscape (`16:9`) outputs.\n\n## Quick Smoke Test\n\nAfter `npm run dev`, confirm the service is healthy before testing the full UI.\n\n1. Open OpenAPI:\n\n```bash\ncurl http://localhost:3000/api/openapi.json\n```\n\n2. List MCP tools:\n\n```bash\ncurl -X POST http://localhost:3000/api/mcp \\\n  -H 'content-type: application/json' \\\n  --data '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'\n```\n\n3. Create a conversion job:\n\n```bash\ncurl -X POST http://localhost:3000/api/v1/convert \\\n  -H 'content-type: application/json' \\\n  --data '{\n    \"input_text\": \"Open source projects grow faster when onboarding is simple and the value is visible on first use.\",\n    \"max_slides\": 4,\n    \"aspect_ratios\": [\"16:9\"]\n  }'\n```\n\n4. Poll the returned `status_url` until `status` becomes `completed` or `failed`.\n\nExpected first-run behavior:\n- The job should be accepted immediately and return `202`.\n- In `fast` mode, several quality stages are intentionally reported as `skipped:fast_mode`.\n- Without fully working external model/image credentials, some quality/image steps may degrade or fall back.\n- Leaving `NANO_BANANA_MODEL` as the template placeholder can trigger image-generation retries and fallback placeholder outputs.\n\n## OpenClaw Integration (as a Skill)\n\nclawvisual can be integrated into OpenClaw as a workspace/local skill via MCP.\n\n1. Run clawvisual service:\n\n```bash\nnpm install\ncp .env.local.template .env.local\nnpm run dev\n```\n\n2. Install this skill into OpenClaw:\n- copy [skills/clawvisual](skills/clawvisual) to either:\n  - `\u003copenclaw-workspace\u003e/skills/clawvisual` (workspace scope), or\n  - `~/.openclaw/skills/clawvisual` (shared local scope)\n\n3. Configure skill runtime env:\n\n```bash\nCLAWVISUAL_MCP_URL=http://localhost:3000/api/mcp\nCLAWVISUAL_API_KEY=\u003cyour_clawvisual_api_key_if_enabled\u003e\n```\n\nIf the dev server starts on `3001` or another port, update `CLAWVISUAL_MCP_URL` accordingly.\n\nIf you explicitly configure `CLAWVISUAL_API_KEYS`, set `CLAWVISUAL_API_KEY` to one of those accepted values.\n\n4. Test the skill client locally:\n\n```bash\nnpm run skill:clawvisual -- tools\n```\n\n## MCP\n\n- Endpoint: `POST /api/mcp`\n- Methods: `initialize`, `tools/list`, `tools/call`\n- Tools: `convert`, `job_status`, `revise`, `regenerate_cover`\n\n## FAQ\n\n### Can I self-host clawvisual?\n\nYes. This repository is self-hostable with Node.js and environment variables in `.env.local`.\n\n### Can I run batch generation?\n\nYes. Use API or MCP calls from scripts/workflows and submit multiple conversion jobs asynchronously.\n\n### Can I use this in automation pipelines?\n\nYes. The MCP interface is designed for automation and agent workflow orchestration.\n\n### Can another agent call clawvisual as a skill?\n\nYes. Use the `skills/clawvisual` package and point it to your `CLAWVISUAL_MCP_URL`.\n\n## Roadmap\n\n- Better batch orchestration and queue controls\n- Expanded template/style presets\n- Stronger evaluation cases and regression gates\n- More granular asset export formats\n- Weekly release notes in [GitHub Releases](../../releases)\n\n## Implemented Architecture (V1 Scaffold)\n\n- Framework: Next.js App Router + TypeScript\n- API:\n  - `POST /api/v1/convert` starts a 16-skill chain and returns `job_id`\n  - `GET /api/v1/jobs/:id` returns status/progress/result\n  - `POST /api/mcp` JSON-RPC MCP endpoint (`initialize`, `tools/list`, `tools/call`)\n  - `GET /api/openapi.json` exports OpenAPI schema\n- Skill system: `src/lib/skills` contains 16 atomic async skills\n- Prompt templates: `src/lib/prompts/index.ts`\n- Orchestration: `src/lib/orchestrator.ts`\n- Queue:\n  - Local in-memory job queue for immediate development\n- API key validation: `src/lib/auth/api-key.ts`\n\n## Directory Layout\n\n- `src/app/page.tsx`: clawvisual dashboard UI\n- `src/app/api/v1/convert/route.ts`: conversion entrypoint\n- `src/app/api/v1/jobs/[id]/route.ts`: job status endpoint\n- `src/app/api/openapi.json/route.ts`: OpenAPI export\n- `src/lib/types`: standard interfaces and context object\n- `src/lib/skills`: 16 atomic skill modules\n\n## Environment Variables\n\nExisting keys are reusable. Current scaffold reads:\n\n- `LLM_API_URL` (optional, default `https://openrouter.ai/api/v1/chat/completions`)\n- `LLM_API_KEY`\n- `LLM_MODEL` (optional, default `google/gemini-3-flash-preview`)\n- `LLM_TIMEOUT_MS` (optional, default `25000`)\n- `LLM_COPY_FALLBACK_MODEL` (optional, default `google/gemini-2.5-flash`)\n- `LLM_COPY_POLISH_MODEL` (optional, default `openai/gpt-5.1-mini`)\n- `GEMINI_API_KEY`\n- `NANO_BANANA_MODEL`\n- `NANO_BANANA_TIMEOUT_MS` (optional, default `60000`)\n- `NANO_BANANA_TRANSIENT_RETRY_MAX` (optional, default `2`)\n- `NANO_BANANA_RETRY_BASE_DELAY_MS` (optional, default `450`)\n- `QUALITY_LOOP_ENABLED` (optional, default `true`)\n- `QUALITY_AUDIT_THRESHOLD` (optional, default `78`)\n- `QUALITY_IMAGE_COVER_THRESHOLD` (optional, default `85`)\n- `QUALITY_IMAGE_INNER_THRESHOLD` (optional, default `78`)\n- `QUALITY_COVER_FIRST_GLANCE_THRESHOLD` (optional, default `82`)\n- `QUALITY_COVER_NOVELTY_THRESHOLD` (optional, default `80`)\n- `QUALITY_COVER_CANDIDATE_COUNT` (optional, default `1`)\n- `QUALITY_MAX_COPY_ROUNDS` (optional, default `1`)\n- `QUALITY_MAX_IMAGE_ROUNDS` (optional, default `0`)\n- `QUALITY_MAX_EXTRA_IMAGES` (optional, default `1`)\n- `QUALITY_IMAGE_LOOP_MAX_MS` (optional, default `120000`)\n- `QUALITY_IMAGE_AUDIT_SCOPE` (optional, `cover` or `all`, default `cover`)\n- `PIPELINE_MODE` (optional, `fast` or `full`, default `fast`)\n- `PIPELINE_MAX_DURATION_MS` (optional, default `300000`)\n- `PIPELINE_ENABLE_SOURCE_INTEL` (optional, default `false` in fast mode)\n- `PIPELINE_ENABLE_STORYBOARD_QUALITY` (optional, default `false` in fast mode)\n- `PIPELINE_ENABLE_STYLE_RECOMMENDER` (optional, default `false` in fast mode)\n- `PIPELINE_ENABLE_ATTENTION_FIXER` (optional, default `false` in fast mode)\n- `PIPELINE_ENABLE_POST_COPY_QUALITY` (optional, default `false` in fast mode)\n- `PIPELINE_ENABLE_FINAL_AUDIT` (optional, default `false` in fast mode)\n\nRuntime observability:\n- Thinking \u0026 Actions event timeline now includes per-step token usage deltas (`in/out/total`) when provider `usage` is returned.\n- Final `skill_logs` includes `llm_usage_summary` for total request-level token aggregation.\n- `OPENROUTER_API_KEY`\n- `TAVILY_API_KEY`\n- `SERPER_API_KEY`\n- `JINA_API_KEY`\n\nAPI security controls:\n\n- `CLAWVISUAL_API_KEYS` comma-separated accepted keys\n- `CLAWVISUAL_ALLOW_NO_KEY` default `true` in local development\n\n## Notes\n\n- This project includes async conversion pipeline + revision engine + MCP-compatible JSON-RPC endpoint.\n- Real integrations (Flux/Midjourney, Redis/BullMQ worker process, PostgreSQL persistence, satori rendering) are left as plug-in points.\n\n## MCP Tools\n\n`POST /api/mcp` supports:\n\n- `convert`: create conversion job\n- `job_status`: fetch current job status/result\n- `revise`: create revision job for copy/image changes\n- `regenerate_cover`: regenerate cover via job revision or direct prompt image call\n\n## Skill Template\n\nReusable external skill package:\n\n- [skills/clawvisual/SKILL.md](skills/clawvisual/SKILL.md)\n- [skills/clawvisual/scripts/clawvisual-client.mjs](skills/clawvisual/scripts/clawvisual-client.mjs)\n\nConvenience command:\n\n- `npm run skill:clawvisual -- tools`\n\n## Common Local Issues\n\n- `Missing x-api-key`\n  - Cause: API-key validation was explicitly enabled by setting `CLAWVISUAL_API_KEYS`.\n  - Fix: send `x-api-key`, or clear `CLAWVISUAL_API_KEYS` for local no-auth mode.\n\n- MCP client points to the wrong service\n  - Cause: `npm run dev` switched to `3001`, but the client default is still `http://localhost:3000/api/mcp`.\n  - Fix: set `CLAWVISUAL_MCP_URL` to the real local port.\n\n- Next.js workspace-root warning during `dev` or `build`\n  - Cause: another lockfile exists above this repo, so Next.js infers a higher workspace root.\n  - Fix: set `turbopack.root` in `next.config.ts` or remove the unrelated parent lockfile.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclawvisual%2Fclawvisual","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclawvisual%2Fclawvisual","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclawvisual%2Fclawvisual/lists"}