Storytold

Claude Code & Codex plugin for the open-source ArtCraft Craft App Suite: one
craft Skill drives 13 local, headless Craft MCP apps (photo, vector, video,
RAW, PDF, layout, sheets, docs, slides, CAD, audio, motion, interface design)
with staged copies and verified exports.

English · Deutsch · Türkçe

Thank you, ArtCraft team! Storytold is built on the Craft App Suite, which
the ArtCraft team released as free, open-source
software: thirteen creative apps, each written from scratch. We're grateful for
their generosity. None of this integration would exist without their work.

❤️ ArtCraft team 💚

Local creative work. Native app engines. Verified file handoffs.

Storytold is Devsolux's local integration kit for thirteen existing Craft CLI MCP
servers. One compact craft Skill guides the host; the apps keep their own
schemas, editing state, rendering and save semantics. Deterministic helpers
install and pin the thirteen CLIs on explicit command, stage files, generate
evidence-bound config and verify artifacts within stated limits. No
gateway MCP server or second AI agent.

User + Claude Code / local Codex
           │  one craft Skill; native tool discovery and approvals
           ├── stdio ── PhotoCraft, VectorCraft, FilmCraft, LightCraft
           ├── stdio ── PdfCraft, EffectCraft, DesignCraft, GridCraft
           ├── stdio ── WordCraft, DeckCraft, CADCraft, SoundCraft
           └── stdio ── FigCraft
                                │
                      native engines → durable files

The offline core suite, the official MCP SDK contract test,
strict Claude manifest validation and Claude Code/Codex install with Skill
discovery have been run, and setup has installed, probed and
Sigstore-verified all thirteen Craft CLIs on macOS, Linux and Windows runners
(twelve of them on a developer Mac as well); read
verification. Craft apps
are not bundled: installing the plugin installs guidance, the reviewed release
manifest and inactive templates, never binaries, permissions or running MCP
processes. Only the explicit setup command below installs and registers the
CLIs. Business use requires the local acceptance gates in
acceptance.

Install the Skill/plugin

Repository devsolux/storytold · plugin storytold · marketplace
devsolux-storytold. Both hosts take plugin@marketplace:

claude plugin marketplace add https://github.com/devsolux/storytold
claude plugin install storytold@devsolux-storytold

codex plugin marketplace add devsolux/storytold
codex plugin add storytold@devsolux-storytold

Update later (step 1 of 2):

claude plugin marketplace update devsolux-storytold
claude plugin update storytold@devsolux-storytold

codex plugin marketplace upgrade devsolux-storytold
codex plugin add storytold@devsolux-storytold

Codex has no plugin update: marketplace upgrade refreshes the Git snapshot
and running plugin add again installs the newer version from it. A plugin
update brings the Skill, docs and the refreshed release manifest; it never
touches installed CLIs or host registrations, and the plugin directory now
carries the new version number. Step 2 of 2 moves the Craft CLIs:

python3 ~/.codex/plugins/cache/devsolux-storytold/storytold/<version>/storytold.py setup --list

python3 ~/.codex/plugins/cache/devsolux-storytold/storytold/<version>/storytold.py setup --all --upgrade --acknowledge-unconfined

--list shows which pins moved (manifest_commit_pinned: false);
--all --upgrade re-downloads only those apps, verifies and re-probes them and
leaves registrations as they are (same command path). When a release changes
an app's launch arguments (1.5.0 adds WordCraft's root flags), add --replace
so the differing registration is re-registered; without it setup reports it
and leaves it alone. Remove:

python3 ~/.codex/plugins/cache/devsolux-storytold/storytold/<version>/storytold.py setup --remove --all
claude plugin uninstall storytold@devsolux-storytold
codex plugin remove storytold@devsolux-storytold

setup --remove --all first unregisters and deletes the thirteen
Storytold-managed CLIs and their pins (the workspace and its outputs stay, and
so does anything the lock cannot prove Storytold installed); uninstalling the
plugin alone would leave the servers registered and running.

The generated plugins/storytold/ runtime is committed, so both hosts install
straight from the public repository; nothing is built during installation. From
a source checkout, make install-claude-local or make install-codex-local
installs the local marketplace instead. These commands change host state; builds
and tests never run them, and only the explicit make github-* targets commit
or push.

Claude Code exposes the Skill as /storytold:craft; Codex lists it as
storytold:craft in its Skill picker. Use one native MCP registration per app.
Local Codex support is an additive packaging/configuration adaptation, not a
remote ChatGPT connector. Host packaging and installation sources are recorded in
source ledger.

Craft App Suite

ArtCraft Launcher installs the Craft App Suite: free, open-source creative tools from the
ArtCraft team, each written from scratch in Rust and each able to
stand on its own.

	App	What it's for	Code	Learn more
	PhotoCraft	Image editing: layers, masks, type and real PSD files	GitHub	Website
	VectorCraft	Vector illustration	GitHub	Website
	FilmCraft	Video editing, color and sound	GitHub	Website
	LightCraft	Photo library and raw development	GitHub	Website
	PdfCraft	Reading, organizing and protecting PDFs	GitHub	Website
	EffectCraft	Motion graphics and visual effects	GitHub	Website
	DesignCraft	Page layout and publishing	GitHub	Website
	GridCraft	Spreadsheets and data	GitHub	Website
	WordCraft	Word processing and documents	GitHub	Website
	DeckCraft	Presentations and slide decks	GitHub	Website
	CADCraft	Computer-aided design	GitHub	Website
	SoundCraft	Audio recording and editing	GitHub	Website
	FigCraft	Interface design and prototyping	GitHub	Website

Develop without network access

Python 3.11+ runs the core tools and tests; GNU Make is optional convenience.
No third-party Python dependencies are needed for the default checks/build.

make help
make doctor
make check
make test
make build
make verify-build
make package
make source
make clean

make setup creates only a local virtual environment. make setup-probe is an
explicit network opt-in for mcp==2.3.0; then make test-sdk checks the real SDK
against a clearly synthetic stdio fixture. It does not run the thirteen Craft apps.
make release orders checks, core tests and reproducible packaging; it does not
claim native acceptance or publish anything. make refresh-releases and
make sign-releases are the network steps the daily workflow runs (the second
needs cosign); make setup-confined installs the five root-confined apps on
this machine. Makefile lists all targets.

Set up the native apps (one command)

Each app's MCP server is its CLI, <app>-cli. Installing the plugin or the
desktop app never provides or registers it, so until then the Skill correctly
reports that the app's native tools aren't connected. One explicit command fixes
that per app, or for all thirteen, on macOS (universal), Linux x86_64 and Windows
x64:

python3 storytold.py setup --app photocraft

python3 storytold.py setup --all --acknowledge-unconfined

Run it from a clone or from the installed plugin directory, which both hosts
place at <home>/plugins/cache/devsolux-storytold/storytold/<version>/ under
~/.codex or ~/.claude; python3 storytold.py doctor prints the exact
command, with the right path, for each app that is missing, and the craft
Skill offers it in chat when a server is not connected. For each app, setup
downloads the archive pinned for your platform in
config/releases.json (the macOS CLI zip, the Linux
tarball or the Windows portable zip), checks it against that manifest and
the release's own SHA256SUMS.txt, takes exactly the one <app>-cli out of
it, checks provenance, stages it beside the active install, runs preflight and
the official MCP SDK probe (initialize, tools/list, one read-only call) against
that staged candidate, and only then promotes it (~/.local/opt/craft/bin, or
%LOCALAPPDATA%\Storytold\craft\bin on Windows), pins the binary hash in a
private lock and registers the server with every host CLI on PATH
(codex mcp add, claude mcp add --scope user). A candidate that fails any
step leaves the previous binary, its pin and the registrations untouched. Then
start a new session.
Re-running setup is idempotent: an app whose installed binary matches its
pin and the manifest is skipped, a registration that already matches is kept.
--dry-run previews; --list shows manifest, installed, pinned and registered
state; --upgrade moves an app whose pin changed to the manifest release;
--replace re-registers a same-name server that points elsewhere and
restores the old entry if the new one cannot be added;
--skip-probe registers without exercising the binary and says so;
--remove unregisters only the user-scope entries setup itself wrote (same
command and arguments, app still pinned) and deletes only a binary whose
bytes match the lock, reporting anything it leaves alone; --remove --dry-run
previews exactly that without changing anything. An upgrade interrupted
between the file replace and the lock rewrite is reconciled by the next run.
Nothing runs unless you invoke it; Python 3.11+ is required.

Provenance. On macOS the binary must be Apple-notarized by the ArtCraft
team. Upstream does not code-sign Linux or Windows builds, so the
daily workflow signs every pinned CLI keyless
with Sigstore cosign under its own GitHub
identity and commits the bundles to
config/signatures.json; on Linux and Windows,
setup verifies that bundle with cosign verify-blob (install cosign first)
before installing, and macOS verifies it too when cosign is present. Until a
release has a bundle, or without cosign, --trust-upstream-sums proceeds on the
manifest and SHA256SUMS.txt alone and says so in the lock.

Daily refresh. The workflow checks every app's latest release each day,
rewrites the manifest, signs new CLIs, rebuilds the plugin, runs the checks and
the real setup on Linux, Windows and macOS runners, and opens one pull request
on bot/releases for review (set the repository variable
STORYTOLD_AUTO_MERGE=true to merge green runs automatically). Users get the
new pins with the next plugin update.

PhotoCraft, VectorCraft, EffectCraft, WordCraft and PdfCraft are confined to the
workspace by native root flags and register by default. The other eight can read and
write anything your user can, so they are installed and registered only with
--acknowledge-unconfined: keep them for non-sensitive work or run them under
OS isolation. Other platforms, air-gapped machines and custom pins use the
manual chain in operations: download, lock, preflight,
probe, configure, register.

Where things live

The plugin directory holds code, docs and the release manifest only; setup
keeps everything it installs outside it, so a plugin update or uninstall can
never delete, downgrade or swap a CLI, and one installed copy serves both
hosts. python3 storytold.py setup --list prints the paths in use.

The complete Unix launch templates are under config/. They are examples only,
not active host configuration. Real config generation chooses .exe on native
Windows and emits concrete validated paths rather than hoping env expansion
works identically across hosts. Machine-specific config stays out of packages.

Safe creative workflow

Inspect → staged copy → native edit → preview → save/export → reopen/verify.

The thirteen app cards describe special pitfalls: VectorCraft
headless selection, LightCraft library locks, PdfCraft explicit saves, DesignCraft
UTF-8 byte offsets, GridCraft typed formulas, FigCraft page-unit coordinates, media
timing and offline warnings.
These are source-derived hints; the connected binary supplies the operative API.

For cross-app work, pass verified files—not another server's in-memory IDs.
PhotoCraft can export a PNG for DesignCraft; DesignCraft can export a PDF for
PdfCraft. Stop at the last verified artifact if a stage fails. No universal batch
transaction, automatic write retry, or hidden fallback is promised.

Four apps have source-documented separate read/write roots; PdfCraft has one
root; eight apps must be treated as OS-user-wide. Neither the Skill, probe
receipts nor MCP config is an OS sandbox. Other host shell/file tools also need
appropriate permissions. See security.

Repository map

Architecture records why the native plan takes precedence
over the older gateway reference and which component owns what.

Devsolux integration; no affiliation or endorsement by the upstream storytold
organization, Anthropic or OpenAI is asserted. Released under the
MIT License. Native apps, SDKs, fonts and media are not bundled and
keep their own licenses; see the license notice.