Identity Forge README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Identity Forge listing page.
Identity Forge MCP
Design systems, brand naming, and domain research for coding agents.
For people · For agents · MCP tools · CLI reference · Docs
Free to use. 69 of 79 design kits are free, with all 6 export formats, the CLI, the MCP server, and the API. No account required. Pro unlocks 10 additional kits, 1,000 AI generations/month, and advanced features.
For people
Identity Forge gives a coding agent a complete visual system before it starts
building. Choose a design kit yourself, or let the agent rank the catalog
against your product and the mood you want. Each kit includes typography,
semantic color tokens, layout, motifs, dos and don'ts, and a DESIGN.md the
agent can build from.
The agent can export the kit as CSS, Tailwind v3 or v4, shadcn registry data, DTCG tokens, or JSON, then apply it with conflict protection. Brand naming, domain research, and shareable client projects live in the same workflow.
Public Free kits work without an account. Browse the design kits or read how the agent flow works before installing anything.
Watch it work
The three-minute lifecycle film follows a design system from the first choice through product imagery, an ecommerce rebuild, a later brand update, an older-site rebuild, and team review. The Aubade storefront and Shiftly rebuild are complete one-shot agent builds from real Identity Forge design systems. The Commonkeep review uses synthetic showcase data in the real review experience.
https://github.com/user-attachments/assets/fc3cdba2-4876-46e5-a92a-09ce6d7071ff
Download the full-resolution 1080p WebM.
For agents
Install the local MCP server into the client you use:
Also supported: gemini, opencode, pi. Every client runs the same local
stdio server, and install merges into your existing config rather than
replacing it. Config paths for all seven are in
Install into an agent.
Public Free kits work immediately, without a key. Tell your agent:
Use Identity Forge to pick a theme that fits this product, apply it, and follow the DESIGN.md.
Sign in for persistent projects, saved work, authenticated quota, or Pro access:
No account yet? In the browser, sign up, complete the security check, select
Send verification email, and open its link. Then select
Confirm email and continue, approve the resumed authorization, and the CLI
receives the key automatically.
Use-case discovery
Every use-case lane has two checks. First, the kit's authored audience or bestFor must name that kind of product. Then concrete token measurements such as text contrast, chart-series distinctness, and information density rank the eligible kits. Visual tags help search but do not establish product fit. A high technical score cannot put an unrelated kit into a lane. The per-lane prose justification is switched off catalogue-wide pending re-enrichment, so a score arrives without a sentence explaining it.
list_themes({ use: "data-dashboard" })returns kits authored for dashboards, ordered by their measured dashboard fit.list_themes({ q: "calm fintech dashboard" })runs a synonym-aware ranked search across moods, industries, and use cases.search_themesreturns the whole catalog unranked so the agent can weigh a subtle brief itself.
Use the lane to shortlist and the order to compare. Do not turn the score into an explanation: it ranks technical fit after authored intent, but does not say why the kit suits a particular brief.
For the data lanes there is a better answer than the score. Every kit summary carries a charts block measured on the mode the kit ships in: minDeltaE and cvdMinDeltaE (the closest pair of series colors, plain and under colorblind simulation), distinct, hueFamilies, severityHeadroom (how close any series comes to the destructive, warning and success roles — 0 means a category color IS a status color), sequentialReady, and designed, which is false when the kit defines no chart slots and the five were cycled from its brand roles. Those are measurements, so unlike the fitness score they can be stated to a user as the reason for a recommendation.
Use-case lanes: data-dashboard, admin-internal-tool, saas-marketing, landing-page, ecommerce-store, portfolio, editorial-blog, docs-knowledge-base, mobile-app, business-services, community-social, ai-agent-chat.
The same discovery runs the kit gallery and the HTTP API (GET /api/v1/kits?use=…&q=…, see llms.txt).
Install into an agent
install --client <name> writes the MCP server config for that agent, merging into any existing config:
| Client | --client | Config file |
|---|---|---|
| Claude Code | claude-code | .mcp.json |
| Cursor | cursor | .cursor/mcp.json |
| Codex | codex | ~/.codex/config.toml |
| Gemini CLI | gemini | .gemini/settings.json |
| VS Code / Copilot | vscode | .vscode/mcp.json |
| opencode | opencode | opencode.json |
| Pi | pi | .pi/agent/mcp.json |
All of them run the same local stdio server via npx -y identityforge@latest mcp.
After installation, identityforge doctor --client <name> checks that the client
points at the rolling package and initializes the package's MCP server without
calling the Identity Forge API or spending quota.
Install the agent plugin and skill
The repository also bundles the MCP server with an Agent Skill that tells the agent when
to use Identity Forge, how free and authenticated access differ, and how to guide a human
through Send verification email before the pending browser authorization resumes.
Claude Code:
GitHub Copilot CLI:
Codex and other Agent Skills-compatible clients:
Cursor metadata is included for directory distribution. Until it is listed there, use
the install --client cursor command above to connect the same MCP server.
MCP tools
Once connected, your agent gets 63 tools. Browsing free kits needs no key; scopes are noted where they apply.
Find a design kit
list_themes: browse the catalog as compact summaries. Rank by use-case lane withuse, run ranked search withq, page withoffset, sort byfeatured,popular,recent,name, orfit.search_themes: return the whole catalog unranked, for briefs too subtle to rank against a lane.similar_themes: given a kit slug, find neighbours by palette, tags, and audience.match_palette: given existing brand colors, rank kits by perceptual color distance.
Choose typography outside a kit
A kit already names its heading, body, and mono faces. These two answer the cases where it does not.
search_fonts: browse the Google Fonts catalog by name or category, or passlikewith a family you already have to find faces that resemble it. Metadata only, andlikereads no letterform, so confirm the look before promising it.suggest_font_pairings: the curated heading/body/mono table, or what goes beside one family the user is committed to.
Read and apply one
get_design_md: fetch a kit's DESIGN.md, the full design brief.get_tokens: fetch tokens asdtcg,css,tailwind-v3,tailwind-v4,shadcn-registry, orjson.apply_theme: write DESIGN.md, a tokens file, and anidentityforge.jsonstamp into the project. It refuses rather than overwriting a file it did not write, see below.
What apply writes, and what it will not overwrite
apply_theme (and identityforge apply) writes three files into the target directory:
Identity Forge requests carry one random reference that lasts only for the
current CLI or MCP process. A local apply reports one bounded result: files
written, artifacts already current, a safe conflict refusal, or the stage where it failed. The report
contains counts and classifications, never local paths or error prose. Running
as an MCP server, requests also carry the client name
your editor or agent already sends in the MCP handshake (claude-code,
cursor-vscode, codex), so usage can be attributed to a product rather than to
nothing. None of this includes paths, filenames, prompts, file contents,
repository names, exception text, or a persistent installation identifier. Set
IDENTITYFORGE_TELEMETRY=0 to omit the process reference and local outcome
reports; ordinary API requests still appear in server access logs.
| File | What it is |
|---|---|
DESIGN.md | the design brief the agent builds from |
<slug>.css / .json / .js | the tokens, named for the format you asked for |
identityforge.json | the stamp: which kit was applied, at which version, and a SHA-256 of every file written |
The stamp belongs to your repository, not to the kit. It records what this codebase was built against, which is a fact the server cannot know, so commit it. It is also what makes applying safe: before writing anything, apply compares what is on disk against the hashes in the stamp.
- A file that does not exist gets created.
- A file whose content already matches the kit is left alone.
- A file the last apply wrote, still byte-identical, is updated when the kit has moved.
- A file that is not recorded in the stamp, for example a
DESIGN.mdyou wrote yourself, or one that changed since it was written, is a conflict.
On a conflict the default is to write nothing at all, name every conflicting file, and exit non-zero. Nothing is written until every file is planned, so a failed fetch cannot leave the directory half applied.
--force is destructive and unrecoverable: the current content of the conflicting files is gone, and the report names each one. Preview first, show the person what would change, and let them decide.
What the stamp records, and how a later apply reads it
kit.version has three distinct meanings and they must not be collapsed. A number is the kit's revision. 0 means the kit exists and has no minted version yet. null means the export did not report a version at all, which is a different fact, and reading it as 0 would put a baseline in your repository that was never true. Identity is copied from the export's own front matter; nothing here is inferred.
Re-applying reads that back:
- The version moved — the server's own count says the kit changed. Re-read the brief.
- Same version, different rendered file — the
DESIGN.mdserializer changed, not the kit. No action. - No version on both sides — only the digest is available, and it cannot tell those two cases apart, so it says so rather than guessing.
Because the id is the durable handle, renaming a kit's slug is not reported as "you applied a different kit". A stamp written by a newer CLI than yours is refused rather than half-understood: every file counts as unrecorded, so the apply stops instead of overwriting on a record it cannot fully read.
status: ask the stamp what moved
It takes no kit and no version, because the stamp already holds both. themes diff --from N needs you to know the kit and read the number out of the JSON yourself; apply --preview needs the slug and fetches a whole write plan to answer a read-only question. status reads identityforge.json, asks the server by id, and reports the three movements the stamp implies, separately:
kitMoved— the server's own version count differs. The design changed.documentMoved— the renderedDESIGN.mdbytes differ. A serializer change alone does that to every kit at once, so on its own it is not a reason to touch your code.contractMoved—designMdContractdiffers. The document's shape changed: a section added, renamed, or removed. That is a third question, and neither of the other two answers it.
Each is null rather than false when one side cannot answer, and a note says which side was missing. If the kit did move and both versions are numbers, the same diff themes diff would have printed is included. It also hashes every artifact the stamp recorded against what is on disk, so a DESIGN.md you have since edited by hand shows as modified before you re-apply over it.
It writes nothing and never touches the working tree. Losing your key or hitting a Pro gate degrades it to a local-only report with a note, rather than failing. JSON goes to stdout and the human summary to stderr, so identityforge status | jq .moved works while a person still sees the sentence.
Complementary collections
These answer questions a kit does not. None of them replace the kit.
list_image_directions/get_image_direction: choose and export how the project's imagery should be presented and repeated.list_interface_styles/get_interface_style: choose and export a neutral render grammar for surfaces and hierarchy, applied through a kit.list_page_recipes/get_page_recipe: choose and export how a page should argue its case.
When the user supplies a real product, person, or object, use the approved image as fixed input to a reference-preserving image editor. Shape project-specific presentation routes around it: setting, supporting elements, composition, lighting, surfaces, crop, finish, and variation rules. Keep the source identity exact, compare every result with it at full resolution, and avoid recreating an existing product from text or placing a cutout over a separately generated background. If the current agent cannot perform reference-led editing, hand the source image and exported direction to a product-image workflow. Identity Forge provides the brief; it does not render the images in this flow.
Author kits and brands (kits:write)
create_theme: author a private kit from scratch or by forking a catalog kit with overrides covering tokens, colors, fonts, and facet presets.remix_theme: copy a resolvable kit into a new private kit with overrides applied.update_theme: edit one of your saved kits in place, keeping its slug and publication state so existing consumers follow the change. Overwrites the stored kit, but every save mints a version, so the replaced state stays readable through the version tools below. The slug itself cannot be renamed here, andexpectedUpdatedAtturns a concurrent edit into a 409 instead of a silent overwrite.delete_theme: permanently delete one of your saved kits. Passconfirm: true; a kit still referenced by a brand project is refused with409 kit_in_use, so retire or repoint those references first.create_brand_projectandlist_brand_projects: the container for brand variations and a client share.add_brand_variation: attach a proposal to a project, with a kit plus optional name, domain, label, and notes.update_brand_variation: revise one proposal in place, including repointing it at a different kit. The client sees it on their next view.remove_brand_variation: permanently delete one proposal and its comments. Passconfirm: true; it is not undoable.revoke_brand_share: permanently withdraw a client link. Passconfirm: true; sharing again mints a new token.reorder_brand_variations: set the order the client meets the directions in. Must list every variation exactly once.share_brand_project: create or rotate a read-only/p/<token>client share link, optionally password protected.list_client_comments(kits:read): read what the client wrote on each variation. The return leg of the share loop.
Compose the other axes onto a brand
A brand is a design kit plus an image direction, an interface style, and any number of page recipes. Those references live on the PROJECT, not the kit, so swapping the kit leaves them alone.
get_brand_layers(kits:read): what a brand is composed of, with both revision numbers on every reference anddriftpresent only where the record has moved since it was pinned.meta.driftedcounts them, andlinks.previewis the composition rendered as an image. Reads nothing into the brand: no version is minted and no pin moves.add_brand_layer: compose one record onto the brand, recording the revision it is at now so a later read can report a change rather than apply it silently. One tool for all three axes viaaxis. Image direction and interface style hold one each; a second is refused with 409 unless you passreplace: true, which is also how you accept a drifted revision.remove_brand_layer: take one off. Passconfirm: true; it names the record rather than the axis, so a stale view cannot clear a layer it never saw, and repeating it is a no-op.export_brand(kits:read): the brand as ONE document, ready to build from — the kit'sDESIGN.mdwith every pinned layer written into it, under the precedence rule that decides which wins when they disagree (the kit owns identity, a layer owns application). Use it instead of merging the kit and each layer yourself. A layer the key cannot open is named with its page and an upgrade path rather than dropped; a brand with no chosen kit answers 409 instead of returning a placeholder nobody picked.
Describe the product once, then get proposals grounded in it
get_project_context/set_project_context: store what the product is — what it does, who it is for, its constraints, what has been ruled out, its screens, its stack — on a brand project. Every later proposal is grounded in it, including in a session that never saw the description.recommend_kits({projectId}): candidates for that product, each carrying the kit's own evidence and its judged fitness for the surfaces the product actually has. With Pro and akits:writekey you also get a model ranking with a reason per candidate;meta.depthisrankedorcandidates.
Two things that surprise people:
set_project_contextREPLACES. The endpoint isPUT, notPATCH, so a field you omit is deleted rather than kept. That is deliberate — a merging update would let you drop a surface from the list and silently keep the old one — but it means you read withget_project_contextfirst and send the whole object back with your edit applied.recommend_kitscosts 3 quota units and needs a key, wherelist_themescosts 1 and every other discovery route works anonymously. The reasoning is in the route's own docstring: it takes a free-text body rather than query parameters, and it is the one route that can grow into a metered model call. Writing a context needskits:write; reading one needs onlykits:read.
Has it changed since I built? (read-only)
-
list_kit_versions,get_kit_version,diff_kit_versions: a kit's version timeline, one past snapshot in full, and what moved between two versions.diff_kit_versions({slug, from})with no upper bound compares against the current version, which is the question a repo with anidentityforge.jsonactually has. -
list_brand_project_versions,get_brand_project_version,diff_brand_project_versions: the same three for a brand project, owner-scoped. -
list_kit_history,get_kit_history_event: the same kit's ledger, which is a wider record than its version timeline.kit_history_eventscarries three event types — created, saved, and applied to a brand — and only the first two mint a version, so an apply appears in the ledger and nowhere else. Ask the ledger whether a kit was ever actually used; ask the timeline what its tokens were. It pages by an opaque cursor rather than a version number, because an event has no ordinal to page below. Share: pause or withdraw.update-shareis the reversible one and almost always the right one —--disablepauses the link, the token is untouched, and a URL already with the client works again the moment you resume.revoke-shareis permanent: the/p/<token>URL stops resolving wherever it was pasted, including in an email already sent, and sharing again mints a new token and deliberately never the old one. It refuses without--yes. -
whoami: plan, granted and missing scopes, remaining quota, AI credits, and saved-kit slots. Free, and never refused for being over quota, so it still answers after a 429.
None of these writes anything. Restoring an old state is an update_theme call you make deliberately.
What actually has history. Saved kits and managed catalog kits accumulate versions. A static catalog fallback stays at version 0 until it is promoted into the managed catalog. The separate kit history ledger remains owner-only and records creation, saves, and applications to a brand. On brand projects the whole brand is recorded: name and domain, fonts, pinned layers, project context, and the variations, including a reorder. What is deliberately not recorded is sharing, because who may see a brand is not what the brand is.
What a Pro gate does to them. For a kit you are not entitled to, the timeline still lists versions but the author's free-text note is null, and a diff returns each change marked redacted: true with its path and CSS variable but no before or after, plus a redactedChanges count. get_kit_version returns the whole payload, so it answers 403 instead.
Name a brand (naming:read / naming:write)
list_naming_recipes: the full naming strategy catalog.list_naming_projectsandcreate_naming_project: reuse or create a durable board.generate_names: generate with Identity Forge's own model. Spends AI credits only when unique candidates persist.add_name_candidates: persist names from the active agent, an authorized offline process, or manual research, using stable caller UUIDs. Spends no credits.list_name_candidates: read the kanban board with provenance and evidence.list_name_generations: audit model, prompt, request, and credit provenance.move_name_candidatesandrank_name_candidates: atomically review, shortlist, rank, and select.get_naming_research_context: read the brief, board, evidence, capabilities, and small-task handoff contract, without server ranking.search_name_evidence: run bounded model-authored searches through self-hosted SearXNG and return evidence without verdicts. One account-wide monthly unit per query.check_domains: DNS plus distinct RDAP, registrar, and optional self-hosted SERP evidence. Basic research costs one unit per unique domain; SERP adds one. Absent DNS records only mean a domain might be available.assess_domain_acquisition: state whether the goal is a new registration, an aftermarket purchase, or either. It reports registrar registration evidence and bounded public landing-page evidence separately, including literal sale, marketplace, reserved-page, and visible-price signals. It never validates the seller or guarantees purchase. Aftermarket evidence adds one unit per unique domain; an exact successful repeat within ten minutes costs zero.
Trademark screening remains a separate manual step through the official registers for each relevant jurisdiction. Record the query, classes, source URL, result wording, and date. This is preliminary research, not legal clearance.
Build a brand and share it with a client
The kits:write tools let an agent build a whole brand package end to end:
create_themeorremix_themeto compose four or five contrasting directions, either forking a catalog kit and overriding colors, fonts, and facets, or authoring from scratch.create_brand_project, one project per client brief.add_brand_variationto attach each direction with a brand name, domain, and label.share_brand_projectto hand the client a/p/<token>link, optionally password protected, where they cycle the variations and comment.list_client_commentsto read what came back, thenupdate_theme,update_brand_variation,remove_brand_variation, andreorder_brand_variationsto revise the same board rather than starting a second one.
Everything an agent creates it can also revise. The write tools change live, client-visible state; destructive tools require confirm: true, so read the feedback before acting on it.
New keys carry kits:write by default. A key minted before that scope existed will 403 until you re-run identityforge login or create a new scoped key.
The MCP server also ships connect-time instructions describing this workflow, so a connected agent knows how to go from intent to an applied kit without being told the steps.
How an agent picks a kit
When you ask your agent for a look and feel, it should:
- Gather intent: what the product is, who it is for, and the mood you want, for example "fintech dashboard for SMBs, calm and trustworthy".
- Find candidates:
list_themes({ use })when the build target maps to a use-case lane,list_themes({ q })for ranked search, orsearch_themesto rank the whole catalog against a subtle brief. If you already have brand colors,match_palette({ colors })finds the closest kits. - Review: each result is a compact summary with name, tags, a font and color glimpse, tier, and judged fitness.
similar_themes(slug)offers neighbours, andget_design_md(slug)reads the full brief before committing. - Apply:
apply_theme(slug), optionally with atokensFormatmatching your stack, writesDESIGN.md, a tokens file, and theidentityforge.jsonstamp into the project. If the project already has files it did not write, it shows you the conflict instead of overwriting them. - Implement: follow
DESIGN.mdand wire the tokens into your styling layer, whether CSS variables, a Tailwind@themeblock, or shadcn.
The more concrete your description, the better the match.
Ids and slugs
Every kit has an opaque id and a slug, and either one addresses it directly, so once you have a kit you can skip discovery. They differ in durability:
- The id never changes. It is minted once, is never reassigned, and always resolves to the same kit.
- The slug is a public handle its owner can rename. A retired slug keeps resolving through an alias, so a rename alone does not break you. But a different kit can later claim that freed slug, and the live kit wins, so a stored slug can quietly start resolving to a different kit rather than failing loudly.
Pass the slug when a person typed it. Store the id for anything your agent keeps: a config value, a version stamp, a choice it repeats in a later session. list_themes prints both.
Image directions, interface styles, and page recipes carry ids too, and the same advice applies more strongly: they have no alias table, so a renamed slug there simply stops resolving.
CLI commands
Guarding a naming write. naming move and naming rank take
--expected-updated-at, so a candidate that changed since you read it answers 409 instead of
being silently overwritten. Take the marker from naming candidates, pass it back byte for byte,
and never parse it: it looks like a timestamp and is compared as an opaque string.
The marker guards one candidate, so passing it with several ids is refused before anything is
sent rather than applied to all of them: each row has its own marker, and spreading one across a
batch would guard the wrong rows. Move the guarded candidate on its own. This matters most for
--status selected, which also sets the project's chosen brand name.
--evidence is different: it is not row-specific, so it applies to every candidate in the batch.
It takes a path or - for stdin, and a file that will not parse is refused rather than sent as an
empty object, which would record "no evidence" as though it were the considered answer.
Editing a saved kit without clobbering a concurrent edit
PATCH accepts an expectedUpdatedAt marker and answers 409 rather than overwriting a kit that moved since you read it. Read the current marker with themes get --marker:
--kit is deep merged over the stored kit, so a file holding only what changed is enough. Leave slug as it is: it is the kit's public handle, and a payload carrying a different one is rejected with 400 slug_rename_unsupported rather than quietly ignored. Omitting --expected-updated-at still works and still writes; it just overwrites whatever is stored, including an edit someone made since your read, so the command says so on stderr.
The marker is opaque. Echo it back byte for byte and never parse it. It crosses the wire as a raw Postgres timestamp rather than ISO-8601, and the guard compares strings, so a client that parses it into a Date and serialises it back never matches and gets 409 forever. Parsing also drops the microseconds, so a comparison that normalises both sides can falsely match and let a genuinely stale write through. A curated catalog kit has no marker, because it has no row and cannot be edited.
Authentication
Commands authenticate with an Identity Forge API key (ifk_…). login stores it in ~/.identityforge/config.json with mode 600. You can also set it per shell:
Free kits and naming-recipe discovery work without a key. Sign in to keep persistent projects and saved work under an authenticated quota. Owned naming projects and domain research use naming:read, generation and board edits use naming:write, reading design systems uses kits:read, and creating or remixing kits plus building shareable brand projects uses kits:write. API calls count against one account-wide monthly API quota shared by all keys, while generation separately spends AI credits for successfully persisted unique candidates. Manage keys at https://identityforge.io/account/api-keys.
After a successful local apply, the client sends one metadata-only completion request so aggregate builds can be counted. It includes the kit identifier plus the client name and version already present in every API request. It never sends the repository path or file contents, never changes the apply result, and can be disabled with IDENTITYFORGE_TELEMETRY=0.
Existing design-only keys are not silently upgraded. If a key reports that it is missing naming:read or naming:write, create a scoped key or run browser login again.
Docker
The MCP server also runs as a container over stdio:
The image contains no kit payloads. The key is optional: without one, the server still starts and fetches published Free kits from the Identity Forge platform API. Pro kits, saved work, and writes require an account key.
Links
- Source and agent plugin: the public CLI and MCP implementation.
- Kit gallery: browse every kit with live previews, authored-intent use-case filters, and search.
- For agents: the full agent integration story.
- API manifest and llms.txt.
- Official MCP Registry record and Glama listing with independent build and security analysis.
If Identity Forge earns a place in your workflow, a GitHub star helps other builders find it.
License
MIT