ContextDX Plugins — Installation and Usage Guide

Analyze your codebase or infrastructure architecture and sync it to ContextDX Portal for collaborative architecture boards.

---

Overview

Two plugins are available, each self-contained with configuration, sync, and status commands:

Install whichever is relevant to your project. Each plugin includes:

• /configure — Set up ContextDX Portal credentials
• /analyze or /analyze-infra — Run architecture analysis
• /sync — Push analysis results to ContextDX Portal
• /status — Check analysis and sync status

---

Installation

From Marketplace

BASHCopy
# Install the code analysis plugin
claude plugin install code-analysis@contextdx-plugins

# Install the infrastructure analysis plugin
claude plugin install infra-analysis@contextdx-plugins

Scope Options

Example:

BASHCopy
claude plugin install code-analysis@contextdx-plugins --scope project

From Local Path

If you have the plugin source locally:

BASHCopy
claude --plugin-dir /path/to/plugins/code-analysis

---

Configuration

Before analyzing or syncing, configure your ContextDX Portal credentials.

Step 1: Get Credentials from ContextDX

1. Go to ContextDx UI → your workspace
2. Navigate to Sources → Add Source → select Board Builder
3. Fill in the required fields and save (an API secret is auto-generated)
4. Open the target workboard → Sources panel → Bind Source
5. Select your BoardBuilder source and enter a branch name (e.g., main)
6. Copy the Binding Token and API Secret

Step 2: Store Credentials

Choose one of these methods:

Environment Variables (recommended for CI/CD)

BASHCopy
export BOARDBUILDER_TOKEN="your-base64-binding-token"
export BOARDBUILDER_SECRET="bb_your_api_secret"
export BOARDBUILDER_BRANCH="main"

Config File (recommended for local development)

Create .contextdx/config.json in your project root:

JSONCopy
{
  "bindingToken": "your-base64-binding-token",
  "apiSecret": "bb_your_api_secret",
  "branch": "main",
  "baseUrl": "https://api.contextdx.dev"
}

Step 3: Run /configure

/configure

This command:

• Detects credentials from env vars or .contextdx/config.json
• Writes .claude/contextdx.local.md (used by sync and hooks)
• Tests the API connection
• Verifies .gitignore includes credential files

Step 4: Protect Credentials

Add these to your .gitignore:

.contextdx/
.claude/*.local.md

---

Code Analysis Workflow

For JavaScript/TypeScript, Python, Java, Go, C#, Ruby, and Rust projects.

1. Analyze

/analyze

Or target a specific path:

/analyze src/backend

This scans your codebase and produces .contextdx.json containing:

• Nodes — Components classified as service, api, database, component, queue, or external
• Edges — Relationships: imports, database operations, API calls, message queue patterns
• Metadata — Languages, frameworks, tech stacks detected

2. Sync

/sync

Pushes the analysis results to ContextDX Portal. Reports how many nodes and edges were created or updated.

For incremental updates that only push changes:

# Smart sync is available via the CLI
npx contextdx-sync --config .claude/contextdx.local.md --analysis .contextdx.json --smart-sync

3. Check Status

/status

Shows:

• Configuration details (API URL, branch)
• Analysis summary (node/edge counts by type)
• Sync status (last sync, pending changes)

---

Infrastructure Analysis Workflow

For AWS CDK TypeScript projects.

Requirements

Your project must have:

• cdk.json in the project root
• aws-cdk-lib in package.json dependencies

1. Analyze

/analyze-infra

Or target a specific path:

/analyze-infra infra/

This scans your CDK project and produces .contextdx-infra.json containing:

• Nodes — AWS resources (Lambda, S3, DynamoDB, API Gateway, SQS, SNS, ECS, and more), CDK stacks, and custom constructs
• Edges — Relationships: permission grants, event triggers, API integrations, data access patterns, cross-stack references
• Metadata — Stacks, framework, language, region

2. Sync

/sync

Pushes the infrastructure analysis to ContextDX Portal.

3. Check Status

/status

Shows infrastructure analysis summary and sync state.

---

Auto-Sync

Enable automatic change tracking so modified files are flagged for re-analysis.

Edit .claude/contextdx.local.md and add autoSync: true to the YAML frontmatter:

YAMLCopy
---
bindingToken: your-token
apiSecret: bb_your_secret
baseUrl: https://api.contextdx.dev
branch: main
autoSync: true
---

When enabled, every file edit in Claude Code appends the changed file to the analysis file's pendingChanges array. Run /analyze or /analyze-infra again to re-analyze changed files, then /sync to push updates.

---

Troubleshooting

"ContextDX not configured"

Run /configure to set up credentials. Make sure you have either:

• Environment variables set (BOARDBUILDER_TOKEN, BOARDBUILDER_SECRET, BOARDBUILDER_BRANCH)
• A .contextdx/config.json file in your project root

"Configuration file not found"

The sync command expects .claude/contextdx.local.md to exist. Run /configure first — it creates this file from your credentials.

"Invalid apiSecret format"

The API secret must start with bb_. Check that you copied the full secret from the ContextDX UI.

401 Unauthorized

Your bindingToken or apiSecret is invalid or expired. Regenerate credentials in the ContextDX UI and run /configure again.

400 Branch Mismatch

The branch in your configuration doesn't match the branch configured in the workboard binding. Update your config to use the correct branch.

"No code analysis found" / "No infrastructure analysis found"

Run /analyze (for code) or /analyze-infra (for infrastructure) before running /sync or /status.

"This is not a CDK project"

The /analyze-infra command requires cdk.json and aws-cdk-lib in your project. If you're analyzing application code instead of infrastructure, use /analyze.

Plugin commands not showing up

Make sure you loaded the plugin correctly:

BASHCopy
# Check that the plugin directory has .claude-plugin/plugin.json
ls /path/to/plugin/.claude-plugin/plugin.json

# Load with --plugin-dir
claude --plugin-dir /path/to/plugin

Commands are loaded at session start — restart Claude Code after installing or updating plugins.