Character Foundry provides open-source tools for reading, editing, preserving and sharing AI character cards. The SDK supplies format and protocol primitives; applications own their storage, authentication and user experience.
Install the bundled public package:
npm install @character-foundry/character-foundryImport the functionality you need through its subpaths:
import { parseCard } from '@character-foundry/character-foundry/loader';
import { exportCard } from '@character-foundry/character-foundry/exporter';
import { CCv3DataSchema } from '@character-foundry/character-foundry/schemas';The SDK also provides /png, /charx, /voxta, /lorebook, /normalizer,
/tokenizers, /media, /zip and /integrations, among other documented exports.
Its internal workspace packages are bundled into the public SDK, not installed
as separate @character-foundry/loader or @character-foundry/exporter packages.
See the SDK README
and package documentation
for examples, runtime requirements and format-specific limits. The separately
published CLI
is available as @character-foundry/cli.
The ecosystem spans separate repositories; the SDK itself is a package monorepo. Follow each application's README for its setup and current status. Character Unity is the integrated application for the library, Archive, editing and sharing; the original standalone projects remain available below.
| Project | Purpose |
|---|---|
| Character Foundry SDK | TypeScript format parsing, export, validation, binary utilities and opt-in protocol primitives. |
| Character Unity | Native library, in-place Archive search, editing, forks and sharing; local, account and browser-only profiles. |
| Character Architect | Self-hostable visual character-card editing and format conversion. |
| Character Archive | Character-card ingestion, original-file preservation and collection search. |
| Character Federation | CardsHub sharing, discovery and federation. |
The SDK reads and writes CCv2/CCv3 PNG and JSON, CharX and Voxta packages, and supports standalone lorebooks. Conversion capabilities differ by format; use the exporter's loss reporting rather than assume every conversion is lossless.
RisuAI CharX packages can contain many assets, authored descriptor metadata and an
opaque module.risum. Preserving these bytes does not mean executing or translating
their scripts. See the CharX documentation
for supported reader/writer behavior.
The public feat/unity-identity branch
adds versioned card content identity, explicit revision lineage and publication
sanitization through /identity, plus signed publication and fork transport through
/sync. Existing loader/normalizer hash APIs keep their meanings. These are SDK
contracts for applications to integrate, not a hosted application or deployment.
The branch's identity bounds accommodate large RisuAI cards: up to 8,192 asset digest bindings, 2,000,000 JSON nodes and 32 Mi UTF-16 code units of canonical output, with a maximum depth of 64. These are identity resource limits, not universal parser or application upload limits. Asset digests must come from verified bytes; a remote asset URL alone is not an immutable identity.
Development contracts:
- Card identity and lineage
- Signed HTTP transport
- Publication reads
- Publish/fork commands
- Verified remote fork submissions
- Descriptor-preserving CharX export
These additions are unreleased. A feature-branch push does not publish an npm release; do not assume the install command above includes these development APIs.
- Preserve accepted original files; transformations are explicit operations.
- Report unsupported conversions and content loss instead of silently claiming preservation.
- Keep application storage, access control and peer trust with the application.
Contributions and bug reports are welcome; consult the relevant project's guidelines and issue tracker. Format work follows the Character Card V3 specification.