How to Install Archify for Various IDEs and CLIs: A Complete Setup Guide

Install Archify across Cursor, Codex CLI, Claude Code, and other agents using a single npx skills add tt-a1i/archify -g command, or manually extract the ZIP for Raven and Claude.ai web UI.

Archify is an open-source skill for AI-assisted development environments that generates architecture diagrams from natural language descriptions. Distributed through the tt-a1i/archify repository, this tool ships as a self-contained Node.js runtime with a typed JSON IR and HTML renderer. Whether you are using agent-aware IDEs or command-line interfaces, installing Archify follows a consistent pattern: register the skill globally via npx or manually deploy the ZIP bundle to the host's skill directory.

Universal Installation via npx

The fastest way to install Archify for most supported hosts is through the global skills registry. This method automatically places the necessary files in the correct location for your IDE or CLI to discover and invoke the archify/bin/archify.mjs runtime.

Run the following command to install Archify globally for any supported agent:

npx skills add tt-a1i/archify -g

This command downloads the skill, validates the bundled schema definitions located in archify/schemas/README.md, and registers the binary so hosts can generate, validate, and deliver diagrams on-demand without external services.

IDE-Specific Installation Methods

While the global installer handles most configurations automatically, specific development environments require slightly different approaches depending on their skill discovery mechanisms and sandboxing requirements.

Cursor (Agent-Aware)

For Cursor's agent-aware mode, install the skill globally so it becomes available through the quick-start UI. The skill registers under Cursor's global configuration and exposes the diagram generation capabilities immediately.

npx -y skills add tt-a1i/archify --skill archify \
      --agent cursor --global --copy --yes

Once installed, the Cursor agent can invoke archify/bin/archify.mjs directly when you request architecture diagrams in natural language.

Codex CLI

Codex CLI stores skills under ~/.agents/skills/ (or ~/.config/opencode/skills/ on some systems). Install Archify specifically for Codex using the agent flag:

npx skills add tt-a1i/archify@archify --agent codex

This places the skill in the Codex-specific directory, enabling the codex command to invoke archify as a sub-command for generating typed JSON IR and rendered HTML artifacts.

Claude Code

Claude Code loads skills from ~/.claude/skills/ (or .claude/skills/ within your project). The global installation command automatically detects Claude Code and copies the necessary files to this location, making the skill available automatically when Claude Code runs.

npx skills add tt-a1i/archify -g

Alternatively, for project-local installation only, omit the -g flag to install within the current working directory under .claude/skills/.

opencode

For the Open-Code agent, the skill must reside in ~/.opencode/skills/ (or .opencode/skills/). The standard global install command handles this automatically, but you can explicitly target opencode:

npx skills add tt-a1i/archify --agent opencode --global

Raven (Manual ZIP Installation)

Raven requires manual installation because it does not use the npx skills registry. Download the release archive and extract it to Raven's workspace skills directory:

curl -L -o archify.zip https://github.com/tt-a1i/archify/releases/latest/download/archify.zip
unzip archify.zip -d ~/.raven/workspace/skills/archify

This manual installation supplies the full renderer and validation workflow, allowing Raven to invoke archify/bin/archify.mjs directly for diagram generation.

Claude.ai (Web UI)

For the Claude.ai web interface, you cannot use command-line installation. Instead, upload the ZIP bundle via Settings → Capabilities → Skills. The skill executes in the sandboxed environment where Node.js access is available, enabling the same generation pipeline as desktop clients.

Project-Level and Temporary Usage

If you prefer not to persist the skill globally or want to test Archify before committing to an installation, use the temporary execution mode. This runs the skill without copying files to your system's skill directories:

npx skills use tt-a1i/archify@archify --agent codex

For project-specific knowledge bases without persistent installation, upload the ZIP directly to the project's context. This allows prompt-driven diagram generation without modifying your global skill configuration.

Verifying Your Installation

After installation, verify that Archify is correctly registered by invoking it through your host's natural language interface. For example:

Use archify to draw this login flow: Browser → Web App → API → JWT validation →
Redis session lookup → PostgreSQL fallback.

The host forwards this request to archify/bin/archify.mjs, which:

1. Generates typed JSON IR from your description
2. Validates the structure against the bundled schema in archify/schemas/README.md
3. Delivers a deterministic HTML artifact (or PNG/SVG/WEBM) that can be shared or embedded

You can also test the CLI directly using Node.js:

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss" --json

Key supporting files in the installation include:

• archify/bin/archify.mjs – Main CLI entry point that parses commands and orchestrates the generation pipeline
• archify/bin/preview.mjs – Desktop preview loop for watching JSON sources and rendering verified revisions
• archify/bin/open-artifact.mjs – Helper utility for opening generated HTML in your default browser
• archify/SKILL.md – Contract defining the skill's capabilities and renderer expectations

Summary

• Global install: Use npx skills add tt-a1i/archify -g for Cursor, Codex CLI, Claude Code, and opencode
• Manual install: Extract the ZIP to ~/.raven/workspace/skills/archify for Raven or upload via Claude.ai web UI Settings
• Temporary use: Run npx skills use tt-a1i/archify@archify --agent [name] without persistent installation
• Core runtime: All installations rely on archify/bin/archify.mjs to generate typed JSON IR and deliver HTML artifacts
• Validation: Every diagram passes through the schema validation defined in archify/schemas/README.md before rendering

Frequently Asked Questions

What is the difference between global and project-level installation?

Global installation places the skill in your home directory (e.g., ~/.claude/skills/ or ~/.agents/skills/), making it available across all projects. Project-level installation copies files to a .claude/skills/ or similar directory within your current working directory, limiting availability to that specific repository. Global installation is recommended for tools like Archify that you use frequently across multiple codebases.

Can I use Archify without installing it permanently?

Yes. Use the npx skills use command to execute Archify temporarily without copying files to your skill directories. This is ideal for testing or one-off diagram generation. For Claude.ai web users, you can also upload the ZIP to Project Knowledge as a prompt-driven fallback without persistent installation.

Where does Archify store its validation schemas and renderer?

The validation schemas and HTML renderer are bundled within the skill package itself. The archify/schemas/README.md file contains the JSON schema reference for all diagram types (Architecture, Workflow, Sequence, Data Flow, Lifecycle), while the rendering logic is self-contained within the Node.js runtime. This design ensures Archify operates without external services or internet connectivity after installation.

Why does Raven require manual ZIP installation while other tools use npx?

Raven uses a distinct workspace-based skill discovery mechanism that does not integrate with the npx skills registry. According to the tt-a1i/archify source code, Raven expects skills to exist as complete directory trees under ~/.raven/workspace/skills/. The manual ZIP extraction ensures all binaries, including archify/bin/archify.mjs and supporting assets, are present in the exact structure Raven requires for sandboxed execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}