# Codify

> Give your AI agent the blueprint it needs. MCP server & CLI that generates context, specs, and Agent Skills from project descriptions — powered by Claude & Gemini.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jorelcb-codify`
- **Verified:** Pending review
- **Seller:** [jorelcb](https://agentstack.voostack.com/s/jorelcb)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [jorelcb](https://github.com/jorelcb)
- **Source:** https://github.com/jorelcb/codify

## Install

```sh
agentstack add mcp-jorelcb-codify
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🧠 Codify

[](https://github.com/jorelcb/codify/releases)
[](https://modelcontextprotocol.io)
[](https://golang.org/doc/go1.23)
[](LICENSE)
[](https://www.anthropic.com)
[](https://ai.google.dev)
[](https://github.com/anthropics/AGENTS.md)

**Generate, audit, and evolve your AI agent's context across the whole project lifecycle.** 🏗️

_Because an agent without context is an intern with root access — and stale context is an intern reading three-week-old docs._

**[English]** | [Español](README_ES.md)

**Lifecycle:** [🚀 Bootstrap](#-bootstrap-phase-one-time-setup) · [🧰 Equip](#-equip-phase-install-context-skills-hooks-specs) · [🔧 Maintain](#-maintain-phase-ongoing-lifecycle)

**Jump:** [Quick Start](#-quick-start) · [Phases at a glance](#-lifecycle-phases-at-a-glance) · [MCP Server](#-mcp-server) · [Language Guides](#-language-specific-guides) · [Architecture](#%EF%B8%8F-architecture) · [Migrating from v1.x](#-migrating-from-v1x) · [FAQ](#-faq) · [Troubleshooting](#-troubleshooting)

---

## 🎯 The Problem

**Two problems, both real.**

**The agent improvises.** You tell it _"Build a payments API in Go with microservices"_, and:

- Folder structures nobody asked for
- Patterns that contradict your architecture
- Decisions you'll revert in the next session
- Zero continuity between sessions

It's not the agent's fault. Without context, it starts from scratch every session.

**Even when context exists, it drifts.** Three weeks ago you wrote a beautiful AGENTS.md. Since then `go.mod` added five deps, the Makefile gained four targets, the README evolved. The AGENTS.md still says what was true on day one. The agent reads it and confidently makes decisions on stale ground.

**Codify equips the agent with context AND keeps that context honest as the codebase moves.** 🛠️

## 💡 The Solution

**Codify** equips your AI agent with six layers it needs to stop improvising:

```
┌──────────────┐     ┌──────────────┐     ┌──────────────────────────────┐
│   Context    │     │    Specs     │     │            Skills            │
│              │     │              │     │                              │
│  What the    │     │  What to     │     │  How to do things right —    │
│  project is  │────▶│  build next  │     │  abilities + lifecycle       │
│              │     │              │     │  recipes (multi-step)        │
│  generate    │     │  spec        │     │  catalog                     │
│  analyze     │     │  --with-specs│     │                              │
└──────────────┘     └──────────────┘     └──────────────────────────────┘
     Memory             Plan                Abilities + Orchestration

┌─────────────────────────────────┐  ┌─────────────────────────────────────┐
│           Hooks                 │  │            Lifecycle                │
│                                 │  │                                     │
│   Deterministic guardrails      │  │   Maintain artifacts over time      │
│   on tool calls (Edit/Bash)     │  │                                     │
│                                 │  │   config / init                     │
│   hooks                         │  │   check / update / audit / usage    │
└─────────────────────────────────┘  └─────────────────────────────────────┘
       Determinism                              Custodianship
```

- **Context** gives the agent architectural memory — stack, patterns, conventions, domain knowledge
- **Specs** give the agent an implementation plan — features, acceptance criteria, task breakdowns
- **Skills** give the agent reusable abilities — how to commit, version, design entities, review code — plus **lifecycle recipes**, the multi-step orchestrations (bug fixing, releases, the SDD lifecycle) that ship as a `lifecycle` skills category
- **Hooks** add deterministic guardrails — shell scripts on Claude Code lifecycle events, no LLM in the loop
- **Lifecycle** keeps everything in sync — `config`, `init`, `check`, `update`, `audit`, `usage`, `watch` — drift detection, selective regen, commit auditing, cost transparency, foreground watching

It follows the [AGENTS.md standard](https://github.com/anthropics/AGENTS.md) — an open specification backed by the Linux Foundation for providing AI agents with project context. Files work out of the box with Claude Code, Cursor, Codex, and any agent that reads the standard.

## 🗺️ Lifecycle phases at a glance

Codify groups its commands into three phases that map naturally to how a developer adopts and uses it:

```
    ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
    │  Bootstrap  │ ──▶ │    Equip    │ ──▶ │  Maintain   │
    └─────────────┘     └─────────────┘     └─────────────┘
       config              generate            check
       init                analyze             update
                           spec                audit
                           catalog             watch
                                               usage
                                               resolve
```

- **Bootstrap (one-time)** — set up the workstation (`codify config`) or a project (`codify init`).
- **Equip (per need)** — generate context, install skills (incl. lifecycle recipes) and hooks via `codify catalog`, write specs.
- **Maintain (ongoing)** — detect drift, regenerate, audit commits, track usage.

The same diagram is available in `codify --help`. For the full matrix of which command applies to **workstation vs project** and **greenfield vs brownfield**, see [`docs/lifecycle-matrix.md`](docs/lifecycle-matrix.md).

## ✨ Before and after

### 😱 Without Codify

```
Day 1
You: "Create a payments API in Go"

Agent: *creates main.go with everything in one file*
You: "No, use Clean Architecture"
Agent: *creates structure but mixes domain with infra*
You: "Repositories go in infrastructure"
Agent: *refactors for the third time*
You: "What about the BDD tests I asked for yesterday?"
Agent: "BDD tests? This is the first time you've mentioned that"
You: "At least commit this properly"
Agent: *writes "update code" as commit message*

Day 22 (after AGENTS.md was written and never updated)
You: "Add the new circuit-breaker dep we added last week"
Agent: *uses go-retry — never heard of go-resilience because AGENTS.md is stale*

Result: 45 minutes correcting the agent on day 1, two hours on day 22. 😤
```

### 🚀 With Codify

```
Day 1
You: "Create a payments API in Go"

Agent: *reads AGENTS.md, CONTEXT.md, DEVELOPMENT_GUIDE.md*
Agent: "I see you use DDD with Clean Architecture, PostgreSQL,
        BDD testing with Godog, and idiomatic Go patterns.
        I'll create the payments endpoint in internal/domain/payment/
        following your patterns and concurrency conventions."

Agent: *reads SKILL.md for conventional commits*
Agent: "Done. Here's the commit following Conventional Commits:
        feat(payment): add payment domain entity with Stripe integration"

Day 22 (you've been editing in the background; AGENTS.md auto-stayed in sync)
You: "Add the new circuit-breaker dep we added last week"
Agent: *reads current AGENTS.md — knows go-resilience is the project's choice*
Agent: "Adding go-resilience following the wrap-with-context pattern from
        IDIOMS.md. Note that codify check ran clean before this session."

Result: Coherent code from the first line, AND from line 1,000. ✨
```

Behind the scenes on day 22, **`codify watch`** has been quietly running, **`codify check`** flagged the `go.mod` change, **`codify update`** refreshed AGENTS.md, and **`codify usage`** shows it cost $0.04 in tokens.

## ⚡ Quick Start

The recommended sequence for a first-time user. Each step maps to a lifecycle phase ([see diagram above](#-lifecycle-phases-at-a-glance)). For a full walk-through with expected outputs see [`docs/getting-started.md`](docs/getting-started.md).

```bash
# 1. Install (Homebrew / go install / GitHub Releases)
brew tap jorelcb/tap && brew install codify

# 2. Bootstrap — workstation defaults (one time)
codify config

# 3. Bootstrap — your project (greenfield or brownfield)
cd my-project && codify init

# 4. Equip — install only what you need (each is skippable)
codify spec  --from-context ./output//    # SDD specs
codify catalog                                        # Skills (incl. lifecycle recipes) + hooks + plugins

# 5. Maintain — keep artifacts honest as the code evolves
codify check    # Drift detection — no LLM, zero cost
codify update   # Selective regen when input signals drift
codify audit    # Review commits against conventions
codify watch    # Foreground watcher
codify usage    # LLM token + cost summary
codify resolve  # Fill [DEFINE: ...] markers
```

API keys (`ANTHROPIC_API_KEY` or `GEMINI_API_KEY`) are required only for LLM-backed commands — see the table in [`docs/getting-started.md`](docs/getting-started.md#api-keys).

The first-run auto-launch of `codify config` is soft (TTY only, never blocks CI). Opt out via `--no-auto-config`, `CODIFY_NO_AUTO_CONFIG=1`, or `~/.codify/.no-auto-config`.

---

## 🚀 Bootstrap phase (one-time setup)

> **One-time setup** for the workstation and per project. After this, you move to the [Equip phase](#-equip-phase-install-context-skills-hooks-specs).

### ⚙️ Configuration & Bootstrap

Two complementary commands shape how Codify behaves: **`codify config`** at the user level and **`codify init`** at the project level. Both compose on top of the existing standalone commands; they are smart entry points, not replacements.

#### `codify config` — user-level defaults

`codify config` manages your global preferences at `~/.codify/config.yml`. The first time you run any interactive Codify command in a TTY without that file existing, you'll be offered the option to launch the wizard. Three answers: Yes (run wizard), No (use defaults this run), Skip permanently (creates `~/.codify/.no-auto-config` so the prompt never appears again).

| Subcommand                        | Action                                                      |
| --------------------------------- | ----------------------------------------------------------- |
| `codify config`                   | Wizard if no config exists; print current config if it does |
| `codify config get `         | Read a single value                                         |
| `codify config set  ` | Update a single value                                       |
| `codify config unset `       | Clear a single value                                        |
| `codify config edit`              | Open `~/.codify/config.yml` in `$EDITOR`                    |
| `codify config list`              | Print the effective config (with merge applied)             |

Valid keys: `preset`, `locale`, `language`, `model`, `target`, `provider`, `project_name`.

#### `codify init` — project-level bootstrap

`codify init` asks one question first: is this project new or existing? Based on the answer it routes you to the right flow:

| Answer       | Internal flow      | What you provide                                            |
| ------------ | ------------------ | ----------------------------------------------------------- |
| **new**      | invokes `generate` | project name + description (inline or path to a file)       |
| **existing** | invokes `analyze`  | project name (auto-detected from cwd, override if you want) |

After that, both branches collect: architectural preset (override of global default), language, locale, output directory, model. Result:

- `.codify/config.yml` — project-scoped defaults that persist for everyone with the repo
- `.codify/state.json` — snapshot of generation state (consumed by lifecycle commands)
- Generated `AGENTS.md` and `context/*.md` written to `output/`

Skills and hooks are NOT bundled — `init` prints recommended next-step commands to keep responsibilities focused. Run `codify catalog` (skills — including the `lifecycle` recipes — hooks, and plugins) separately when you want them.

#### Merge precedence

When any command resolves a value (preset, locale, model, etc.):

```
flags > .codify/config.yml > ~/.codify/config.yml > built-in defaults
```

Setting `--preset hexagonal` on the command line wins regardless of what's in either config file. Project-level config wins over user-level. Built-ins fill the gaps.

---

## 🧰 Equip phase (install context, skills, hooks, specs)

> **Install only what you need.** Each command below is independent and skippable. After equipping, the [Maintain phase](#-maintain-phase-ongoing-lifecycle) keeps everything honest as the project evolves.

### 📋 Context Generation

The foundation. Generates files following the [AGENTS.md](https://github.com/anthropics/AGENTS.md) standard that give your agent deep project memory.

#### When to use `generate` vs `analyze`

| Situation                                                     | Use                                                          | Why                                                                                                                                                        |
| ------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Greenfield project (no code yet)                              | `codify generate`                                            | You provide the description; the LLM generates context against it                                                                                          |
| Existing repo with code in it                                 | `codify analyze`                                             | The scanner extracts factual signals (deps, build targets, CI, frameworks) and feeds them as ground truth — much higher accuracy than a manual description |
| Existing repo + you want to override what the scanner detects | `codify analyze` first, then edit, then `codify reset-state` | Scan-first, hand-tune second                                                                                                                               |
| You have a detailed design doc                                | `codify generate --from-file ./docs/design.md`               | Treat the file's content as the description                                                                                                                |
| In doubt                                                      | `codify init`                                                | Asks "new or existing?" and routes you to the right flow internally                                                                                        |

#### `generate` command — Context from a description

```bash
codify generate payment-service \
  --description "Payment microservice in Go with gRPC and PostgreSQL" \
  --language go
```

#### `analyze` command — Context from an existing project

Scans an existing codebase and generates context files from what it finds. Uses a **differentiated prompt** that treats scan data as factual ground truth, producing more accurate output than a manual description.

**What the scanner detects:**

- Language, framework, and dependencies (Go, JS/TS, Python, Rust, Java, Ruby)
- Directory structure (3 levels deep)
- README content (filtered: badges, HTML comments, ToC removed)
- Existing context files (18+ patterns: AGENTS.md, .claude/CLAUDE.md, ADRs, OpenAPI specs, etc.)
- Build targets from Makefile/Taskfile (exact commands for AGENTS.md)
- Testing patterns (frameworks, BDD scenarios, coverage config)
- CI/CD pipelines (GitHub Actions triggers and jobs, GitLab CI)
- Infrastructure signals (Docker, Terraform, Kubernetes, Helm)

```bash
codify analyze /path/to/my-project
```

#### Generated files

| File                   | What it does                                                                         |
| --------

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jorelcb](https://github.com/jorelcb)
- **Source:** [jorelcb/codify](https://github.com/jorelcb/codify)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jorelcb-codify
- Seller: https://agentstack.voostack.com/s/jorelcb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.