Codify
Plugin Development

Plugin development

Build custom Codify plugins to manage system resources declaratively

Codify plugins extend the CLI's capabilities by implementing resources that can be created, modified, and destroyed on a system. This guide covers everything you need to build your own plugin.

Overview

A Codify plugin is a Node.js module that extends Codify's functionality by implementing resources—manageable entities on your system such as applications, CLI tools, or configuration settings. Think of plugins as the bridge between Codify's declarative configuration syntax and the actual system commands needed to install and configure software.

Architecture

Codify uses a multi-process plugin architecture for security and isolation:

  • CLI Process: The main Codify CLI runs in the parent process, orchestrating the workflow, managing user interaction, and coordinating plugins.
  • Plugin Process: Each plugin runs in an isolated child process, communicating with the CLI via Inter-Process Communication (IPC). This ensures plugins can't directly access privileged operations without user approval.
  • Type-Safe IPC: All messages between the CLI and plugins are validated against JSON schemas, ensuring data integrity and preventing malformed requests.

This architecture means your plugin:

  • Defines one or more resources (applications, CLI tools, settings)
  • Runs in an isolated child process and communicates with the CLI via IPC
  • Implements a standardized lifecycle: validate → plan → apply
  • Uses the @codifycli/plugin-core framework for resource management

How Plugins Work

When a user runs codify apply, the following workflow occurs:

  1. Parse Configuration: The CLI reads the user's codify.jsonc file
  2. Initialize Plugins: For each resource type in the config, the CLI spawns the appropriate plugin process
  3. Validate: Plugins validate the user's configuration against their schemas
  4. Refresh: Plugins query the current system state for each resource
  5. Plan: Plugins compare desired state vs current state and generate a change set
  6. Apply: After user approval, plugins execute the planned changes sequentially

Your plugin participates in each of these phases by implementing the Resource interface.

Prerequisites

  • Node.js ≥ 22.0.0
  • TypeScript knowledge
  • Understanding of Codify basics

What's Next

This guide is organized into the following sections:

Architecture

A architecture overview to make it easier to develop a Codify plugin

Quick start

Build your first Codify plugin in minutes

On this page

OverviewArchitectureHow Plugins WorkPrerequisitesWhat's NextQuick Links