leo-claude-mktplace/docs/CONFIGURATION.md

Configuration Guide

Centralized configuration documentation for all plugins and MCP servers in the Leo Claude Marketplace.

---

Quick Start

After installing the marketplace and plugins via Claude Code:

/setup

The interactive wizard auto-detects what's needed and handles everything except manually adding your API tokens.

---

Setup Flow Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                           FIRST TIME SETUP                                  │
│                         (once per machine)                                  │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                              /setup --full
                          (or /setup auto-detects)
                                    │
     ┌──────────────────────────────┼──────────────────────────────┐
     ▼                              ▼                              ▼
┌─────────────┐            ┌─────────────────┐            ┌─────────────────┐
│  PHASE 1    │            │    PHASE 2      │            │    PHASE 3      │
│  Automated  │───────────▶│    Automated    │───────────▶│   Interactive   │
│             │            │                 │            │                 │
│ • Check     │            │ • Find MCP path │            │ • Ask Gitea URL │
│   Python    │            │ • Create venv   │            │ • Ask Org name  │
│   version   │            │ • Install deps  │            │ • Create config │
└─────────────┘            └─────────────────┘            └─────────────────┘
                                                                   │
                                                                   ▼
                                                   ┌───────────────────────────┐
                                                   │        PHASE 4            │
                                                   │     USER ACTION           │
                                                   │                           │
                                                   │  Edit config file to add  │
                                                   │  API token (for security) │
                                                   │                           │
                                                   │  nano ~/.config/claude/   │
                                                   │       gitea.env           │
                                                   └───────────────────────────┘
                                                                   │
                                                                   ▼
     ┌──────────────────────────────┬──────────────────────────────┐
     ▼                              ▼                              ▼
┌─────────────┐            ┌─────────────────┐            ┌─────────────────┐
│  PHASE 5    │            │    PHASE 6      │            │    PHASE 7      │
│ Interactive │            │    Automated    │            │    Automated    │
│             │            │                 │            │                 │
│ • Confirm   │            │ • Create .env   │            │ • Test API      │
│   repo name │            │ • Check         │            │ • Show summary  │
│   from git  │            │   .gitignore    │            │ • Restart note  │
└─────────────┘            └─────────────────┘            └─────────────────┘
                                                                   │
                                                                   ▼
                                                   ┌───────────────────────────┐
                                                   │      RESTART SESSION      │
                                                   │                           │
                                                   │  MCP tools available      │
                                                   │  after restart            │
                                                   └───────────────────────────┘


┌─────────────────────────────────────────────────────────────────────────────┐
│                          NEW PROJECT SETUP                                  │
│                        (once per project)                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
             /setup --quick                     /setup
             (explicit mode)               (auto-detects mode)
                    │                               │
                    │                    ┌──────────┴──────────┐
                    │                    ▼                     ▼
                    │              "Quick setup"         "Full setup"
                    │               (skips to              (re-runs
                    │              project config)          everything)
                    │                    │                     │
                    └────────────────────┴─────────────────────┘
                                         │
                                         ▼
                              ┌─────────────────────┐
                              │   PROJECT CONFIG    │
                              │                     │
                              │ • Detect repo from  │
                              │   git remote        │
                              │ • Confirm with user │
                              │ • Create .env       │
                              │ • Check .gitignore  │
                              └─────────────────────┘
                                         │
                                         ▼
                                      Done!

---

What Runs Automatically vs User Interaction

/setup --full - Full Setup

Phase	Type	What Happens
1. Environment Check	Automated	Verifies Python 3.10+ is installed
2. MCP Server Setup	Automated	Finds plugin path, creates venv, installs dependencies
3. System Config Creation	Interactive	Asks for Gitea URL and organization name
4. Token Entry	User Action	User manually edits config file to add API token
5. Project Detection	Interactive	Shows detected repo name, asks for confirmation
6. Project Config	Automated	Creates .env file, checks .gitignore
7. Validation	Automated	Tests API connectivity, shows summary

/setup --quick - Quick Project Setup

Phase	Type	What Happens
1. Pre-flight Check	Automated	Verifies system config exists
2. Project Detection	Interactive	Shows detected repo name, asks for confirmation
3. Project Config	Automated	Creates/updates .env file
4. Gitignore Check	Interactive	Asks to add .env to .gitignore if missing

---

One Command, Three Modes

Mode	When to Use	What It Does
/setup	Any time	Auto-detects: runs full, quick, or sync as needed
/setup --full	First time on a machine	Full setup: MCP server + system config + project config
/setup --quick	Starting a new project	Quick setup: project config only (assumes system is ready)
/setup --sync	After repo move/rename	Updates .env to match current git remote

Auto-detection logic:

1. No system config → full mode
2. System config exists, no project config → quick mode
3. Both exist, git remote differs → sync mode
4. Both exist, match → already configured, offer to reconfigure

Typical workflow:

1. Install plugin → run /setup (auto-runs full mode)
2. Start new project → run /setup (auto-runs quick mode)
3. Repository moved? → run /setup (auto-runs sync mode)

---

Configuration Architecture

This marketplace uses a hybrid configuration approach:

┌─────────────────────────────────────────────────────────────────┐
│                    SYSTEM-LEVEL (once per machine)             │
│                    ~/.config/claude/                            │
├─────────────────────────────────────────────────────────────────┤
│  gitea.env     │  GITEA_API_URL, GITEA_API_TOKEN                       │
│  netbox.env    │  NETBOX_API_URL, NETBOX_API_TOKEN                     │
│  git-flow.env  │  GIT_WORKFLOW_STYLE, GIT_DEFAULT_BASE, etc.   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ Shared across all projects
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  PROJECT-LEVEL (once per project)              │
│                  <project-root>/.env                            │
├─────────────────────────────────────────────────────────────────┤
│  GITEA_REPO              │  Repository as owner/repo format    │
│  GIT_WORKFLOW_STYLE      │  (optional) Override system default │
│  PR_REVIEW_*             │  (optional) PR review settings      │
└─────────────────────────────────────────────────────────────────┘

Benefits:

• Single token per service (update once, use everywhere)
• Easy multi-project setup (just run /setup in each project)
• Security (tokens never committed to git, never typed into AI chat)
• Project isolation (each project can override defaults)

---

Prerequisites

Before running /setup:

1. Python 3.10+ installed

   python3 --version  # Should be 3.10.0 or higher
   

2. Git repository initialized (for project setup)

   git status  # Should show initialized repository
   

3. Claude Code installed and working with the marketplace

---

Setup Methods

Method 1: Interactive Wizard (Recommended)

Run the setup wizard in Claude Code:

/setup

The wizard will guide you through each step interactively and auto-detect the appropriate mode.

Note: After first-time setup, you'll need to restart your Claude Code session for MCP tools to become available.

Method 2: Manual Setup

If you prefer to set up manually or need to troubleshoot:

Step 1: MCP Server Setup

# Navigate to marketplace directory
cd /path/to/leo-claude-mktplace

# Set up Gitea MCP server
cd mcp-servers/gitea
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate

# (Optional) Set up NetBox MCP server
cd ../netbox
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate

Step 2: System Configuration

mkdir -p ~/.config/claude

# Gitea configuration (credentials only)
cat > ~/.config/claude/gitea.env << 'EOF'
GITEA_API_URL=https://gitea.example.com
GITEA_API_TOKEN=your_token_here
EOF
chmod 600 ~/.config/claude/gitea.env

Step 3: Project Configuration

In each project root:

cat > .env << 'EOF'
GITEA_REPO=your-organization/your-repo-name
EOF

Add .env to .gitignore if not already there.

Method 3: Automation Script (CI/Scripting)

For automated setups or CI environments:

cd /path/to/leo-claude-mktplace
./scripts/setup.sh

This script is useful for CI/CD pipelines and bulk provisioning.

---

Configuration Reference

System-Level Files

Located in ~/.config/claude/:

File	Required By	Purpose
gitea.env	projman, pr-review	Gitea API credentials
netbox.env	cmdb-assistant	NetBox API credentials
git-flow.env	git-flow	Default git workflow settings

Gitea Configuration

# ~/.config/claude/gitea.env
GITEA_API_URL=https://gitea.example.com/api/v1
GITEA_API_TOKEN=your_gitea_token_here

Variable	Description	Example
GITEA_API_URL	Gitea API endpoint (with /api/v1)	https://gitea.example.com/api/v1
GITEA_API_TOKEN	Personal access token	abc123...

Note: GITEA_REPO is configured at the project level in owner/repo format since different projects may belong to different organizations.

Generating a Gitea Token:

1. Log into Gitea → User Icon → Settings
2. Applications tab → Manage Access Tokens
3. Generate New Token with permissions:
   • repo (all sub-permissions)
   • read:org
   • read:user
   • write:repo (for wiki access)
4. Copy token immediately (shown only once)

NetBox Configuration

# ~/.config/claude/netbox.env
NETBOX_API_URL=https://netbox.example.com
NETBOX_API_TOKEN=your_netbox_token_here

Variable	Description	Example
NETBOX_API_URL	NetBox base URL	https://netbox.example.com
NETBOX_API_TOKEN	API token	abc123...

Git-Flow Configuration

# ~/.config/claude/git-flow.env
GIT_WORKFLOW_STYLE=feature-branch
GIT_DEFAULT_BASE=development
GIT_AUTO_DELETE_MERGED=true
GIT_AUTO_PUSH=false
GIT_PROTECTED_BRANCHES=main,master,development,staging,production
GIT_COMMIT_STYLE=conventional
GIT_CO_AUTHOR=true

Variable	Default	Description
GIT_WORKFLOW_STYLE	feature-branch	Branching strategy
GIT_DEFAULT_BASE	development	Default base branch
GIT_AUTO_DELETE_MERGED	true	Delete merged branches
GIT_AUTO_PUSH	false	Auto-push after commit
GIT_PROTECTED_BRANCHES	main,master,...	Protected branches
GIT_COMMIT_STYLE	conventional	Commit message style
GIT_CO_AUTHOR	true	Include Claude co-author

---

Project-Level Configuration

Create .env in each project root:

# Required for projman, pr-review (use owner/repo format)
GITEA_REPO=your-organization/your-repo-name

# Optional: Override git-flow defaults
GIT_WORKFLOW_STYLE=pr-required
GIT_DEFAULT_BASE=main

# Optional: PR review settings
PR_REVIEW_CONFIDENCE_THRESHOLD=0.5
PR_REVIEW_AUTO_SUBMIT=false

Variable	Required	Description
GITEA_REPO	Yes	Repository in owner/repo format (e.g., my-org/my-repo)
GIT_WORKFLOW_STYLE	No	Override system default
PR_REVIEW_*	No	PR review settings

---

Plugin Configuration Summary

Plugin	System Config	Project Config	Setup Command
projman	gitea.env	.env (GITEA_REPO=owner/repo)	/setup
pr-review	gitea.env	.env (GITEA_REPO=owner/repo)	/initial-setup
git-flow	git-flow.env (optional)	.env (optional)	None needed
clarity-assist	None	None	None needed
cmdb-assistant	netbox.env	None	/initial-setup
data-platform	postgres.env	.env (optional)	/initial-setup
viz-platform	None	.env (optional DMC_VERSION)	/initial-setup
doc-guardian	None	None	None needed
code-sentinel	None	None	None needed
project-hygiene	None	None	None needed
claude-config-maintainer	None	None	None needed
contract-validator	None	None	/initial-setup

---

Multi-Project Workflow

Once system-level config is set up, adding new projects is simple:

cd ~/projects/new-project
/setup

The command auto-detects that system config exists and runs quick project setup.

---

Installing Plugins to Consumer Projects

The marketplace provides scripts to install plugins into consumer projects. This sets up the MCP server connections and adds CLAUDE.md integration snippets.

Install a Plugin

cd /path/to/leo-claude-mktplace
./scripts/install-plugin.sh <plugin-name> <target-project-path>

Examples:

# Install data-platform to a portfolio project
./scripts/install-plugin.sh data-platform ~/projects/personal-portfolio

# Install multiple plugins
./scripts/install-plugin.sh viz-platform ~/projects/personal-portfolio
./scripts/install-plugin.sh projman ~/projects/personal-portfolio

What it does:

1. Validates the plugin exists in the marketplace
2. Adds MCP server entry to target's .mcp.json (if plugin has MCP server)
3. Appends integration snippet to target's CLAUDE.md
4. Reports changes and lists available commands

After installation: Restart your Claude Code session for MCP tools to become available.

Uninstall a Plugin

./scripts/uninstall-plugin.sh <plugin-name> <target-project-path>

Removes the MCP server entry and CLAUDE.md integration section.

List Installed Plugins

./scripts/list-installed.sh <target-project-path>

Shows which marketplace plugins are installed, partially installed, or available.

Output example:

✓ Fully Installed:
  PLUGIN                   VERSION    DESCRIPTION
  ------                   -------    -----------
  data-platform            1.3.0      pandas, PostgreSQL, and dbt integration...
  viz-platform             1.1.0      DMC validation, Plotly charts, and theming...

○ Available (not installed):
  projman                  3.4.0      Sprint planning and project management...

Plugins with MCP Servers

Not all plugins have MCP servers. The install script handles this automatically:

Plugin	Has MCP Server	Notes
data-platform	✓	pandas, PostgreSQL, dbt tools
viz-platform	✓	DMC validation, chart, theme tools
contract-validator	✓	Plugin compatibility validation
cmdb-assistant	✓ (via netbox)	NetBox CMDB tools
projman	✓ (via gitea)	Issue, wiki, PR tools
pr-review	✓ (via gitea)	PR review tools
git-flow	✗	Commands only
doc-guardian	✗	Commands and hooks only
code-sentinel	✗	Commands and hooks only
clarity-assist	✗	Commands only

Script Requirements

• jq must be installed (sudo apt install jq)
• Scripts are idempotent (safe to run multiple times)

---

Agent Model Selection

Marketplace agents specify their preferred model using Claude Code's model frontmatter field. This allows cost/performance optimization per agent.

Supported Values

Value	Description
sonnet	Default. Balanced performance and cost.
opus	Higher reasoning depth. Use for complex analysis.
haiku	Faster, lower cost. Use for mechanical tasks.
inherit	Use session's current model setting.

How It Works

Each agent in plugins/{plugin}/agents/{agent}.md has frontmatter like:

---
name: planner
description: Sprint planning agent - thoughtful architecture analysis
model: sonnet
---

Claude Code reads this field when invoking the agent as a subagent.

Model Assignments

Agents are assigned models based on their task complexity:

Model	Agents	Rationale
sonnet	Planner, Orchestrator, Executor, Code Reviewer, Coordinator, Security Reviewers, Performance Analyst, Data Advisor, Data Analysis, Design Reviewer, Layout Builder, Full Validation, Doc Analyzer, Clarity Coach, Maintainer, CMDB Assistant, Refactor Advisor	Standard reasoning, tool orchestration, code generation
haiku	Maintainability Auditor, Test Validator, Component Check, Theme Setup, Agent Check, Data Ingestion, Git Assistant	Pattern matching, quick validation, mechanical tasks

Overriding Model Selection

Per-agent override: Edit the model: field in the agent file:

# Change executor to use opus for heavy implementation work
nano plugins/projman/agents/executor.md
# Change model: sonnet to model: opus

Session-level: Users on Opus subscription can change the agent's model to inherit to use whatever model the session is using.

Best Practices

1. Default to sonnet - Good balance for most tasks
2. Use haiku for speed-sensitive agents - Sub-agents dispatched in parallel, read-only tasks
3. Reserve opus for heavy analysis - Only when sonnet's reasoning isn't sufficient
4. Use inherit sparingly - Only when you want session-level control

---

Automatic Validation Features

API Validation

When running /setup, the command:

1. Detects organization and repository from git remote URL
2. Validates via Gitea API: GET /api/v1/repos/{org}/{repo}
3. Auto-fills if repository exists and is accessible (no confirmation needed)
4. Asks for confirmation only if validation fails (404 or permission error)

This catches typos and permission issues before saving configuration.

Mismatch Detection (SessionStart Hook)

When you start a Claude Code session, a hook automatically:

1. Reads GITEA_REPO (in owner/repo format) from .env
2. Compares with current git remote get-url origin
3. Warns if mismatch detected: "Repository location mismatch. Run /setup --sync to update."

This helps when you:

• Move a repository to a different organization
• Rename a repository
• Clone a repo but forget to update .env

---

Verification

Test Gitea Connection

source ~/.config/claude/gitea.env
curl -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/user"

Verify Project Setup

In Claude Code, after restarting your session:

/labels-sync

If this works, your setup is complete.

---

Troubleshooting

MCP tools not available

Cause: Session wasn't restarted after setup. Solution: Exit Claude Code and start a new session.

"Configuration not found" error

# Check system config exists
ls -la ~/.config/claude/gitea.env

# Check permissions (should be 600)
stat ~/.config/claude/gitea.env

Authentication failed

# Test token directly
source ~/.config/claude/gitea.env
curl -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/user"

If you get 401, regenerate your token in Gitea.

MCP server won't start

# Check venv exists
ls /path/to/mcp-servers/gitea/.venv

# If missing, create venv (do NOT delete existing venvs)
cd /path/to/mcp-servers/gitea
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate

Wrong repository

# Check project .env
cat .env

# Verify GITEA_REPO is in owner/repo format and matches Gitea exactly
# Example: GITEA_REPO=my-org/my-repo

---

Security Best Practices

1. Never commit tokens

   • Keep credentials in ~/.config/claude/ only
   • Add .env to .gitignore

2. Secure configuration files

   chmod 600 ~/.config/claude/*.env
   

3. Never type tokens into AI chat

   • Always edit config files directly in your editor
   • The /setup wizard respects this

4. Rotate tokens periodically

   • Every 6-12 months
   • Immediately if compromised

5. Minimum permissions

   • Only grant required token permissions
   • Use separate tokens for different environments