Nexus Getting Started
Everything on this page happens inside Claude Code. You describe what you want, and Claude chooses the Nexus tools and skills for you. Each lesson gives an instruction to type, says what Claude does with it, and says what you will see.
Words in <ORANGE CAPITALS IN ANGLE BRACKETS> are placeholders. Replace them with something from your own project before you send the instruction.
Before you start, install Nexus and the plugin with the install guide. Then open a terminal in one of your projects and run claude.
You describe what you want in your own words, and you do not learn a command for each task. If you say "this test fails and I do not know why", Claude recognizes a debugging situation and uses the debugger agent. If you say "is what the docs say about caching true in the code", Claude plans a search across many documents. The /conexus:… commands in the lessons are shortcuts that start one skill or agent directly, and they are never required. The prompts here are examples of phrasing.
Index your repository, then search it
Indexing makes every later search possible. It reads your repository, cuts each file into chunks, and adds the chunks to the knowledge store. After that Claude answers questions about the code by searching for meaning, so it does not need to read many files.
Index
Index this repository into Nexus.
Claude runs the terminal command nx index repo ., and Claude Code shows a Bash tool call with that command. The command takes longer on a large repository. At the end the output shows Done. and, after the first index, a line with the number of topics that Nexus found.
If you index the same repository again later, Nexus skips files that did not change and shows skipped: index fresh for them.
Find out what is in the index
The first question after indexing works for every repository: what did Nexus find?
Which topics did Nexus find in this repository? List them with a short description of each.
Claude runs nx taxonomy list and describes each topic. Nexus names the topics in the background, so a topic can be unnamed at first. The topics are groups of related code that Nexus found by itself, and together they are a map of your repository. Pick one for the next step.
Search one topic
Use Nexus search to show me the main files for the topic "<TOPIC>", and explain in a few sentences what they do.Claude Code shows a tool call named search on the nexus server. The tool returns the best matching chunks with the file path and line number of each. Claude answers from those chunks and names the files. Each hit also carries a short id= of eight characters. A hit from a document that a newer document replaced says superseded by and names the newer one. Open one of the files to check that the answer is correct.
If Claude uses grep instead, say "Use Nexus search, not grep." Grep finds exact words. Nexus search finds meaning, so it also finds code that uses different words for the same idea.
Ask your own questions
Search works best with a question in normal language rather than a keyword. Three forms work for any repository:
Where in this codebase is <SOMETHING YOU KNOW EXISTS> handled? Is there any code in this repository that <DOES SOMETHING YOU ARE NOT SURE ABOUT>? Which files deal with <A CONCEPT>, and how are they connected?
Start with something you know exists, to check that Nexus finds it. Then ask about something you are not sure about. That is where semantic search helps most, because it finds code whose name you did not know.
From the terminal, a search is nx search "your question". Add --corpus docs to search only documentation, or --files to list only file paths.
Investigate further
- Ask Claude: "Search for <AN EXACT CLASS OR FUNCTION NAME> and include exact-text matches." Claude then also searches the exact-text indexes, which find a rare name that a search by meaning misses.
- Repo indexing: how files are classified and cut into chunks.
Add notes and documents to knowledge
The knowledge store is permanent, and Claude searches it by meaning. In lesson 1 you added a repository. Here you add a written note and a document, and you meet the catalog, which lists every document and the links between them.
A note in a subject collection
A collection is a named group of documents in the knowledge store, and its name is a subject.
Store this in Nexus knowledge, in the collection "<SUBJECT>", with the title "<SHORT-TITLE>": <A LESSON YOU LEARNED THAT IS TRUE BEYOND THIS PROJECT>
Example: collection distributed-systems, title idempotency-keys-per-tenant, text "Idempotency keys must be scoped per tenant. A global key space let two tenants collide in production."
A tool call named store_put on the nexus server, with the collection, the title, and the text. Claude confirms the document ID, and a search about that subject finds the note from any project.
Name a collection after a subject that will still exist in some years: distributed-systems, postgres, team-process. Do not name it after a session, a task, or a program. Nexus refuses the names knowledge, notes, default, tmp, and test. If you do not know the existing collections, ask Claude: "List the Nexus collections."
Documents
Index <PATH/TO/A-MARKDOWN-FILE.md> and <PATH/TO/A-PAPER.pdf> into Nexus.
Claude runs nx index md for the Markdown file and nx index pdf for the PDF. Every PDF goes to MinerU, which keeps layout, tables, and formulas. If you installed with --slim, the first PDF installs PDF support before it reads. Both documents are then in the knowledge store and in the catalog.
The catalog
Nexus adds every repository, note, and document to the catalog, and the catalog also records links between documents. A link has a type, for example cites, implements, or supersedes. Search finds text inside documents. The catalog answers two other questions: which documents exist, and how they are connected.
Which documents in the Nexus catalog are linked to <THE TITLE OF THE PAPER>?Tool calls on the nexus-catalog server, show or links. Claude lists the linked documents and the type of each link. A new install has few links. They appear when Nexus enriches documents and when an RDR cites a source.
From the terminal: nx store put, nx index md, nx index pdf, and nx catalog links "TITLE".
Investigate further
- Collections: the rules for collection names.
- Document catalog: all link types, and how to add a link yourself.
- Ask Claude: "Export the <SUBJECT> collection to a backup file." Claude runs
nx store export.
Explore: research, links, and the topic map
This lesson is the loop that Nexus is built for. You ask, Claude searches, you follow what it finds, and you connect it to other things, and the store gets better each time. The earlier lessons put things into Nexus. This one moves through what is there.
Research a subject
/conexus:research <A SUBJECT THAT YOUR PROJECT DEPENDS ON>Claude starts a research agent, which searches the knowledge store first, then the web, then your code. Claude Code shows the agent's tool calls: search, query, web searches, and at the end store_put. The result is a summary with sources. The findings are saved in the knowledge store, so the next search on that subject finds them.
Follow what you found
A research result names documents and files, and each one is a place to continue. Ask about one:
Open <ONE DOCUMENT OR FILE FROM THE RESULT> and tell me what else in the store is related to it.Claude calls show and links on the nexus-catalog server, and search for related chunks. It tells you what the document is, which documents link to it, and which are similar. Then you ask about one of those, and you move through the store from one document to its neighbours without knowing any names in advance.
Connect a document to code
Most links in the catalog appear on their own: an indexed paper cites other papers, and an RDR cites its sources. You add a link when you know a connection that Nexus does not.
Link <THE PAPER OR DESIGN DOCUMENT> to <THE FILE OR MODULE THAT IMPLEMENTS IT> with an "implements" link.
A tool call named link on the nexus-catalog server, with the two documents and the type implements. From then on a question about the design finds the code, and a question about the code finds the design. Ask "What implements <THE DESIGN DOCUMENT>?" and Claude follows the link.
Link types include cites, implements, supersedes, and relates. If you index papers, ask Claude to "enrich the <COLLECTION> collection with bibliographic data". Claude runs nx enrich bib, which looks up each paper and adds cites links.
Shape the topic map
The topics you saw in lesson 1 are not fixed. You can look at them, question them, and change them.
Show me the topic map for this project. Which topics appear in both the code and the documentation?
Claude runs nx taxonomy list and nx taxonomy hubs. The hubs are topics that connect several collections, and they are often the most important ideas in the project. You can then limit a search to one topic. Say "Search for <A QUESTION> inside the topic <TOPIC> only." Claude gives the topic to the search tool, which leaves out results from other topics.
When a topic is wrong, say so: "The topic <TOPIC> should be called <BETTER NAME>." Claude runs nx taxonomy rename. To move one chunk to a topic, say "Assign <CHUNK> to the topic <TOPIC>," and Claude runs nx taxonomy assign. To review every topic, run nx taxonomy review in the terminal, which goes through them one by one while you accept, rename, or merge each.
Investigate further
- Document catalog: all link types, and how links change search ranking.
- Topic taxonomy: how topics are found, labelled, and reviewed.
- Querying guide: how the
querytool follows links while it searches.
Questions that need many documents
Some questions need more than one or two searches. You might compare what the documentation says with what the code does, or collect one pattern from many files. For these, Claude has a tool that plans several steps and combines the results.
Compare what the documentation says about <A CONCEPT FROM LESSON 1> with what the code actually does.A tool call named nx_answer. It searches the documentation and the code, takes the relevant facts from each, compares them, and returns one answer with sources. This takes much longer than a normal search, so start it and do something else.
Use it when one search cannot hold the answer. For a simple question, a normal sentence to Claude is faster.
Other commands to know
Each command below starts one skill or agent directly. A skill is a named procedure that Claude follows for one kind of situation. An agent is a helper that Claude starts for one job. You can describe the task in your own words instead, and Claude chooses the same one.
| Task | Command |
|---|---|
| Understand a codebase that is new to you | /conexus:analyze-code |
| Plan a feature before you write code | /conexus:brainstorming-gate, then /conexus:create-plan |
| Review code before you commit it | /conexus:review-code |
| Debug a problem after two failed tries | /conexus:debug |
| Hand the work to the next session | /conexus:continuation, lesson 6 |
| Not sure which one | Ask Claude: "Which conexus skill or agent fits my task? Check the orchestration skill." |
Investigate further
- Querying guide: the four ways to search, and when to use each.
- Plugin README: all agents, skills, commands, and tools.
Record a decision with an RDR
An RDR (Research, Design, Review) is a short document you write before you write code. It records the problem, what you found out, the options, and the option you chose. Write one when a problem has more than one good solution or a bug needs a real cause. Write one too when a change affects something other people depend on. Indexing the repository makes every RDR searchable, drafts included, so a later search for a similar decision finds it.
/conexus:rdr-create
Claude creates the document with the status draft, writes the problem from your conversation, and gives it a number. You change a draft as often as you want. Working with RDRs follows one decision from this first command to its close.
Investigate further
/conexus:rdr-listand/conexus:rdr-show: read the RDRs that already exist in a project.- RDR: the full template, the sections, and the status values.
- The Nexus RDR directory: real examples, closed and open.
End a session, start the next one
One habit at the end of each session connects it to the next: a handoff file that says where the work stands.
When you close a session or type /clear, the conversation is gone, and a long conversation is compressed and loses detail. Memory keeps the facts and decisions across sessions, but not the answer to "where was I". That means the branch, what was half finished, and what to do first tomorrow. /conexus:continuation keeps that.
/conexus:continuation
Claude writes one file under /tmp that describes the state of the work. It records what was finished and where the state lives (the branch, the files, the memory entries, the task IDs). It adds the first commands for the next session, the open work and what blocks it, and the decisions the next session must keep. It also lists what the next session must not do. Claude then answers with three lines, and the third is a command that starts with cat /tmp/. Copy that line.
You: /conexus:continuation Claude: Paste this in the next session after /clear: cat /tmp/<HANDOFF-FILE>.md
Type /clear, or start a new session, and paste the copied line as the first message. Claude reads the file, checks the branch and the working tree, and continues the open work from where the last session stopped.
When to run it
Run /conexus:continuation in three cases, and in each case run it before you do the other thing.
| Case | How you notice it | Then |
|---|---|---|
| You are about to stop working | End of the day, a meeting, lunch, any time the terminal will wait for more than an hour. | Run it, then close the terminal or leave the session open. Both are fine. |
| You finished a task, or are about to change subject | The task is committed, or the next task is unrelated to the current one: a different branch, a different part of the system. | Run it, then type /clear and start the next task in the empty session. Paste the handoff later, when you return to the old subject. |
| The context window is filling | /context shows that most of the window is used, or Claude Code shows its warning, or Claude asks about things you told it an hour ago. The appendix explains the window. | Run it, then type /clear and paste the handoff. You lose nothing, and the session is fast again. You can also let Claude Code compact the session: the plugin writes a checkpoint before the compaction and puts it back after, so Claude keeps its place without a handoff. |
If you forget to run it, memory still has everything that was written to it. Start the new session and ask "What do you know about this project, and what was I working on?", and Claude answers from memory. The last continuation file is still in /tmp until the computer restarts, and Claude can find it if you ask.
You can give a topic, /conexus:continuation <TOPIC>, and the file is then named after it, which helps when you work on several things at once. The files live in /tmp and disappear when the computer restarts.
Investigate further
- Read the continuation file after Claude writes it, and tell Claude about any section that is empty or wrong before you close the session.
- The continuation skill: the exact list of sections Claude writes, and why the answer is three lines.
Keep Nexus healthy
Four things keep Nexus working: a health check, a backup before you update, the correct way to update, and a current index.
Health check
Run nx doctor and tell me if anything is wrong.
No line may show ✗. Read every ⚠ line. The line "Orphan uv install" means a copy of conexus installed with uv is still on disk. Right after nx self install that is normal, and Nexus removes the old copy at the next nx self install. Inside Claude Code, /conexus:nx-preflight checks the plugin in the same way.
Back up before you update
Back up the Nexus database.
Claude runs nx backup, which writes the local database to one file in ~/nexus-backups/ while the engine keeps running. The file is about as large as the database. Nothing runs a backup for you, not nx upgrade and not a hook, so ask for one before an update. If your store still holds old-format rows, Nexus refuses to start the engine until a backup taken after that refusal exists. A backup you took earlier does not count, and the message names the commands to run.
On a managed service, nx backup writes your own tenant to a .nxtenant file in the same folder, and it needs engine 0.1.191 or later. To check that file without contacting the service, run nx backup --check <FILE>.
Update
/conexus:upgrade
The skill shows what an update would change, then runs it. From the terminal the same update is two commands, nx self install and then nx upgrade, and you always run both.
Do not update with uv tool install conexus. A plain install builds a second copy that Nexus does not use. With --force it also takes the nx shims, so your terminal runs that copy without telling you. nx self install puts them back.
Keep the index current
Install the Nexus git hooks in this repository.
Claude runs nx hooks install, and after that git indexes the changed files after each commit. Without the hooks, say "Index this repository into Nexus" again after the code changes, and only the changed files are indexed.
Investigate further
- Ask Claude: "Show what nx upgrade would change, without running it." Claude runs
nx upgrade --dry-run. - Getting started: troubleshooting: more problems and their fixes.
Appendix: what sits underneath
You can use Nexus without reading any of this. Each part below explains something Claude does for you, and you can open it when a lesson makes you curious.
What Claude receives when a session starts
When you run claude in your project, the plugin hands Claude several blocks of text before your first message. Claude Code does not show them to you, but you can ask for them:
What context did the Nexus plugin give you at the start of this session?
| Block | Content |
|---|---|
| T2 Memory | The memory entries for this project. Empty in a new project. |
| Ready Beads | Open tasks from the bd task tracker, if the project uses it. |
| nx Capabilities | A short list of the Nexus tools that Claude can use. |
| Knowledge Map | The main topics in the knowledge store, with the number of documents in each. |
Not every project has every block. A project without the bd task tracker has no Ready Beads block, and a project without RDRs has no RDR block. A new install has an empty T2 Memory block and a short Knowledge Map.
The blocks are what Claude chooses from. The memory block tells Claude what was decided before, so it does not decide again from zero. The capabilities block tells Claude which tools exist, so it searches the store instead of reading every file. A guidance block describes situations such as "something is broken" or "an answer must come from many documents". It names an agent, a skill, or a tool for each.
If Claude reports a block with the heading "nx Preflight: FAILED", part of the install is missing. Type /conexus:nx-preflight and it tells you which part. If the nx command itself is missing, that command cannot run either, so type /conexus:setup and answer its question.
The three stores
Every Nexus tool works on one of three stores, and the stores differ in one thing only: how long the data lives.
Notes for the current session. Nexus deletes them when the session ends.
Facts and decisions about a project. Each entry has a project name and a title, and stays forever by default. You can give a temporary finding a shorter lifetime instead, and each read stretches it further.
Indexed code, documents, PDFs, and notes. Claude finds them with semantic search.
Claude does not have to go through scratch. It writes to each store directly. When a note turns out to matter for longer, Claude copies it to the next store, and the original stays. The scratch_manage promote tool copies a scratch note to memory. The nx memory promote command copies a memory entry to knowledge.
To choose a store, ask how long the data must live. Data for this session only goes to scratch. Data for this project, which you will look up by name, goes to memory. Data to keep permanently, which you will look up by meaning, goes to knowledge. You rarely choose yourself, because Claude does it as it works, and this rule lets you judge whether it chose well.
Storage tiers explains how a session is identified and how the lifetime of a memory entry grows with each read.
Memory and scratch
Memory is the store Claude fills for itself and reads first in every new session. It is not a to-do list and not a place for your own notes. As Claude works on a real task, it records what it decided and what it found. The helper agents that Claude starts write their results to the same store. The next day Claude refers to yesterday's decision without you repeating it. To check, ask "What do you already know about this project from earlier sessions?" In a brand-new project the answer is "nothing yet".
When Claude remembers something wrong, or does not know a fact that is not in the code, tell it as you would tell a colleague. Say "that was changed last week, we use X now". Claude updates the store, and you see a memory_put tool call. From the terminal, nx memory list -p PROJECT shows every entry for a project.
Scratch is the shared notepad of one session. When Claude starts helper agents to investigate a problem, each agent reads and writes the same scratch store, and that is how they coordinate. You see it as tool calls named scratch on the nexus server. Most scratch notes disappear when the session ends, which is the purpose of the store. Claude writes a finding that proved true to memory itself. A note it flags to keep is copied to memory when the session ends or moves to a new session. By default it goes to the memory project scratch_sessions. If a finding is worth keeping and Claude has not kept it, say "keep that". From the terminal, nx scratch list shows the notes of the current session.
Storage tiers: T2 and T1 have the details.
Rendering: one document from the stores
A rendering is one readable document that Claude writes from the current state of the stores. After some sessions the stores hold a lot about a subject, spread over findings in knowledge, decisions in memory, and links in the catalog. You ask for the whole picture as one document, you change it, Claude carries the changes back into the stores, and you ask again.
Render everything we have on <A SUBJECT YOU HAVE WORKED ON> as a Markdown document: what we know, what we decided, and what is still open.Claude collects the decisions with memory_search and memory_get, the findings with search and query, and the connections with links on the catalog. Then it writes one file. A Markdown file in the repository is easy to edit and commit, and a web page is easier to read and share.
Change the rendering in whichever way is easiest. Edit the file and tell Claude "I changed the section on <TOPIC>, update the stores". Or say what is wrong in conversation, or write comments on a web page and ask Claude to go through them. Claude then writes each change back to the store where it belongs. A corrected decision goes to memory with memory_put, a new finding goes to knowledge with store_put, and a new connection becomes a catalog link. Without that step the document and the stores diverge, and the next session works from the old state.
Later, ask for the rendering again, and it includes everything that changed since the last one. An RDR is a rendering of one decision with a fixed form and a lifecycle. Plan-centric retrieval explains how Claude collects material from several stores for one document.
The context window
Claude works with a fixed amount of text, called the context window. Everything in the session goes into it: your messages, Claude's answers, every file it read, and every command output. Nothing leaves by itself, so the window fills, and a full window costs you twice. Claude reasons less well when the useful text is buried between old tool outputs. When the window is full, Claude Code also compresses the conversation without asking. The compressed version loses detail, such as exact file names, the reason for a decision, and what was tried and failed.
/context
Claude Code shows how much of the window is used and what uses it. Look at it when a session has run for some time, or when an answer seems wrong. When the window is almost full, Claude Code shows a warning above the input line. That is the last good moment to run the handoff.
The habit that works is one task per session. Finish the task, run /conexus:continuation, type /clear, and start the next task in a window that holds only the handoff and the plugin's context. The handoff makes clearing safe, because everything you need is in the file or in memory.
Large file reads, long command outputs, and wide searches fill the window fastest. Ask Claude to read only the part of a big file that you need, and to summarize a long command output. /compact compresses by hand at a time you choose, which is better than automatic compression but still loses detail.
Words used on this page
| Index | To read documents, cut them into chunks, and add the chunks to the knowledge store. |
| Chunk | A piece of a document. Nexus cuts each document into chunks before it indexes them. |
| Semantic search | Search by meaning. The question and the chunks are compared as meanings, not as exact words. |
| Collection | A named group of documents in the knowledge store, for example distributed-systems. |
| Catalog | The list of all documents and the links between them. |
| Skill | A named procedure that Claude follows for one kind of situation. A command such as /conexus:rdr-create starts it directly. |
Complete
Search results and session context improve as you index and record more. Mail between sessions can arrive the moment it is sent, if you launch Claude Code with a channel flag. Tuple space: turning on push delivery has the steps.
Reference: Plugin README · CLI reference · Querying guide · RDR · Storage tiers