Name	Name	Last commit message	Last commit date
parent directory ..
README.md	README.md

Documentation / Plugins

Plugins

Codanna plugins are project-scoped. They install to .claude/ in your project directory, not globally. This lets each project have different plugin versions.

codanna-cc Plugin

Available via Claude Code's /plugin command or codanna's CLI.

Via Claude Code:

# Add the Codanna marketplace
/plugin marketplace add bartolli/codanna-plugins

# Install the plugin
/plugin install codanna-cc@codanna-plugins

Via Codanna CLI:

codanna plugin add https://github.com/bartolli/codanna-plugins.git codanna
codanna plugin add https://github.com/bartolli/codanna-plugins.git codanna --ref v1.2.0  # Specific version

The CLI method gives you version control - install different tags per project.

Token-Efficient Workflows

The plugin includes Node.js scripts that parse JSON output to save tokens. See codanna-plugins for examples.

Example: Piping with Node.js wrapper

# Node script handles JSON parsing and formatting
node .claude/scripts/codanna/context-provider.js find "error handling" --limit=3

# Output includes symbol_id for follow-up queries
# 1. IndexError (Enum) [symbol_id:205]
#    Use: node .claude/scripts/codanna/context-provider.js calls symbol_id:205

This approach reduces token usage by pre-processing results before presenting to the AI assistant.

Quick Start

Install our core plugin

codanna plugin add https://github.com/bartolli/codanna-plugins.git codanna

Update a plugin

codanna plugin update my-plugin

Remove a plugin

codanna plugin remove my-plugin

List installed plugins

codanna plugin list --verbose

Verify plugin integrity

codanna plugin verify my-plugin

Adding Plugins

When you add a plugin, codanna:

Clones the marketplace repository to a temporary directory
Validates the plugin manifest (.claude-plugin/plugin.json)
Checks for file conflicts with existing plugins
Copies component files to namespaced directories:
- Commands → .claude/commands//
- Agents → .claude/agents//
- Hooks → .claude/hooks//
- Scripts → .claude/scripts//
- Other files → .claude/plugins//
Merges MCP server configuration into .mcp.json
Calculates integrity checksum (SHA-256) of all installed files
Updates the lockfile (.codanna/plugins/lockfile.json)

Advanced Options

Install specific Git ref (branch/tag/commit)

codanna plugin add https://github.com/user/marketplace.git my-plugin --ref v1.2.0

Force installation (overwrite conflicts)

codanna plugin add https://github.com/user/marketplace.git my-plugin --force

Preview changes without installing

codanna plugin add https://github.com/user/marketplace.git my-plugin --dry-run

Rollback Protection: If any step fails, codanna automatically:

Removes partially copied files
Restores previous plugin version (during updates)
Restores MCP configuration
Cleans up directories

Updating Plugins

Updates detect changes via Git commit SHA comparison:

Update to latest commit

codanna plugin update my-plugin

Update to specific ref

codanna plugin update my-plugin --ref main

Force reinstall (bypass commit check)

codanna plugin update my-plugin --force

Update Process:

Resolves remote commit SHA from Git repository
Compares with installed commit:

Same commit + passes verification → "Already up to date"
Same commit + fails verification → Reinstall
Different commit → Update

Backs up existing plugin before changes
Uninstalls old version completely
Installs new version with new files
Rolls back to backup if installation fails

Removing Plugins

Safe removal with complete cleanup:

codanna plugin remove my-plugin

Force removal (skip safety checks)

codanna plugin remove my-plugin --force

Preview removal

codanna plugin remove my-plugin --dry-run

Cleanup Actions:

Removes all tracked files from filesystem
Removes MCP server entries from .mcp.json
Cleans up plugin directories (.claude/plugins//, etc.)
Updates lockfile to remove plugin entry

Plugin Storage Structure

.claude/
├── commands/<plugin>/ # Slash commands
├── agents/<plugin>/ # Custom agents
├── hooks/<plugin>/ # Event hooks
├── scripts/<plugin>/ # Utility scripts
└── plugins/<plugin>/ # Additional payload files

.codanna/
└── plugins/
└── lockfile.json # Installation tracking with integrity checksums

Lockfile Structure

The lockfile (.codanna/plugins/lockfile.json) tracks all installed plugins:

{
  "version": "1.0.0",
  "plugins": {
    "my-plugin": {
      "name": "my-plugin",
      "version": "1.0.0",
      "commit": "abc123def456...",
      "marketplace_url": "https://github.com/user/marketplace.git",
      "installed_at": "2025-10-17T13:58:03Z",
      "updated_at": "2025-10-17T14:00:00Z",
      "integrity": "sha256:...",
      "files": [".claude/commands/my-plugin/command.md"],
      "mcp_keys": ["my-plugin-server"],
      "source": {
        "type": "marketplace_path",
        "relative": "plugins/my-plugin"
      }
    }
  }
}

MCP Server Integration

Plugins can provide MCP servers that get merged into your project's .mcp.json:

Before Installation:

{
  "mcpServers": {
    "existing-server": { "command": "cmd" }
  }
}

After Installing Plugin with MCP Server:

{
  "mcpServers": {
    "existing-server": { "command": "cmd" },
    "my-plugin-server": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}

Conflict Handling: If an MCP server key already exists, installation fails unless you use --force (which overwrites the existing entry).

Verification and Integrity

Verify plugin integrity at any time:

Verify specific plugin

codanna plugin verify my-plugin --verbose

Verification Checks:

All tracked files exist on filesystem
File contents match SHA-256 integrity checksum
MCP server keys present in .mcp.json

Failed verification indicates tampering or corruption. Reinstall with --force to fix.

Listing Plugins

Basic list

codanna plugin list

Verbose output with details

codanna plugin list --verbose

JSON output for scripting

codanna plugin list --json

Verbose Output Shows:

Plugin name and version
Installation and update timestamps
Git commit SHA
Marketplace URL
Number of installed files
MCP server keys

Command Reference

Command	Description	Flags
codanna plugin add	Install plugin from marketplace	--ref, --force, --dry-run
codanna plugin remove	Remove installed plugin	--force, --dry-run
codanna plugin update	Update plugin to latest version	--ref, --force, --dry-run
codanna plugin list	List installed plugins	--verbose, --json
codanna plugin verify	Verify plugin integrity	--verbose

Common Flags:

--ref : Specify Git branch, tag, or commit SHA
--force: Override conflicts and safety checks
--dry-run: Preview changes without executing
--verbose: Show detailed information
--json: Output as JSON for scripting

Safety Features

Transactional Installation: All-or-nothing installation with automatic rollback on failures
File Conflict Detection: Prevents overwriting files owned by other plugins (unless --force)
Integrity Verification: SHA-256 checksums detect file tampering or corruption
Backup and Restore: Updates back up existing version before changes
MCP Conflict Detection: Prevents duplicate MCP server keys (unless --force)
Namespaced Directories: Each plugin isolated in its own subdirectories

Error Handling

Common errors and solutions:

Error	Cause	Solution
AlreadyInstalled	Plugin already exists	Use --force to reinstall
FileConflict	File owned by another plugin	Check conflict owner, use --force to override
McpServerConflict	MCP key already exists	Rename server or use --force
IntegrityCheckFailed	Files modified/corrupted	Reinstall with codanna plugin update --force
PluginNotFound	Plugin not in marketplace	Check plugin name and marketplace URL
InvalidPluginManifest	Manifest validation failed	Contact plugin author to fix manifest

Creating Plugins

To create your own plugin:

Create a Git repository with this structure:

   my-plugin/
   ├── .claude-plugin/
   │ └── plugin.json # Required manifest
   ├── commands/ # Optional: slash commands
   ├── agents/ # Optional: custom agents
   ├── hooks/ # Optional: event hooks
   └── scripts/ # Optional: utility scripts

Define the manifest (.claude-plugin/plugin.json):

{
    "name": "my-plugin",
    "version": "1.0.0",
    "description": "What this plugin does",
    "author": { "name": "Your Name" },
    "commands": "./commands",
    "agents": "./agents"
}

Create a marketplace manifest (.claude-plugin/marketplace.json):

{
    "name": "My Marketplace",
    "version": "1.0.0",
    "plugins": [
    {
        "name": "my-plugin",
        "description": "Plugin description",
        "source": {
        "type": "marketplace_path",
        "relative": "."
        }
    }
    ]
}

Publish to Git and share the repository URL

Users can then install with:

codanna plugin add https://github.com/you/my-plugin.git my-plugin

Back to Documentation

FilesExpand file tree

plugins

Directory actions

More options