Integrating Archify with Claude Code, Codex CLI, and opencode: Complete Setup Guide

Archify integrates with Claude Code, Codex CLI, and opencode by unpacking the archify.zip skill bundle into platform-specific directories, enabling automatic diagram generation via the unified bin/archify.mjs CLI.

The tt-a1i/archify repository provides a self-contained, schema-validated diagram generator that functions as an agent skill for popular AI coding assistants. By integrating Archify with Claude Code, Codex CLI, and opencode, developers can generate architecture, sequence, and data-flow diagrams directly from natural language prompts. The skill is distributed as a portable zip file containing renderers, validators, and a unified command-line interface.

Prerequisites and Global Installation

The fastest way to install Archify across all supported platforms is using the skills CLI tool.

npx skills add tt-a1i/archify -g

This command downloads and registers the skill globally, making it available to any compatible agent. Alternatively, you can manually download the archify.zip file from the repository and extract it to platform-specific directories.

Claude Code Integration

Claude Code expects skills to be present under ~/.claude/skills/ (global) or .claude/skills/ (project-local).

Installation Steps

Download the archify.zip file from the repository, then extract it to the appropriate directory:

# Global installation (available to all projects)

unzip archify.zip -d ~/.claude/skills/

# Project-local installation

unzip archify.zip -d ./.claude/skills/

Source: README, lines 102-108

Usage

Once unpacked, Claude Code automatically loads the skill. Invoke it from any prompt:

Use archify to draw an architecture diagram for a web app with React frontend, Node.js API, PostgreSQL and Redis.

Claude executes the embedded bin/archify.mjs renderer, validates the JSON IR against schemas in archify/schemas/, and returns a self-contained HTML diagram.

Codex CLI Integration

Codex CLI searches for skills under ~/.agents/skills/ (global) or .agents/skills/ (project-local).

Directory Setup

# Global install

unzip archify.zip -d ~/.agents/skills/

# Project-local install

unzip archify.zip -d ./.agents/skills/

Source: README, lines 112-118

Running Diagram Commands

Start Codex with the --agent codex flag, then use prompts like:

archify: Draw a data-flow diagram showing event collection, consent filtering, Kafka transport, and a data warehouse.

The CLI processes the request through the same unified renderer used across all platforms, producing HTML/SVG output that can be copied or exported.

opencode Integration

opencode supports flexible skill locations including ~/.config/opencode/skills/, ~/.agents/skills/, or project-local .opencode/skills/.

# Native opencode location

unzip archify.zip -d ~/.config/opencode/skills/

# Reuse Codex location (compatible)

unzip archify.zip -d ~/.agents/skills/

# Project-local

unzip archify.zip -d ./.opencode/skills/

Source: README, lines 120-127

Once installed, any opencode-based agent discovers the skill automatically. Example usage:

archify: Render a lifecycle diagram for a CI/CD pipeline with queued, building, testing, and deployed states.

Core Files and Architecture

The archify.zip bundle contains these critical components that enable integration across all three platforms:

• archify/bin/archify.mjs – Unified CLI implementing render, validate, check, and doctor commands. Processes diagram generation requests and validates JSON IR before rendering.

• archify/SKILL.md – Skill manifest consumed by Claude Code, Codex CLI, and opencode to expose Archify as an agent skill. Defines available commands and parameters for agent discovery.

• archify/renderers/* – Typed renderers supporting architecture, workflow, sequence, data-flow, and lifecycle diagrams. Each renderer outputs platform-agnostic HTML/SVG.

• archify/schemas/*.schema.json – JSON Schema definitions for each diagram type. The validator uses these schemas in bin/archify.mjs to ensure input validity before rendering.

• scripts/check-render-output.mjs – Post-render quality checker executed via the archify check command. Validates HTML/SVG output integrity and detects rendering errors.

Summary

• Integrating Archify with Claude Code, Codex CLI, and opencode requires unpacking archify.zip into platform-specific skill directories (~/.claude/skills/, ~/.agents/skills/, or ~/.config/opencode/skills/).
• The unified bin/archify.mjs CLI handles all diagram generation, validation, and quality checks across every supported platform.
• Global installation via npx skills add tt-a1i/archify -g automates setup for all agents simultaneously.
• Each platform consumes the SKILL.md manifest to expose Archify's capabilities to AI agents.
• Generated diagrams are self-contained HTML files with embedded SVG, theme toggles, and export options.

Frequently Asked Questions

Can I install Archify for multiple agents simultaneously?

Yes. Since Codex CLI and opencode both recognize the ~/.agents/skills/ directory, installing Archify there makes it available to both agents. For Claude Code, you must use ~/.claude/skills/ or maintain separate copies in project-local directories.

What diagram types does Archify support?

According to the source code in archify/renderers/, Archify supports architecture diagrams, workflow diagrams, sequence diagrams, data-flow diagrams, and lifecycle diagrams. Each type has a dedicated renderer and JSON Schema validation in archify/schemas/*.schema.json.

How does Archify validate diagram inputs before rendering?

The bin/archify.mjs CLI automatically validates JSON Intermediate Representation (IR) against type-specific schemas located in archify/schemas/. This prevents rendering errors and ensures diagram consistency across Claude Code, Codex CLI, and opencode integrations.

Is the generated output portable between platforms?

Yes. Archify generates self-contained HTML files with embedded SVG, CSS themes, and JavaScript controls. These files work identically whether generated from Claude Code, Codex CLI, or opencode, and require no external dependencies to view or export.

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