How to Integrate Archify with Cursor Claude Code Codex CLI: A Complete Developer Guide

You can integrate Archify with Cursor Claude Code Codex CLI by exporting architecture JSON from Archify and feeding it to the Cursor CLI via the --input flag, enabling a design-first workflow where Claude generates code from your visual architecture diagrams.

Archify is a lightweight, browser-based tool that lets you describe software architecture in declarative JSON and visualize it as interactive diagrams. The Cursor Claude Code Codex CLI provides command-line access to Claude-powered code generation. Together, they create a seamless bridge between visual system design and AI-assisted implementation.

This guide walks you through the exact integration steps using source files from the tt-a1i/archify repository.

How the Archify-to-Cursor Integration Works

Both tools communicate through JSON payloads—no SDKs or complex adapters required. The workflow follows a simple export-generate-reimport loop:

1. Export your architecture from Archify as JSON
2. Feed that JSON to Cursor CLI with a code generation prompt
3. Consume Claude's output in your project
4. Optionally re-import updated code back into Archify for visualization

The core integration relies on two glue components: Archify's existing model serialization (found in archify/scripts/run-tests.mjs) and a custom wrapper script you create to invoke the Cursor CLI.

Exporting Architecture JSON from Archify

Archify stores architecture definitions in a structured JSON format. The repository's archify/scripts/run-tests.mjs demonstrates how the internal model is built and serialized programmatically.

Reference Architecture File

The example architecture at examples/archify-repo.architecture.json shows the expected schema:

{
  "nodes": [
    { "id": "api-gateway", "type": "service", "label": "API Gateway" },
    { "id": "user-service", "type": "service", "label": "User Service" }
  ],
  "edges": [
    { "from": "api-gateway", "to": "user-service", "protocol": "HTTP/REST" }
  ]
}

Export Script Using run-tests.mjs

Create a small Node.js helper that leverages Archify's existing infrastructure:

// save-archify.js - Export architecture to JSON for Cursor consumption
import { readFileSync, writeFileSync } from 'fs';
import { generateArchitecture } from './archify/scripts/run-tests.mjs';

// Generate architecture object using Archify's internal model builder
const architecture = generateArchitecture();

// Serialize with readable formatting for Claude parsing
writeFileSync('archify-model.json', JSON.stringify(architecture, null, 2));
console.log('✓ Architecture exported to archify-model.json');

Key source reference: The generateArchitecture function in archify/scripts/run-tests.mjs is the canonical entry point for model serialization. This script ships with the repository and handles the internal graph-to-JSON conversion.

Invoking Cursor Claude Code Codex CLI

With the architecture JSON exported, pass it to Claude via the Cursor CLI's --input flag. This command pattern feeds your system design directly into the model's context window.

Basic CLI Invocation

# Install Cursor CLI if needed: npm i -g @cursor/cli

cursor codex run \
  --input archify-model.json \
  --prompt "Given this architecture, generate TypeScript interfaces for all services and their request/response shapes." \
  --output generated/

What happens:

• cursor codex run reads and parses archify-model.json
• Claude receives both the structured architecture and your natural-language prompt
• Generated code files are written to the generated/ directory

Advanced Prompt Patterns

Prompt Purpose	Example
Generate API contracts	"Create OpenAPI 3.0 specs for all HTTP services defined in this architecture"
Scaffold microservices	"Generate Docker Compose configuration and service boilerplates matching this topology"
Data modeling	"Design SQL DDL for the entities and relationships shown in nodes and edges"
Test generation	"Write integration tests that verify connectivity between all edge-defined service pairs"

Closing the Loop: Re-import Generated Code

To maintain synchronization between your architecture diagram and implementation, parse Claude's output and update the Archify model.

Re-import Script Template

// update-archify.js - Sync generated code back to visualization
import { readFileSync, writeFileSync } from 'fs';
import { enrichArchitecture } from './archify/scripts/run-tests.mjs';

// Load current architecture
const arch = JSON.parse(readFileSync('archify-model.json', 'utf-8'));

// Read generated artefacts (example: TypeScript service definitions)
const generatedCode = readFileSync('generated/services.ts', 'utf-8');

// Custom enrichment: parse code and update model
const updatedArch = enrichArchitecture(arch, {
  sourceFiles: [generatedCode],
  extractEntities: true  // Your custom logic here
});

// Persist for re-visualization
writeFileSync('archify-updated.json', JSON.stringify(updatedArch, null, 2));
console.log('↻ Architecture updated with generated services');

Note: The enrichArchitecture helper requires custom implementation based on your code generation targets. It parses generated files and maps discovered entities back to Archify's node/edge schema.

Key Source Files for Integration

File	Purpose	Integration Role
archify/package.json	ESM runtime dependencies	Verify Node.js compatibility for scripts
archify/scripts/run-tests.mjs	Model generation and serialization	Primary export mechanism for architecture JSON
examples/archify-repo.architecture.json	Sample architecture schema	Reference for JSON structure expected by Cursor
examples/web-app.html	Interactive diagram renderer	Visual feedback after re-import
scripts/build-zip.sh	Distribution packaging	CI/CD embedding of Archify
docs/README_EN.md	Human-readable documentation	Installation and setup guidance

CI/CD Integration Pattern

For automated pipelines, chain the three phases in a shell script:

#!/bin/bash
set -e

# Phase 1: Export

node scripts/save-archify.js

# Phase 2: Generate with Cursor

cursor codex run \
  --input archify-model.json \
  --prompt "Generate complete service implementations from this architecture" \
  --output src/generated/

# Phase 3: Validate and optionally re-import

if [ -d "src/generated/" ]; then
  node scripts/update-archify.js
  echo "Architecture synchronized"
fi

Summary

• Archify serves as the source-of-truth for system architecture through its JSON schema
• Cursor Claude Code Codex CLI consumes that truth via --input to generate implementation artefacts
• The run-tests.mjs script in the Archify repository provides the canonical export mechanism
• JSON is the only contract required—no additional SDKs or API wrappers
• The workflow supports bidirectional synchronization: design → code → updated visualization

Frequently Asked Questions

Can I integrate Archify with other AI coding assistants?

Yes. Any tool that accepts JSON input via file or stdin can consume Archify exports. The archify-model.json format is self-documenting and tooling-agnostic. Adapt the Cursor CLI invocation to your preferred assistant's input mechanism.

Does the Cursor CLI require specific JSON formatting?

The Cursor CLI accepts standard JSON without strict schema enforcement. Claude parses the structure contextually based on your prompt. For best results, include a brief schema description in your prompt when working with complex nested architectures.

Where is the actual diagram rendering code in Archify?

The interactive visualization lives in examples/web-app.html, which loads the JSON model and renders it using D3.js-style force-directed graphs. This file demonstrates how Archify's JSON schema maps to visual elements—useful if you're building custom importers.

Is there an official Archify npm package for programmatic use?

Not currently. The integration relies on importing directly from archify/scripts/run-tests.mjs as shown above. The repository uses pure ESM with Node.js 18+; verify your runtime matches the engines specified in archify/package.json.

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