@withfudge/design

Fudge CLI

Local developer CLI and stdio MCP server for querying the Fudge Prolog runtime.

Install

npm install -g @withfudge/design

Then authenticate, install the local MCP server, and check the setup:

fudge login
fudge install --all --skill
fudge doctor

Manual MCP config uses this stdio command:

npx -y @withfudge/design mcp

During development from this repository, install dependencies locally and run commands with tsx:

npm install --prefix fudge/cli
npx --prefix fudge/cli tsx fudge/cli/src/cli.ts --help

Install MCP And Skill Routing

fudge install writes only the fudge MCP server entry and preserves unrelated client config. When a target config already exists, the CLI writes a timestamped sibling backup such as config.json.fudge-backup-... before calling the installer library. Use --no-backup to skip that backup.

fudge install --client codex
fudge install --client opencode
fudge install --all
fudge install --all --include-undetected
fudge install --dry-run --json
fudge install --list-clients
fudge install --client codex --no-backup

The first supported matrix is Codex, OpenCode, Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, and Zed. Codex and OpenCode are the reference clients covered by config-level tests.

Config upsert is library-backed for the full matrix. Doctor verification is strongest for Codex and OpenCode today: those paths are covered by local config tests plus packed-package stdio handshake tests. Other clients are installable through the shared installer library, but should be manually opened once after install to verify the client loaded the fudge MCP entry.

Use --skill to install Fudge routing instructions into the local agents skill directory:

fudge install --skill
fudge install --skill-only

The default skill target is ~/.agents/skills/fudge-search. Override it with --skills-dir DIR or $FUDGE_SKILLS_DIR.

The bundled fudge-search skill tells agents to use local Fudge MCP for saved pins, bookmarks, design inspiration, fonts, colors, palettes, domains, screenshots, and visual references. It also tells agents to read fudge://release/skill.md before querying unfamiliar predicates and to avoid legacy direct tools such as search_design_inspiration, get_pin_details, and display_pin.

Routing support by client:

• Native skills: install fudge-search with fudge install --skill for agents that read ~/.agents/skills.
• AGENTS.md or instruction-file clients: copy the rules from skills/fudge-search/SKILL.md into the project or client instruction file.
• MCP-only clients: install the MCP server and use fudge://release/skill.md, fudge://release/predicates.json, and the query_fudge_release prompt for query guidance.

To uninstall manually, remove only the fudge MCP server entry from the target client config and remove ~/.agents/skills/fudge-search if you installed the routing skill. Do not delete unrelated MCP entries or provider settings.

MCP

Start the stdio MCP server:

npx -y @withfudge/design mcp

Example MCP client command config:

{
  "command": "npx",
  "args": [
    "-y",
    "@withfudge/design",
    "mcp"
  ]
}

The MCP server exposes one tool: query_fudge.

query_fudge runs raw Prolog through a yield-aware SWI query loop. It returns raw bindings, answer count, truncation metadata, and timing. It does not summarize results, infer Prolog semantics, build answer programs, or render markdown.

It also exposes MCP-native release context resources:

fudge://release/info
fudge://release/skill.md
fudge://release/predicates.json
fudge://release/skill-metadata.json

Agents should read fudge://release/skill.md or fudge://release/predicates.json before querying unfamiliar release predicates. The server also exposes the query_fudge_release prompt, which guides clients through that flow.

Auth

fudge status reads the local session from macOS Keychain during normal local use. If Keychain is unavailable, or when $FUDGE_HOME is set for development/tests, it falls back to ~/.fudge/session.json or $FUDGE_HOME/session.json with restrictive file permissions.

fudge login starts a browser-loopback OAuth flow. The CLI opens the hosted Fudge auth URL, listens on 127.0.0.1, accepts a one-time code from the browser redirect, exchanges it for a local session, and stores that session locally.

fudge login

Doctor

fudge doctor --json
fudge doctor --client codex --json
fudge doctor --client opencode --local --cwd .

doctor checks package and Node versions, auth status, release availability, local runtime warmup, stdio MCP handshake, release MCP resources, routing skill status, and installed MCP config status for the requested clients.

Query

fudge query 'pin_title(Pin, Title).' --limit 1

Useful development flags:

FUDGE_LOAD_RELEASE=0
FUDGE_REFRESH_USER_MEMORY=0

Or disable user-memory refresh for one command:

fudge query 'member(X, [a,b]).' --limit 2 --no-refresh-user-memory

limit caps returned bindings and closes finite enumeration after the first extra answer proves truncation. Execution timeout remains the runaway protection.

text_vector/2 uses a persistent local cache for deterministic text embeddings. Cache entries are keyed by release id, embedding vector-space id, dimensions, and normalized text, and are stored under ~/.fudge/cache/text-vectors or $FUDGE_HOME/cache/text-vectors.

Error Contract

CLI JSON failures and MCP structuredContent errors use the same shape:

{
  "error": {
    "code": "login_required",
    "message": "Login required",
    "recoverable": true,
    "actor": "user",
    "action": {
      "type": "run_command",
      "command": "fudge login",
      "label": "Log in to Fudge"
    }
  }
}

actor tells the caller who can recover:

• agent: retry once or adjust the local call.
• user: stop retrying and ask the user to act.
• system: local setup, environment, or service state must change.
• none: no recovery path is available.

Auth gates point to fudge login. Billing and plan gates point to https://design.withfudge.com/.

Recipes

Recipe files are plain .pl files read as opaque Prolog source.

Project recipes:

.fudge/recipes/*.pl

Global recipes:

~/.fudge/recipes/*.pl

Project recipes shadow global recipes with the same filename.

fudge recipe list
fudge recipe run colors --query 'recipe_color(X).' --limit 2

Follow-Ups

The current user-memory refresh builds saved/1, collection/1, and collection_item/2 facts client-side from authenticated JSON endpoints. A cleaner hosted endpoint, /personal/prolog-context, should eventually return opaque Prolog user-memory source directly.