archify-cli analyzes your repository and gives AI assistants the grounded context they need to write architecture docs.

What It Does

Archify is built for repositories where you want architecture output based on actual code and docs instead of guesswork.

It can:

• scan the repository and build a grounded knowledge base in .archify/
• detect when existing analysis is still fresh and reuse it
• regenerate analysis only when the repository changes
• generate doc-specific packets and guides for assistant-driven writing
• write final root-level documents for supported doc types

Who It Is For

Use Archify if you want to:

• understand an unfamiliar codebase faster
• generate architecture documentation from real repository evidence
• give Codex or Claude Code a grounded context pack before asking it to write docs
• keep architecture outputs refreshable as the codebase evolves

Requirements

• Node.js >= 20
• Python >= 3.11
• an AI assistant workflow using Codex or Claude Code

Python is required because the analysis engine shipped inside the package is implemented in Python.

Quick Start

From the repository root:

npx archify-cli init

Then tell your assistant:

Use Archify on this repo

Typical flow:

1. Run npx archify-cli init once.
2. Ask your assistant to use Archify on the repo.
3. Archify checks status and decides whether it should analyze, generate, write, or reuse existing artifacts.

Install Options

Run directly with npx:

npx archify-cli init

Or install it in a project:

npm i -D archify-cli

Then run:

npx archify-cli status

Commands

| Command | Purpose | | --- | --- | | npx archify-cli init | Set up Archify in the current repository | | npx archify-cli status [--doc-type <type>] | Show setup state, artifact freshness, and the next recommended action | | npx archify-cli analyze . | Build or refresh grounded repository knowledge in .archify/ | | npx archify-cli generate . [--doc-type <type>] | Build the synthesis packet and guide for the selected document type | | npx archify-cli write . [--doc-type <type>] | Write the selected root-level document from generated synthesis artifacts | | npx archify-cli clean | Remove generated artifacts from .archify/ |

What Gets Created

Archify adds:

• archify.config.json for project configuration
• .archifyignore for scan exclusions
• project skill files for Codex or Claude Code installs
• .archify/ for analysis, synthesis, and guide artifacts

Core artifacts include:

| File | Purpose | | --- | --- | | archify.config.json | Project-level Archify configuration | | .archifyignore | Ignore rules for repository scanning | | .archify/manifest.json | Analysis state and freshness metadata | | .archify/graph.json | Repository graph output | | .archify/architecture-context.json | Grounded architecture context | | .archify/docs/<docType>/packet.json | Doc-scoped synthesis packet used to author the selected root document | | .archify/docs/<docType>/guide.json | Section-by-section guide for generating the selected root document | | .archify/docs/<docType>/brief.md | Human-readable synthesis brief | | .archify/docs/<docType>/guide.md | Human-readable guide brief |

Available Documents

Archify supports these document types:

| --doc-type value | Output file | | --- | --- | | archify | archify.md | | tech_stack | TECH_STACK.md | | api_design | API_DESIGN.md | | data_model | DATA_MODEL.md | | conventions | CONVENTIONS.md | | glossary | GLOSSARY.md | | flows | FLOWS.md | | test_cases | TEST_CASES.md |

If --doc-type is omitted, Archify defaults to archify and writes archify.md.

Examples:

npx archify-cli status --doc-type tech_stack
npx archify-cli generate . --doc-type api_design
npx archify-cli write . --doc-type flows

How The Analysis Works

Archify analyzes repository structure and supporting docs, including:

• source files
• routes and entrypoints
• dependencies
• database and migration files
• README and supporting architecture documents

The workflow is guide-driven:

• analyze produces grounded .archify artifacts
• generate produces a doc-scoped synthesis packet and guide
• write materializes the selected root document from those artifacts
• installed assistant skills read the selected packet and guide before drafting the final document

Grounded .archify/ artifacts remain the primary source of confirmed facts.

Notes

• init is the main setup command.
• status is the main inspection command.
• analyze, generate, and write are available for manual workflows, but the installed skill is designed to run them when needed.