Tensegrity

Post 00 of the Nexus series: install the CLI, install the plugin, take a short tour. Post 0 explains what you have installed; this post just gets it on your machine.

---

This post takes a fresh laptop to a working Nexus install in about ten minutes. Nothing in here requires an API key or an account. Cloud mode is optional and covered at the end.

Nexus has two install surfaces:

• The nx Command Line Interface. The Nexus CLI, a Python package that indexes repositories, searches them, and manages the storage tiers from the command line. Runs locally without an account (optional cloud mode is available, free-tier and highly recommended).
• The Claude Code plugin. Layers on top of the Nexus CLI, giving the conversation access to 28 MCP tools, 43 skills, and 13 specialized agents. Routes English intent to the right tool, plan, or agent.

The CLI alone is useful; the plugin is what makes the agent team available inside Claude Code. Most readers will want both. The sections below cover each in turn.

Prerequisites

Install the following before running the Nexus install commands below:

• Python 3.12 or 3.13. Python 3.14 is not yet supported (a Pydantic upstream issue). Check yours with python3 --version. If you need to install 3.13, uv will handle it: uv python install 3.13. See uv’s Python install guide for details.
• uv. The Python package manager Nexus is installed with. Install uv with curl -LsSf https://astral.sh/uv/install.sh | sh, or see the installation guide for other platforms.
• git. You probably already have it. If not: brew install git (macOS), apt install git (Ubuntu/Debian), or the downloads page.
• Node.js. Required only if you install the Claude Code plugin (most readers will). The plugin spawns its sequential-thinking MCP server via npx, which silently fails to start without node and npm on PATH. Install: brew install node on macOS, apt install nodejs npm on Ubuntu/Debian, or the Node.js installer for other platforms.
• Claude Code. The host environment for the plugin. Install instructions cover macOS, Linux, and Windows. The nx CLI alone does not need it; the rest of this series assumes you have it.
• Beads. Recommended companion. The plan and RDR workflows the rest of the series describes track work in beads, and the plugin’s preflight check expects bd on PATH. See the Beads install guide. Optional for first-time CLI use; skip it now if you just want a tour.

Preflight check

Before installing Nexus, verify the prerequisites are on PATH:

python3 --version    # 3.12.x or 3.13.x
uv --version
git --version
node --version       # only if you want the plugin
bd --version         # only if you installed Beads
claude --version     # only if you want the plugin

Anything that errors with “command not found” needs installing before you continue.

Command-line interface

Install the nx CLI:

uv tool install conexus

The PyPI package is conexus; the CLI binary is nx. Verify:

nx --version
nx doctor

nx doctor is the canonical health check. It verifies the Python version, the installed conexus version, the storage mode (local ONNX or cloud), and (in cloud mode) credential presence and reachability. A healthy local-mode install looks like:

Nexus health check:

  ✓ Python ≥ 3.12: 3.13.x
  ✓ conexus version: 4.15.0 (latest)
  ✓ T3 mode: local
  ✓ ChromaDB (local persistent): reachable

In cloud mode, you also see ChromaDB (CHROMA_API_KEY): set, Voyage AI (VOYAGE_API_KEY): set, and per-collection pipeline rows. Anything marked ✗ is fixable from the same line: nx doctor prints the install or config command for the failure.

Two gotchas worth flagging:

• nx: command not found after install means ~/.local/bin is not on your PATH. Add it to your shell rc (export PATH="$HOME/.local/bin:$PATH") and reload.
• Crash on startup with a Pydantic v1 error means the tool was installed under Python 3.14. Fix: uv python install 3.13 && uv tool install conexus --force --python 3.13.

To upgrade later: uv tool update conexus.

Plugin

The plugin lives at github.com/Hellblazer/nexus and is installed from inside Claude Code:

/plugin marketplace add Hellblazer/nexus
/plugin install nx@nexus-plugins

Verify everything is wired up:

/nx:nx-preflight

This is one slash command that checks the nx CLI, nx doctor, bd, uv, node/npx, and your project’s CLAUDE.md. All rows should report PASS. If any fail, the output names the install command you need to run.

The plugin gives Claude Code:

• 3 MCP servers (nexus, nexus-catalog, sequential-thinking) exposing 28 tools for semantic search, storage-tier access, plan-template lookup, and catalog graph traversal.
• 43 skills routing English intent to retrieval, the RDR lifecycle, planning, code review, and architectural design.
• 13 specialized agents for critique, audit, planning, research synthesis, implementation, and validation.
• 23 slash commands as direct entry points for the workflows above (/nx:rdr-research, /nx:rdr-gate, /nx:review-code, /nx:create-plan, and the rest).

You do not need to invoke these directly; the skills route intent to the right tool or agent. I tend to type the RDR slash commands explicitly to signal intent, but a natural-language request like “Create an RDR that does X and Y” lands on /nx:rdr-create without the slash command.

Companions worth knowing about. I also run a small sn plugin alongside nx that wires up two upstream MCP servers I rely on heavily: Serena for LSP-precise symbol navigation (find references, type hierarchies, safe rename), and Context7 for current library and framework docs (used in place of training-data recall). Neither is required for Nexus, but they pair well — the agents in the post-6 measurements reach for Serena before grep and Context7 before guessing API shapes. You’ll see serena/find_symbol and context7/query-docs show up in the top MCP-tool counts there.

Short tour

A few minutes of dogfooding before you read the rest of the series. It’s not much, but it’s worth the time.

Index a repository

cd your-project
nx index repo .

The first run classifies every file (code, prose, RDR), chunks it, and embeds it. Local mode uses bundled ONNX embeddings: no API keys, no network. After indexing, Nexus auto-discovers topics across the corpus and labels them:

nx taxonomy status

You see a per-collection summary: topic counts, document counts, when discovery last ran. nx taxonomy review lets you accept, rename, merge, or split topics interactively. You can skip that for now, but it is worth revisiting later.

Search

Semantic search by intent, not exact strings:

nx search "how does authentication work"
nx search "retry logic" --hybrid
nx search "database pool" --corpus code

--hybrid adds keyword matching via ripgrep; --corpus code restricts to code. Results are grouped by topic and ranked by relevance plus git frecency. Common flags: -n 20 for more results, --files for paths only, -c to show the matched text. --hybrid requires ripgrep on PATH (brew install ripgrep on macOS, apt install ripgrep on Ubuntu/Debian).

Structured memory across sessions and contexts

The substrate’s three storage tiers each carry context across a different lifetime. All three are usable from the CLI:

# T1: within-session
nx scratch put "bug in retry logic"
nx scratch search "retry"

# T2: project memory
nx memory put "rate limit 10k/min" -p app
nx memory search "rate limit" -p app

# T3: cross-project knowledge
echo "use Postgres" | nx store put - -t db
nx search "Postgres" --corpus knowledge

The agent team writes to and reads from the same tiers during work. When you tell the conversation to “remember that the rate limit is 10k/min,” it calls memory_put underneath. The next session (same project, fresh claude invocation, possibly a different machine) sees the note immediately when the agent calls memory_search. The conversation does not need to be re-briefed.

Three lifetimes, three jobs:

• T1 coordinates agents inside one session. A skill seeds context, the dispatched agent reads it, downstream operators read it again.
• T2 bridges context across sessions and Claude instances. Standing rules, project state, decisions, plan templates. Survives until you delete the entry.
• T3 bridges context across projects. Indexed code, prose, RDRs, papers. Lives until the catalog is reset.

Nothing the developer or the agent team learns has to be re-explained the next time around.

Use Nexus from Claude Code

Open Claude Code in your project. The plugin’s MCP tools and skills are now available to the conversation. Try a few things:

• “What does our retry logic look like?” The conversation searches T3 and returns the relevant code with citations.
• “Remember that the vendor’s API rate limit is 10k requests per minute.” The conversation calls memory_put so the note is there next session.
• “I want to brainstorm an approach for migrating to JWT auth.” The brainstorming-gate skill fires, the substantive-critic engages, an RDR draft starts.

You do not need to invoke the MCP tools or dispatch the agents yourself. The skills should route intent for you. The substrate stays under the surface; you stay in English. Of course, your style may vary.

In practice, prompting Claude explicitly to search the knowledge base (“search T3 for…”) is worth the habit. It reinforces that semantic memory is available and keeps retrieval from being skipped on questions where it would help.

Try an RDR

RDRs (Research-Design-Reviews) are an opinionated protocol for how Nexus tracks the reasoning behind technical decisions: the problem, the research, the chosen approach, and the rejected alternatives. They live in docs/rdr/ alongside the code. These documents form the interface to your LLM. The RDR protocol is a document-oriented command-and-control mechanism for agentic coding. It is not just for producing code; it is for the entire ecosystem of development. RDRs integrate with the rest of Nexus and are linked throughout the knowledge base, forming the foundation of your LLM conversational work.

To start one from the conversation:

/nx:rdr-create your-topic-here

The skill scaffolds an RDR file from the template, registers it in T2, and opens a research session. Companion commands:

/nx:rdr-list             # list all RDRs
/nx:rdr-show 042         # show RDR-042
/nx:rdr-research add 042 # add findings
/nx:rdr-gate 042         # finalize gate
/nx:rdr-accept 042       # accept it
/nx:rdr-close 042        # close it

Post 3 in this series walks the lifecycle in detail. For now, knowing the verbs create / research / gate / accept / close is enough.

The quality of the output tracks the quality of the input. RDRs that record real research, real constraints, and real alternatives produce better-implemented code than RDRs written to check a box. The gate step (/nx:rdr-gate) is where the substantive-critic agent reads the draft and argues with it before any code is written; the critique is the checkpoint, not an optional review.

The developer’s contribution to this loop is the upstream work: architecture, design, analysis, documentation, rationale. The more thinking goes into the RDR, the more the agent team’s downstream implementation, review, and validation has to work with.

From accept to done

/nx:rdr-accept is not the end of the workflow. It is the moment the planning chain fires automatically. The chain runs three steps in sequence: the strategic-planner agent decomposes the RDR into a bead epic with N child task beads (each with dependencies); the nx_plan_audit MCP tool validates the plan against the live codebase; the nx_enrich_beads MCP tool fills in execution context (file paths, code patterns, test commands) for each task. The result is a tracked work graph rooted at the RDR, ready to execute.

If you have not used Beads before, the short version: a bead is a task issue with dependencies, persisted across sessions in a Dolt-backed database that you, the agent team, and the next session can all see. The CLI is bd. The plugin and the agent team rely on it heavily.

To find work that has no blockers and is ready to start:

bd ready

This lists task beads whose dependencies are all closed. Claim the one you want:

bd update <bead-id> --claim

Then drive the implementation from inside Claude Code:

/nx:implement <task description from the bead>

/nx:implement reads the active in-progress bead from bd list, dispatches the developer agent in TDD mode, runs the implementation, and pauses for review. After implementation, run a review pass:

/nx:review-code
/nx:test-validate

When the work is verified and committed, close the bead and pick up the next ready task:

bd close <bead-id>
bd ready

Cycle through the epic until every task is closed. When the last task closes, the epic auto-closes, and you finish the RDR with:

/nx:rdr-close <NNN>

Optionally with a post-mortem note about how the implementation actually went versus what the RDR predicted.

The flow looks heavy when written out, but most of it runs underneath. The actual rhythm is: write the RDR, gate it, accept it, then for each task bd ready → /nx:implement → /nx:review-code → bd close. Repeat until the epic is done, then /nx:rdr-close. The agent team handles the rest.

Advanced topics

For most readers, the local storage mode is enough. Cloud mode is the recommended next step: the embedding quality is materially better and the addition of a code-specific model (voyage-code-3) noticeably sharpens code search. Both required services have generous free tiers.

When you are ready for more:

• Cloud mode. Upgrades the local ONNX MiniLM (384d) to Voyage AI’s voyage-3 / voyage-context-3 (1024d, cross-chunk context, reranking). Requires ChromaDB Cloud and Voyage AI accounts (both have generous free tiers). Run nx config init for the interactive setup, then nx doctor to verify.
• Catalog. Once you have indexed multiple corpora, nx catalog setup builds the typed-link graph that knits decisions to code to research. Post 2 covers it.
• Plan library. Saved retrieval templates the matcher pulls back for paraphrased questions. Post 4 covers it.
• PDFs. nx index pdf paper.pdf --collection knowledge__papers indexes a paper with bibliographic metadata extraction (authors, year, citations). The same machinery works on RDRs from other repos: nx index rdr ../other-project.
• Cross-project knowledge. A single catalog can span every repository you work on. Indexing multiple repos populates one knowledge graph that the plugin queries in one step.

Going deeper

• Getting Started: the canonical setup doc, deeper than this post.
• CLI Reference: every command, every flag.
• Configuration: config keys, environment variables, tuning.
• Storage Tiers: T1, T2, T3 architecture.
• RDR Overview: the decision-tracking workflow.

What the rest of this series does

This post got Nexus on your machine. The rest of the series opens the substrate one piece at a time, starting with the conceptual overview and working out toward the architectural details:

• Post 0: How I actually use Nexus: the conceptual overview. Cross-domain knowledge work, the two cooperating teams, the substrate that stays out of the way.
• Post 1: Nexus, by example: a worked session against the Delos corpus showing the moving parts cooperating on a real research question.
• Post 2: Typed links and the catalog: the graph that knits the corpora together.
• Post 3: Decisions as indexed data: RDRs as first-class graph nodes, not static markdown.
• Post 4: Plans, not replanning: the plan library as a growing asset, not a maintenance burden.
• Post 5: Operators as building blocks: the DAG primitives that compose into reusable analytical flows.
• Post 6: The substrate, measured (forthcoming): what 2,300+ sessions show the system actually doing.

Up next

Post 0: How I actually use Nexus: the conceptual overview of what you have just installed. The shape of the substrate, the two cooperating teams, and why the agents stay under the surface.