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

> Integrate Archify with Cursor, Claude Code, and Codex CLI. Export architecture JSON and use the Cursor CLI for a design-first workflow. Claude generates code from your diagrams.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-17

---

**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`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) shows the expected schema:

```json
{
  "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:

```javascript
// 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

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) | Sample architecture schema | Reference for JSON structure expected by Cursor |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) | Interactive diagram renderer | Visual feedback after re-import |
| [`scripts/build-zip.sh`](https://github.com/tt-a1i/archify/blob/main/scripts/build-zip.sh) | Distribution packaging | CI/CD embedding of Archify |
| [`docs/README_EN.md`](https://github.com/tt-a1i/archify/blob/main/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:

```bash
#!/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/archify/package.json).