Plugins

Plugins are collections of resources that extend Codify's capabilities. Think of plugins as toolboxes—each one contains a set of tools (resources) that Codify can use to manage your development environment. Codify comes with a powerful default plugin maintained by the Codify team that provides 50+ essential resources for managing packages, tools, and system configuration.

What are Resources?

A resource represents a piece of software or system configuration that Codify can manage declaratively. Resources can be:

CLI tools (git, docker, terraform)
GUI applications (Visual Studio Code, Slack)
Package managers (Homebrew, npm, pip)
Version managers (nvm, pyenv, asdf)
Configuration (shell aliases, PATH entries, SSH keys)
Files and repositories (dotfiles, git repositories)

Each resource has a unique type (like homebrew, git, or vscode) that you use to reference it in your configuration file.

How Plugins Work

Plugin Architecture

When you run a Codify command, the following happens:

Parse Configuration: Codify reads your codify.jsonc file and identifies which plugins are needed
Load Plugins: Each plugin runs as an isolated process for security
Discover Resources: Codify asks each plugin "What resources can you manage?"
Validate: Your resource configurations are validated against the plugin's schemas
Execute: Codify coordinates with plugins to plan and apply changes

This architecture ensures plugins can't access privileged operations without your explicit approval.

Specifying Plugins in Your Configuration

You specify which plugins to use in a special project configuration block at the beginning of your codify.jsonc file:

[
  {
    "type": "project",
    "plugins": {
      "default": "latest",              // The default plugin (recommended)
      "my-custom-plugin": "^1.0.0",     // Third-party plugin from registry
      "./local/plugin.ts": "1.0.0"      // Local plugin during development
    }
  },

  // Your resource configurations follow...
  {
    "type": "homebrew",
    "formulae": ["git", "node"]
  }
]

Plugin version options:

"latest" - Always use the most recent stable version
"beta" - Use the latest beta version
Semantic version (e.g., "^1.0.0", "1.2.3") - Specific version constraints
Local file path (e.g., "./plugins/custom.ts") - Reference a local plugin file

If you don't specify a project config, the default plugin is loaded automatically.

How Resources Work

Declaring Resources

Resources are declared as JSON objects in your configuration file. Each resource must have a type field that identifies which resource you want to manage:

[
  { "type": "project", "plugins": { "default": "latest" } },

  // Simple resource with just type
  {
    "type": "vscode"
  },

  // Resource with parameters
  {
    "type": "homebrew",
    "formulae": ["git", "ripgrep", "fzf"],
    "casks": ["visual-studio-code", "docker"]
  },

  // Named resource (for multiple instances of same type)
  {
    "type": "alias",
    "name": "dev-shortcuts",
    "alias": "cdp",
    "value": "cd ~/projects"
  }
]

Resource Naming

When you need multiple resources of the same type, you can give them unique names:

[
  {
    "type": "alias",
    "name": "shortcut-1",
    "alias": "gs",
    "value": "git status"
  },
  {
    "type": "alias",
    "name": "shortcut-2",
    "alias": "gp",
    "value": "git push"
  }
]

Named resources are identified by type.name (e.g., alias.shortcut-1), while unnamed resources are identified by just their type.

Resource Dependencies

You can specify that one resource depends on another, ensuring they're applied in the correct order:

[
  {
    "type": "homebrew",
    "formulae": ["node@20"]
  },
  {
    "type": "npm",
    "packages": ["typescript", "eslint"],
    "dependsOn": ["homebrew"]  // Install homebrew first
  }
]

Codify automatically handles many common dependencies. For example, on macOS, most resources automatically depend on xcode-tools, so you don't need to declare it explicitly.

Cross-Platform Resources

Some resources only work on specific operating systems. You can optionally specify which platforms a resource applies to:

[
  {
    "type": "homebrew",      // Automatically only runs on macOS
    "formulae": ["git"]
  },
  {
    "type": "apt",           // Automatically only runs on Linux
    "packages": ["git"]
  },
  {
    "type": "path",
    "os": ["macOS", "linux"],  // Explicitly specify platforms
    "paths": ["/opt/custom/bin"]
  }
]

Resources that don't support your current platform are automatically skipped.

The Default Plugin

The default plugin is Codify's core plugin that provides over 50 essential resources for managing development environments. It's automatically loaded even if you don't specify it in your project config.

The default plugin includes resources for:

Package managers: Homebrew, apt, yum, dnf, snap, MacPorts
Version managers: nvm, pyenv, asdf, jenv
Programming tools: npm, pip, pnpm, virtualenv
Development tools: Git, Docker, VS Code, Terraform, AWS CLI
Shell configuration: aliases, PATH management, custom scripts
SSH management: SSH keys, config, agent
File operations: Local and remote file management
And much more...

See the Resource Reference for complete documentation of all available resources in the default plugin.

Using Default Plugin Resources

You don't need any special syntax to use default plugin resources—just specify the resource type:

[
  {
    "type": "git",
    "username": "Your Name",
    "email": "you@example.com"
  },
  {
    "type": "homebrew",
    "formulae": ["git", "node"],
    "casks": ["visual-studio-code"]
  },
  {
    "type": "nvm",
    "global": "20.11.0",
    "nodeVersions": ["18.20.0", "20.11.0"]
  }
]

Caching

When the Codify CLI first reads a codify.jsonc file, it parses the required plugins from the project config and downloads them from the Codify registry. Plugins are cached under ~/.codify/plugins/ to avoid re-downloading them on subsequent runs.

Plugin Cache Structure

~/.codify/plugins/
├── default/
│   ├── 1.0.0/
│   │   └── index.js
│   ├── 1.1.0/
│   │   └── index.js
│   └── beta/
│       └── index.js
└── custom-plugin/
    └── 2.0.0/
        └── index.js

Each plugin version is cached separately, so you can safely use different versions across different projects.

Clearing the Cache

If you experience issues with a stale or improperly downloaded plugin, you can clear the cache:

# Remove all cached plugins
rm -rf ~/.codify/plugins

# Remove a specific plugin
rm -rf ~/.codify/plugins/default

# Remove a specific version
rm -rf ~/.codify/plugins/default/1.0.0

Codify will re-download plugins on the next run.

Building Your Own Plugins

If you need to manage resources that aren't covered by the default plugin, you can create your own custom plugins. See the Plugin Development Guide for comprehensive documentation on building, testing, and distributing custom plugins.

Resource Reference - Complete documentation of all default plugin resources
Plugin Development Guide - Learn how to build custom plugins
Configuration Reference - Detailed guide to writing codify.jsonc files

On this page