7 min read
Back to How-to guides

How to install and manage the GARDEN plugin

GARDEN supports Claude Code and Codex CLI. uv must be on PATH for either harness: bundled Python entry points run through uv run --no-project. See GARDEN principles for the methodology.

1. Confirm the prerequisite

Install uv and make it available on PATH before adding the plugin in either harness.

  • Action: confirm that uv is available in the shell used for Claude Code or Codex CLI.
  • Acceptance signal: uv resolves on PATH before any bundled Python entry point runs.

2. Add the marketplace

Claude Code

Add the GARDEN marketplace. Pass --scope user|project|local to choose where it is registered; the default is user.

claude plugin marketplace add vshuraeff/garden

Codex CLI

Add the same marketplace to Codex CLI. The command also accepts a local path or full Git URL, with --ref or --sparse when needed.

codex plugin marketplace add vshuraeff/garden
  • Action: add the garden marketplace in each harness where the plugin is needed.
  • Acceptance signal: claude plugin marketplace list and codex plugin marketplace list each show a marketplace named garden.

3. Install the plugin

Claude Code

Install the marketplace-qualified plugin name. Pass -s user|project|local to set the install scope. You can instead select the plugin from the interactive /plugin menu.

claude plugin install garden@garden

Start a new Claude Code session after installing. Its first interactive load presents a trust prompt; accept it only after reviewing the plugin source.

Codex CLI

Install the plugin from the marketplace.

codex plugin add garden@garden

Start a new Codex session after installing. Hooks are skipped until trusted; run /hooks, inspect the source and command, then trust the hashes.

  • Action: install garden@garden in the selected harness, using a Claude Code scope flag when required, then start a new session.
  • Acceptance signal: claude plugin list shows garden in Claude Code; codex plugin list --marketplace garden and /plugins show it in Codex CLI. Confirm that the MCP tools garden_inspect_project and garden_check_file are available.

4. Pin the plugin for a team or project

This Claude Code-specific configuration declares the GARDEN marketplace and enables the plugin for a repository. It also enables automatic marketplace updates.

{
  "extraKnownMarketplaces": {
    "garden": {
      "source": { "source": "github", "repo": "vshuraeff/garden" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": { "garden@garden": true }
}
  • Action: merge this configuration with the project's existing .claude/settings.json, preserving unrelated settings.
  • Acceptance signal: the project configuration names garden@garden in enabledPlugins, and a new project-scoped Claude Code session resolves the marketplace.

5. Know what the plugin ships

Installing garden provides six skills: garden:bootstrap, garden:retrofit, garden:review, garden:audit, garden:start, and garden:stop.

The plugin includes the read-only garden-reviewer agent. Claude Code loads its Markdown agent from the plugin package. Codex CLI requires garden:start to install the project-scoped .codex/agents/garden-reviewer.toml agent.

The garden MCP server runs tools/garden_mcp.py over stdio and exposes the read-only garden_inspect_project and garden_check_file tools. In Claude Code, use /mcp to confirm that the server is available.

The manifest-registered garden-check.sh PostToolUse hook is a thin wrapper running garden_hook.py, backed by garden_core.py. It is a no-op until naming-registry.txt exists at the project root. Once it exists, it blocks when root CONTEXT.md exceeds 200 lines or a CONTRACT.md does not start with Version: MAJOR.MINOR.PATCH; it gives advisory nudges for a missing per-capability CONTRACT.md or missing colocated tests.

  • Action: inspect the installed skills, agent delivery, MCP server, and hook behavior before adopting GARDEN in a project.
  • Acceptance signal: Claude Code shows the garden MCP server in /mcp; the hook has no effect until the project contains naming-registry.txt.

6. Start a GARDEN adoption in a project

Use garden:bootstrap for a new project and garden:retrofit for an existing codebase.

New project:

Use the garden:bootstrap skill to set up this new project under GARDEN: propose a
slice map for <short product description>, create the naming registry, root
CONTEXT.md, one directory per slice with README and CONTRACT.md, and wire the CI
gates in the prescribed order. Ask me before finalizing the slice map.

Existing codebase:

Use the garden:retrofit skill to begin adopting GARDEN in this repository: measure
the baseline, propose the first slice to extract, add contracts at its seams, set
the lint ratchet to warn, and log every decision to retrofit-log.md. Do not
restructure anything outside the first slice.

garden:start asks whether to install for Claude Code, Codex CLI, or both, then runs uv run --no-project <plugin-root>/tools/garden_project.py install --root <project-root> --harness <claude|codex|both>. For Claude Code it installs the owned, SHA-256 digest-marked .claude/rules/garden.md. For Codex CLI it appends an owned, digest-marked block to the project-root AGENTS.md and installs .codex/agents/garden-reviewer.toml. The installer refuses to touch unmanaged or hand-edited content that it does not own.

After selecting Codex CLI, start a new Codex session and inspect the project-scoped reviewer through /agent.

Codex installs a cached plugin copy. During local plugin development, bump the shared version with uv run --no-project plugins/garden/tools/plugin_version.py bump patch and reinstall the plugin.

  • Action: use the matching prompt, then run garden:start and select the harness or harnesses that need project-scoped artifacts.
  • Acceptance signal: bootstrap creates the naming registry, root CONTEXT.md, slice READMEs and CONTRACT.md files, and stack-compatible CI gates; retrofit records three dated baselines, creates the first slice and its seam contracts, applies the lint ratchet, and writes retrofit-log.md decisions. With Codex CLI selected, a new session shows garden-reviewer in /agent.

7. Use the plugin day to day

Run garden:review before merging a change. For example, prompt either harness with Run garden:review on the current diff. Run garden:audit periodically for a full compliance audit. Once naming-registry.txt exists, the PostToolUse gate runs after matching tool use; it has no manual invocation.

  • Action: review each proposed merge with garden:review and schedule garden:audit for broader compliance checks.
  • Acceptance signal: review findings cite the current diff and audit findings cite the compliance checklist; the PostToolUse hook reports any applicable hard-gate failure.

8. Update the plugin

Claude Code

Update the marketplace, then the installed plugin, and start a new Claude Code session. Alternatively, use autoUpdate: true in the Claude Code configuration from step 4.

claude plugin marketplace update garden
claude plugin update garden

Codex CLI

Codex CLI has no dedicated plugin update command. Its available command set implies refreshing the marketplace snapshot, then rerunning the install command to reinstall from that snapshot. Omit garden from the first command to upgrade all configured Git marketplaces.

codex plugin marketplace upgrade garden
codex plugin add garden@garden
  • Action: use the two commands for the selected harness in the order shown; start a new Claude Code session after its update.
  • Acceptance signal: claude plugin details garden shows the updated installed plugin, and codex plugin list --marketplace garden shows the reinstalled Codex CLI plugin.

9. Remove or pause the plugin

Run garden:stop before removing the plugin. It asks which harnesses to remove and runs garden_project.py remove --harness <claude|codex|both>, removing only the owned, digest-marked artifacts that it installed. It does not touch naming-registry.txt, CONTEXT.md, CONTRACT.md files, slice directories, or retrofit-log.md.

Claude Code

To pause the plugin, run claude plugin disable garden; re-enable it with claude plugin enable garden. Remove it with claude plugin uninstall garden, then remove the marketplace with claude plugin marketplace remove garden. Start a new Claude Code session after disabling, enabling, uninstalling, or removing the marketplace.

If needed, remove the leftover cache:

rm -rf ~/.claude/plugins/cache/garden/garden/

Removing the marketplace already removes ~/.claude/plugins/marketplaces/garden/.

Codex CLI

Codex CLI has no disable or enable command; removal is its only plugin-management lever. Remove the plugin from local configuration and cache, then remove the marketplace when it is no longer needed.

codex plugin remove garden@garden
codex plugin marketplace remove garden

Methodology artifacts are deliberately never removed: naming-registry.txt, CONTEXT.md, CONTRACT.md files, slice READMEs, and retrofit-log.md are project content. Removing naming-registry.txt alone deactivates the PostToolUse hook; deleting the remaining artifacts is a manual editorial decision.

  • Action: run garden:stop for the installed harness or harnesses, then pause or remove the plugin and marketplace as needed.
  • Acceptance signal: claude plugin list or codex plugin list --marketplace garden no longer shows garden, the marketplace is absent, and methodology artifacts remain unless manually removed.

Next steps