How to Use Archify with Codex on a Real Codebase

Quick answer: open Codex in the repository you want to understand and ask for the diagram in plain English. That is the entire setup.

Use the Archify skill (https://github.com/tt-a1i/archify) to create a
high-level architecture diagram of this repository. Validate it and deliver
the result as architecture.html.

An interactive architecture diagram generated by Archify, open beside the
repository that produced it and the Codex session that created
it

What comes back: a self-contained architecture.html you can pan, zoom, and search. This one maps a real Electron, Node.js, and Python application, and is open in StashBase, the local workspace I build.

The link is doing real work. Without it, Codex has no way to know which skill “Archify” refers to; with it, the prompt is self-sufficient. Codex ships with a skill installer, so if Archify is not on the machine yet it fetches the skill from that repository before running it. There is no install step to do first.

Prefer to install Archify yourself? Here are the manual commands

Nothing below is required — this is the same installation Codex performs on its own, for readers who want it done before the first prompt or pinned to a specific project.

Install globally for Codex

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

Install only in the current repository

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

Try it once without a permanent installation

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

You can also drive the built-in installer directly instead of letting Codex decide: $skill-installer Install the Archify skill from https://github.com/tt-a1i/archify. OpenAI's Skills documentation covers $skill-installer and repository installs; Archify's Codex quick start is the source of the commands above.

Two follow-up prompts for a sharper diagram

Give the diagram a size and a question. A component budget is what stops the agent drawing one box per directory.

$archify Create a high-level runtime architecture diagram of this
repository. Show 8–12 core components, the primary runtime and data
flows, and the external dependencies. Base it on repository evidence,
not assumptions. Validate it and deliver it as architecture.html.

Then check it instead of trusting it. A generated map is a claim about the system, not a fact about it.

$archify Explain why the indexing layer is modeled separately, cite
the repository evidence, and correct the diagram if that boundary is
wrong.

Where it runs, and what breaks

Where you run Codex	Archify	Opening the diagram
Terminal (Codex CLI)	Works	In a browser
VS Code or another IDE extension	Works	In a browser, not the editor
ChatGPT desktop app	Works	In a browser
Codex on the web (cloud tasks)	Does not load	—

In a web cloud task, nothing happens at all. OpenAI documents standalone skills as available in the desktop app, the CLI, and the IDE extension; only skills bundled into a plugin reach the web. If the prompt seems ignored there, the environment is wrong, not the prompt.

In VS Code and other IDE extensions, the work is invisible. The agent’s commands do not run in your integrated terminal, so a step like “open the generated HTML” has no visible effect, and clicking the file in the tree shows its source rather than the diagram. The file is fine — open it in a browser.

In the terminal, three things go wrong often enough to name. The first run pauses for approval, because Codex’s sandbox has network access off by default and the install needs it: that approval request is the install, or set network_access = true under [sandbox_workspace_write] in ~/.codex/config.toml. Codex sometimes installs the skill and then does not see it, which /skills plus a restart fixes — skills load from the repository as well as your home directory, so a global install can stay invisible in a project that pins its own set. And the first validation often fails, which is normal and not your cue to step in — the run in the screenshot above needed two correction rounds and about eight minutes end to end.

In StashBase, the diagram stays in the project. It runs the same local Codex, so architecture.html is written straight into the file tree and opens in place, next to the source and the conversation that produced it. That is the difference between a diagram you keep correcting and one you generated once and lost track of.

Another close read from the skills wave: Humanizer, tested.

Disclosure: I build StashBase, the workspace in the screenshot above. Archify creates and validates the diagram; StashBase is not required to use it. Commands and behavior verified against the Archify and official OpenAI documentation on August 31, 2026.