ai-nexus Documentation

Unified rule manager for Claude Code, Cursor, and Codex. Write once, use everywhere, save tokens.

Installation

Install ai-nexus globally with a single command:

$ npx ai-nexus install

Or use interactive mode for full control over what gets installed:

$ npx ai-nexus install -i

Quick Start

# Interactive setup (recommended)
npx ai-nexus install -i

# Quick install with defaults
npx ai-nexus install

# Use your team's rules
npx ai-nexus install --rules github.com/your-org/team-rules

# Install in current project only
npx ai-nexus init

Supported Tools

Commands

Browse Marketplace

Open a web-based marketplace to search, install, and remove rules with one click:

$ npx ai-nexus browse        # default port 3847
$ npx ai-nexus browse 8080   # custom port

The marketplace runs locally on http://localhost:3847 and provides:

• Community tab — browse and search all community rules with category filters
• My Rules tab — view installed rules and remove with one click
• Diagnostics tab — system health checks and rule source info
• Tool status cards — Claude Code, Cursor, Codex at a glance

Testing Rules

Preview which rules would load for a given prompt:

$ npx ai-nexus test "write a react component with hooks"

Selected rules (3):
  rules/essential.md
  skills/react.md

$ npx ai-nexus test --list    # show all registered keywords

How It Works

Claude Code: Semantic Router

A hook runs on every prompt, analyzing what rules you actually need:

• With AI routing (recommended) — GPT-4o-mini or Claude Haiku analyzes your prompt and picks the right rules. Cost: ~$0.50/month.
• Without AI (fallback) — keyword matching activates rules based on words in your prompt.

# Enable AI routing
export OPENAI_API_KEY=sk-xxx        # or ANTHROPIC_API_KEY
export SEMANTIC_ROUTER_ENABLED=true

Cursor: Rule Converter

ai-nexus converts .md rules to Cursor's .mdc format, adding description and alwaysApply metadata automatically. After conversion, Cursor's built-in semantic search handles rule filtering — ai-nexus does not run a router for Cursor.

Codex: Aggregated Rules

Individual rule files are aggregated into a single AGENTS.md file, which is loaded at session start. No dynamic loading.

Directory Structure

Install Modes

Symlink (default)

$ npx ai-nexus install

• Rules link to source — update syncs instantly
• Cannot edit rules directly (edit source instead)

Copy

$ npx ai-nexus install --copy

• Rules are independent copies
• Can edit locally
• update only adds new files, never overwrites

Rule Format

Rules are markdown files with optional frontmatter:

---
description: When to load this rule (used by semantic router)
---

# Rule Title

Your rule content...

Categories:

Team Rules

Share rules across your team via Git:

# Everyone installs from the same source
$ npx ai-nexus install --rules github.com/acme/team-rules

# When rules are updated
$ npx ai-nexus update

Creating a Rules Repository

Multi-Source Setup

Combine rules from multiple Git repositories:

# Base company rules
$ npx ai-nexus install --rules github.com/acme/base-rules

# Add frontend team rules
$ npx ai-nexus add github.com/acme/frontend-rules

# Add security rules
$ npx ai-nexus add github.com/acme/security-rules

# Update all at once
$ npx ai-nexus update

Community Registry

Browse and download community-contributed rules directly from GitHub — no npm publish needed.

# List all available rules
$ npx ai-nexus search

# Search by keyword
$ npx ai-nexus search react

# Download a rule
$ npx ai-nexus get react.md

# Specify category when name exists in multiple
$ npx ai-nexus get commit.md --category commands

Or use the web marketplace for a visual experience:

$ npx ai-nexus browse