Content
# Comic Sol
Comic Sol is a pure installable Codex Skill 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.
## 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:
```bash
git clone https://github.com/wenn-id/comic-sol.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: install 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:
```powershell
git clone https://github.com/wenn-id/comic-sol.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.
## Native Hermes 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.
To run the MCP adapter, install the SDK alongside Pillow:
```bash
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:
```bash
OUTPUT_ROOT="$(pwd)/comic-sol-output"
python3.11 scripts/mcp_server.py --root "$OUTPUT_ROOT"
```
For an MCP client configuration, resolve `python3.11`, `scripts/mcp_server.py`, and
the selected output root to absolute paths from the current checkout. Do not copy
paths from another machine. A portable installed CLI is not available yet. Disable
sampling and lock the server to that output root. The server exposes the full
deterministic lifecycle as 17 `comic_*` tools.
## 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
See [`references/capability-detection.md`](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`](references/image-provider-setup.md).
For deterministic diagnostics:
```bash
python3.11 scripts/comic_sol.py 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:
```text
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](tests/fixtures/valid-one-page) 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 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 its target, and 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:
```bash
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:
```bash
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)
```bash
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:
```bash
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:
```powershell
$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`](LICENSE). The bundled Comic Neue and Noto Sans fonts remain separately
licensed under the SIL Open Font License 1.1; see
[`assets/README.md`](assets/README.md).
