Repo Nexus (rnex)

A simple, lightweight companion tool for multi-repo workflows. It links multiple independent repositories and shares universal AI instructions (like AGENTS.md) using standard Unix symlinks — without Git submodules, monorepo migrations, or complex setup.

• No Git Submodules or Nested Git Friction: Keep your repositories completely independent. No detached HEADs, no .gitmodules, and no merge conflicts between repos.
• A Lean Companion, Not a Workspace Replacer: It does not replace your editor, terminal, build tools, or package manager. It is a tiny (~20 KB) helper that seamlessly complements your existing workflow.
• Unified Workspace for AI Coding Assistants: Open one folder to give Cursor, Claude Code, GitHub Copilot, or Antigravity complete cross-repo visibility.
• Single Source of Truth for AI Guidelines: Share and sync AGENTS.md, Copilot instructions (.github/copilot-instructions.md), Cursor rules (.cursorrules), Claude instructions (CLAUDE.md), and custom prompts across all projects.
• Zero Dependencies: Pure POSIX shell CLI (rnex). Works out of the box with zero external runtimes required.

💡 Have questions? Check out the Frequently Asked Questions (FAQ) for architecture deep dives, Git workflows, and AI context strategies.

Table of Contents

• What Repo Nexus Is (and What It Isn't)
• How It Works: The Two Symlink Flows
• Key Principles
• Installation
• Quick Start
• Everyday Usage
• Plugins & AI Context Packs
• Workspace Configuration (rnex.yaml)
• CLI Command Reference
• Operating on External Workspaces via --config
• Supported AI Configuration Files
• Project Structure
• Running Tests
• Frequently Asked Questions (FAQ)
• License

What Repo Nexus Is (and What It Isn't)

How It Works: Zero-Touch Multi-Repo Architecture

┌─────────────────────────────────────────────────────────────┐
│  Repo Nexus Workspace Root                                 │
│                                                             │
│  my-workspace/                                              │
│    repos/                                                   │
│      backend/   ──(symlink)──>  ~/code/backend-api          │
│      frontend/  ──(symlink)──>  ~/code/web-app              │
│    AGENTS.md         (root universal AI instructions)       │
│    .rnex/            (plugins, rules, and workflows)        │
│    rnex.yaml         (manifest: repos_dir, plugins, repos)  │
│                                                             │
│  • Agent opens workspace → sees all repos in one tree.      │
│  • Edits through symlinks modify original files directly.   │
│  • Member repositories remain 100% clean and untouched.     │
└─────────────────────────────────────────────────────────────┘

Key Principles

1. No Git Submodules (Complete Repository Autonomy):
   Member repositories are never converted into Git submodules or subtrees. Each repository keeps its own standalone Git history, remotes, branches, and commits. rnex simply links them on your local filesystem.

2. Symlink Write-Through:
   Symlinks are transparent pointers resolved by your OS. When you or an AI agent edit repos/backend/src/index.ts, the OS resolves the link and writes directly to the source repository on disk.

3. Clean Member Repositories & Dedicated .rnex/ Scope:
   Member repository roots remain clean and unpolluted. By default, rnex creates a dedicated .rnex/ directory in each member repo (repos/<name>/.rnex/) to isolate all Repo Nexus documents, instructions, rules, workflows, and scripts. This setting is configurable per repository (rnex_dir: true|false) and can be disabled to leave a member repo 100% untouched.

4. Multi-Repo AI Context Discovery:
   Root AGENTS.md and .rnex/ govern workspace-wide AI assistant behavior, while AI tools operating at the workspace level inspect repos/<name>/.rnex/ for member-specific instructions without cluttering root codebases.

5. Dynamic Workspace Scope:
   Easily show or hide member repos from the active workspace without modifying disk contents.

Installation

Install rnex via npm, GitHub Packages, or the zero-dependency native installer:

Option 1: Via npm (Recommended)

npm install -g repo-nexus

(Installs both repo-nexus and rnex commands globally, or run via npx repo-nexus init)

Option 2: Via GitHub Packages

npm install -g @nu-nenoi/repo-nexus --registry=https://npm.pkg.github.com

Option 3: Native Installer (Zero Dependencies)

Clone the repository and run the built-in installer:

git clone https://github.com/nu-nenoi/repo-nexus.git
cd repo-nexus
./rnex install

(Installs rnex and repo-nexus symlinks into ~/.local/bin, or pass a custom directory like ./rnex install /usr/local/bin)

Option 4: Shell Alias

Add to your ~/.zshrc or ~/.bashrc:

alias rnex="/path/to/repo-nexus/rnex"
alias repo-nexus="/path/to/repo-nexus/rnex"

Quick Start

# 1. Initialize a new workspace
mkdir my-workspace && cd my-workspace
rnex init

# 2. Register repositories
rnex add backend ~/code/backend-api
rnex add frontend ../web-app          # relative paths work too

# 3. Check workspace health
rnex status

During rnex init, the CLI automatically scans for existing AI configuration files (like CLAUDE.md, .cursorrules, .github/copilot-instructions.md) and adds them to your config.

Everyday Usage

# Register a repository (links into scope & initializes member .rnex/ directory)
rnex add my-app ~/code/my-app

# Register a repository with .rnex/ disabled (100% untouched)
rnex add --no-rnex-dir my-app ~/code/my-app

# Inspect workspace health, active repos, and .rnex status
rnex status

# List all registered repositories with scope and .rnex status
rnex list

# Toggle .rnex directory integration for a member repo
rnex rnex-dir disable my-app
rnex rnex-dir enable my-app

# Temporarily hide a repo from active indexing/agent scope
rnex hide my-app

# Restore a hidden repo back to active scope
rnex show my-app

# Reconcile all scope links, plugins, and member .rnex/ directories
rnex sync

# Unregister a repository (removes scope link & member .rnex assets)
rnex remove my-app

Plugins & AI Context Packs

Repo Nexus features a zero-dependency plugin architecture. Plugins package curated AI instructions, agent behavioral rules, and architecture templates that are automatically synchronized into member repositories via symlinks.

# List available and active plugins
rnex plugin list

# Inspect plugin details and provided files
rnex plugin info karpathy-llm

# Enable a plugin across your workspace
rnex plugin enable karpathy-llm

# Disable a plugin and clean up injected files
rnex plugin disable karpathy-llm

Built-in Plugin: karpathy-llm

The karpathy-llm plugin packages Andrej Karpathy's verified LLM agent design patterns, context engineering principles, and the autonomous Karpathy LLM Wiki architecture (based on setup-karpathy-wiki.md, available locally in toolkit/prompts/setup-karpathy-wiki.md):

• Step 0 — Configuration Interview: Guides setup decisions including target agent instruction file (AGENTS.md, CLAUDE.md, .cursor/rules/wiki.mdc, etc.), wiki purpose (codebase, second brain, research, content archive), organization layout (flat vs structured), and automation enablement.
• The 4 Cardinal Agent Rules (.rnex/rules/KARPATHY_RULES.md):
  1. Think Before Coding: Formulate explicit assumptions, boundary checks, and trade-offs before writing code.
  2. Simplicity First: Minimal abstractions, readable implementations, zero speculative boilerplate.
  3. Surgical Changes: Minimal blast radius, preserved comments/docstrings, and tight diffs.
  4. Goal-Driven Execution: Upfront verification criteria, automated tests, and diff inspection.
• Autonomous Karpathy LLM Wiki Knowledge Architecture:
  • Intake (/raw/): Append-only intake for unmodified source documents.
  • Curated Knowledge Base (/wiki/): Interlinked atomic markdown pages with typed YAML frontmatter relations (sources, related, extends, contradicts, mentioned_in).
  • Control Index (/wiki/index.md): Master navigation index with lint_trigger: enabled|disabled toggle.
  • Rolling Context (/wiki/hot.md): ~500-word quick-orient context cache for AI agents.
  • Operation Log (/wiki/_log.md): Append-only audit trail of ingest and lint operations.
  • Session Counter (.rnex/.lint_trigger_counter): Machine-local state tracking session activity (gitignored).
• Autonomous Lint Trigger (.rnex/scripts/wiki-lint-trigger.sh): Session counter and maintenance alerts on session 1 and every 15 sessions.
• Standardized Workflows (.rnex/workflows/):
  • wiki-ingest.md: 8-step protocol decomposing raw source documents into 5–25 atomic wiki pages.
  • wiki-lint.md: 10-step protocol validating paths, recomputing mentioned_in, removing orphans, resolving contradictions, identifying gaps, suggesting source candidates, and rebuilding indexes.

Workspace Configuration (rnex.yaml)

The configuration file defines repo symlink directory, enabled plugins, and registered repositories:

# Directory for repository symlinks (relative or absolute)
repos_dir: ./repos

# Workspace plugins
plugins:
  karpathy-llm:
    lint_trigger_enabled: true

# Member repositories
repos:
  backend:
    path: /Users/dev/code/backend-api
    scope: visible
    rnex_dir: true      # default: true (creates repos/backend/.rnex/)
  frontend:
    path: ../web-app
    scope: visible
    rnex_dir: true
  analytics:
    path: /Users/dev/code/analytics
    scope: hidden
    rnex_dir: false     # disabled: leaves analytics repo 100% untouched

See docs/rnex.example.yaml for a comprehensive example with all options.
For common questions and architecture details, see the Frequently Asked Questions (FAQ).

CLI Command Reference

Global Options

Commands

Operating on External Workspaces via --config

Run rnex commands targeting any workspace without changing directories:

# Inspect status of a workspace stored elsewhere
rnex -c /path/to/my-workspace/rnex.yaml status

# Add a repository to an external workspace
rnex --config /path/to/my-workspace/rnex.yaml add api-service ~/code/api

Any command executed with an explicit config file operates within the directory where that config lives.

Project Structure

repo-nexus/
├── rnex.yaml                       # Workspace configuration
├── rnex                            # CLI executable (POSIX shell)
├── AGENTS.md                       # Universal AI coding guidelines
├── docs/
│   ├── AGENTS.sample.md            # Template for AGENTS.md
│   ├── FAQ.md                      # Frequently Asked Questions
│   └── rnex.example.yaml           # Full config reference with examples
├── .github/
│   ├── workflows/ci.yml            # GitHub Actions CI workflow
│   └── ISSUE_TEMPLATE/             # Bug report and feature request templates
├── tests/
│   └── test_cli.sh                 # Automated CLI test suite (20 tests)
├── toolkit/                        # Shared prompts, scripts, templates
├── package.json                    # npm package manifest
├── LICENSE                         # MIT License
└── README.md

Running Tests

./tests/test_cli.sh

License

MIT