Comic Sol

Comic Sol is an installable Codex Skill and portable Python CLI that turns a short prompt, pasted story, or .txt/.md file into an original manga/anime comic. One natural-language invocation drives planning, character consistency, image generation, visual QA, selective repair, deterministic lettering and composition, and PDF export. It is not a web app or hosted product. No build service is required.

This repository, wenn-id/comicsol, is the canonical, independent home of Comic Sol. New development, issues, pull requests, documentation, and releases happen here.

Install

Requirements are Python 3.11 and Pillow==12.3.0. Image creation additionally requires an image-generation capability exposed to the active agent session; Comic Sol never embeds provider credentials.

Clone the public repository directly into the Codex skills directory, then install the one pinned dependency:

git clone https://github.com/wenn-id/comicsol.git \
  "${CODEX_HOME:-$HOME/.codex}/skills/comic-sol"
cd "${CODEX_HOME:-$HOME/.codex}/skills/comic-sol"
python3.11 -m pip install -r requirements.txt

The host-agnostic rule is: clone or copy this repository as one comic-sol folder beneath the Codex skills directory configured by your Codex installation. Keep SKILL.md, scripts/, references/, templates/, and assets/ together.

Windows PowerShell:

git clone https://github.com/wenn-id/comicsol.git `
  "$env:USERPROFILE\.codex\skills\comic-sol"
Set-Location "$env:USERPROFILE\.codex\skills\comic-sol"
py -3.11 -m pip install -r requirements.txt

Supported environments are Linux, macOS, Windows, and WSL with Python 3.11 and Pillow 12.3.0. The deterministic test suite does not need an image provider.

Install the portable CLI from a checkout and verify the bundled deterministic engine, fonts, and templates:

python3.11 -m pip install .
comic-sol --json doctor

The CLI currently exposes doctor, init, status, validate, resume, finalize, and the optional mcp launcher. Machine-readable responses use one stable envelope containing ok, command, data, and error.

Native Distribution (v2.0.0rc4)

The v2.0.0rc4 prerelease provides bundled portable archives for Linux, macOS, and Windows x86_64, plus transactional user-local installers and a non-root OCI image. Native archives include Python, Pillow, MCP, fonts, templates, the Skill, and references, so installed execution does not require a system Python.

Every native bundle includes SHA256SUMS, deterministic metadata, and a CycloneDX SBOM. The RC artifacts are explicitly unsigned and not notarized; verify the SHA-256 digest before execution. Exact install, upgrade, rollback, uninstall, and security instructions are in docs/install.md.

Container and Compose deployment commands are documented in docs/install.md; they are optional and are not required for the normal local CLI workflow.

Native uninstall removes only the runtime. User projects and separately managed MCP client configurations remain preserved.

MCP Server (Optional)

Comic Sol includes an optional stdio MCP server that exposes the deterministic pipeline as standard tools for Hermes Agent, Claude Desktop, Cursor, or any MCP client.

Sampling should remain disabled to preserve deterministic execution.

To run the MCP adapter, install the SDK alongside Pillow:

python3.11 -m venv ~/.venvs/comic-sol-mcp
~/.venvs/comic-sol-mcp/bin/pip install -r requirements.txt -r requirements-mcp.txt

From the repository root, start the development server with a repository-relative script path and an absolute selected output root:

OUTPUT_ROOT="$(pwd)/comic-sol-output"
python3.11 scripts/mcp_server.py --root "$OUTPUT_ROOT"

For an MCP client configuration, lock the server to one absolute output root and keep sampling disabled. An installed package uses the stable launcher:

python3.11 -m pip install '.[mcp]'
comic-sol mcp --root /absolute/path/to/comic-sol-output

Transactional client integration is available through:

comic-sol --json setup --output-root /absolute/path/to/comic-sol-output
comic-sol --json repair --output-root /absolute/path/to/comic-sol-output
comic-sol --json uninstall --output-root /absolute/path/to/comic-sol-output

Setup refuses malformed native config, creates a timestamped backup before each change, writes atomically, and restores the original bytes if verification fails. Repeated setup is idempotent. Uninstall removes only the MCP integration and preserves comic projects. Codex TOML and detected JSON client configs are mutated only at verified locations; clients whose native format or location has not been verified are reported as unsupported rather than guessed.

During source development, python3.11 scripts/mcp_server.py --root PATH remains available. Both entry points expose the same protocol-tested deterministic lifecycle as exactly 17 comic_* tools.

Provider contract

Image-provider integrations implement the immutable GenerationProvider protocol from comic_sol_product.providers. Requests record only prompt hashes, dimensions, relative references, and optional provider/model/seed identifiers. Results retain only allowlisted metadata plus raster bytes and SHA-256; credentials and raw provider payloads are never accepted into the contract. The base package includes no HTTP or provider SDK. Retained results pass through the engine's existing containment, raster verification, and retry-budget accounting.

Invoke

Open Codex with the skill installed and say, for example:

Make a 2-page manga about a courier delivering sunlight to an underground city.

That is the complete user invocation. Comic Sol detects prompt, pasted-story, source-file, or resume mode; applies documented defaults; and asks only materially missing questions. It reports an explicit error if the agent session cannot return a local raster image. See references/capability-detection.md for the exact capability check and preserved-project recovery procedure. Platform-specific image-provider setup is documented in references/image-provider-setup.md.

For deterministic diagnostics:

python3.11 scripts/comic_sol.py doctor --output-root /tmp/comic-sol-doctor
# Installed equivalent:
comic-sol --json doctor --output-root /tmp/comic-sol-doctor

Inspect the result

Each run preserves editable semantic and visual intermediates beneath its generated project directory. The important outputs are:

project.json                  project manifest and current state
plan/                         story plan, character bible, and storyboard
prompts/                      editable reference and panel prompts
references/                   canonical character and scene images
panels/raw/                   generated panel PNGs
panels/clean/                 accepted clean panel PNGs
panels/*/lettered.png         deterministic lettered panel PNGs
pages/page-001.png            ordered 1600×2400 page PNGs
exports/<project-id>.pdf      ordered comic PDF
qa/panels/*.json              seven-check panel QA records
qa/report.md                  human-readable QA report
logs/                         sanitized events, cache, and retry accounting

The committed one-page synthetic fixture provides sample-output inspection without an external provider. Its three geometric panel PNGs are deterministic test data, not generated art or a claimed live sample.

Architecture

SKILL.md orchestrates ten agent stages and progressively loads guidance from references/. Agent reasoning creates the editable story, character, storyboard, prompt, and QA decisions. Python scripts handle only deterministic project state, validation, resume planning, lettering, page composition, PDF export, and report rendering. Provider access remains in the agent capability plane; secrets and provider SDKs do not enter deterministic scripts.

Hybrid lettering

Dialogue is rendered in uppercase, while authored caption casing is preserved.

Dialogue uses bundled Comic Neue Regular, and inline **bold** emphasis uses Comic Neue Bold with wrapping and centering measured across the mixed runs. Font selection is per-character: bundled Noto Sans covers Greek and Cyrillic when Comic Neue does not, while a character absent from both fonts is preserved as Noto Sans .notdef rather than silently dropped. The --font option still overrides the regular dialogue font; its bold counterpart may fall back to Comic Neue Bold.

Pillow fits dialogue into adaptive oval balloons, attaches each tail at the nearest oval boundary toward a validated speaker or device anchor, and renders a tapered organic cubic tail that stops before the voice source. It also draws compact light caption strips sized to their text. Authored SFX takes the other half of the hybrid pipeline: the image model draws the exact SFX into the artwork, and visual QA verifies spelling, count, and authorization. Pillow validates and counts SFX but reserves no placement and changes no pixels for it.

Test

Run the complete offline suite:

python3.11 -m unittest discover -s tests -v
python3.11 scripts/comic_sol.py doctor

Base environment (Pillow only, MCP tests skipped)

Create a clean virtual environment and install only the base dependency:

python3.11 -m venv /tmp/comic-sol-base
/tmp/comic-sol-base/bin/pip install -r requirements.txt
/tmp/comic-sol-base/bin/python -m unittest discover -s tests -v

MCP tests (test_mcp_server.py) are skipped gracefully when the mcp package is absent.

MCP-extra environment (Pillow + MCP, all tests run)

python3.11 -m venv /tmp/comic-sol-mcp-extra
/tmp/comic-sol-mcp-extra/bin/pip install -r requirements.txt -r requirements-mcp.txt
/tmp/comic-sol-mcp-extra/bin/python -m unittest discover -s tests -v

Clean-room Linux/macOS/WSL check:

tmp_dir=$(mktemp -d)
python3.11 -m venv "$tmp_dir/venv"
"$tmp_dir/venv/bin/python" -m pip install Pillow==12.3.0
"$tmp_dir/venv/bin/python" scripts/comic_sol.py doctor --output-root "$tmp_dir/output"

Windows clean-room equivalent:

$TempRoot = Join-Path $env:TEMP "comic-sol-clean-room"
py -3.11 -m venv "$TempRoot\venv"
& "$TempRoot\venv\Scripts\python.exe" -m pip install Pillow==12.3.0
& "$TempRoot\venv\Scripts\python.exe" scripts\comic_sol.py doctor --output-root "$TempRoot\output"

Support matrix

Area	Supported	Notes
Inputs	Short prompt, pasted prose, UTF-8 .txt and .md, resume	Source limit and defaults are documented in the workflow reference.
Output	Panel PNGs, page PNGs, comic PDF, manifest, QA report	Editable intermediate artifacts remain local.
Lettering	Comic Neue Regular/Bold; per-character Noto Sans fallback	Adaptive oval dialogue, actual inline bold emphasis, compact captions, and hybrid authored SFX are supported. Font licenses and digests are in assets/README.md.
Image generation	Agent-exposed image model returning a local raster	References and exact dimensions are used when supported; exact authored SFX is checked by visual QA.
Deterministic scripts	Python 3.11 and Pillow 12.3.0	Offline and provider-neutral.
Native MCP	Python 3.11 and MCP SDK 1.28.1 via stdio	Exposes 17 tools covering the full deterministic lifecycle safely locked to one output root.

Privacy, IP, and Limitations

Project artifacts stay in the selected local output directory. Prompts and reference images sent to a selected image tool are governed by its external provider policies. Minimize private source material and never place secrets in story text or prompts. Logs contain sanitized paths, hashes, categories, and state changes rather than raw credentials or story content.

Comic Sol requests original manga/anime direction and translates disallowed artist or franchise imitation into high-level visual traits. It does not promise perfect character continuity: results depend on the available image capability, especially its reference-image and dimension support. The bundled font set does not cover CJK; characters absent from both bundled fonts are preserved as visible .notdef fallback boxes unless a compatible regular --font override covers them. Image-model SFX spelling is not deterministic, so visual QA and bounded retries remain required. Offline fixtures prove deterministic stages, not live image quality. Large projects beyond four pages or twelve panels require an explicit scope decision.

For support, run doctor, retain the printed project path, and inspect project.json plus qa/report.md. A BLOCKED project is intentionally resumable; restore the missing capability or correct the reported artifact, then ask Codex to resume that Comic Sol project.

License

Comic Sol's original code and documentation are available under the MIT License in LICENSE. The bundled Comic Neue and Noto Sans fonts remain separately licensed under the SIL Open Font License 1.1; see assets/README.md.

Contributing and security

Development is review-first through pull requests into main. See CONTRIBUTING.md for the required validation gates. Report security issues privately as described in SECURITY.md.