Codify

🧠 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 — 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).

# 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 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

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)

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
• Source: jorelcb/codify
• License: Apache-2.0

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