Nexus Getting Started

Nexus gives Claude context before you type anything, and Claude Code does not show it to you. This lesson shows what that context contains, because it explains why Claude chooses the tools it chooses. It also introduces the three stores that every later lesson uses.

What Claude receives when the session starts

When you run claude in your project, the plugin hands Claude several blocks of text before your first message. You can see them by asking:

What context did the Nexus plugin give you at the start of this session?

Claude repeats the blocks. The important ones are these.

Not every project has every block. A project without the bd task tracker has no Ready Beads block, a project without RDRs has no RDR block, and a new install has an empty T2 Memory block and a short Knowledge Map. All of that is normal.

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.

Why Claude receives this context

Claude does not follow a fixed script. It reads the situation and chooses what to do, and the blocks above are what it 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 rather than commands: "something is broken", "a plan needs a check", "an answer must come from many documents". For each situation it names the skill that fits, and Claude matches your request to a situation and uses that skill by itself.

The same routing adapts to how you write. A person who types short instructions and a person who thinks in long paragraphs get the same tools, chosen from what they said. The prompts in these lessons are examples of phrasing, and your own words work the same way.

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.

Data moves in one direction only: scratch to memory, then memory to knowledge.

You rarely choose a store yourself. Claude does it as it works, following the plugin's guidance, and the rule above lets you read what Claude did and judge whether it was right.

One habit at the end of each session connects it to the next: a handoff file that says where the work stands. Learn it now, before the first real work, because every later lesson ends with it.

A Claude Code session holds only a limited amount of the conversation. When the conversation grows long, Claude Code compresses it and detail is lost, and when you close the session or type /clear, the conversation is gone. Memory (lesson 4) keeps the facts and decisions across sessions, but it does not keep the answer to "where was I": which branch, what was half finished, what to do first tomorrow. /conexus:continuation keeps that.

/conexus:continuation

Claude writes one file under /tmp that describes the state of the work, with the same sections every time:

• What was finished in this session: commits, closed tasks, memory entries written.
• Where the state lives: the branch, the files, the memory entries, the task IDs.
• The first actions for the next session, as commands that can be run without change.
• Open work, and what blocks it.
• Decisions from this session that the next session must keep.
• Things the next session must not do.
• What went wrong in this session, so the next one avoids it.

Claude then answers with only three lines, and the third line is a command that starts with cat /tmp/. Copy that line.

Type /clear, or start a new session, and paste the copied line as the first message. Claude reads the file, runs the first actions, and continues where the last session stopped. It also receives the memory block from lesson 1, so it has both the facts and the position.

When to run it

Run /conexus:continuation in three cases, and in each case run it before you do the other thing.

The context window

Claude works with a fixed amount of text, called the context window, and everything in the session goes into it: your messages, Claude's answers, every file Claude read, every command output, every search result, and the blocks the plugin added at the start. Nothing leaves by itself, so the window fills. A full window costs you twice. Claude reasons less well when the useful text is buried between old tool outputs, and when the window is full, Claude Code compresses the conversation without asking. The compressed version keeps the outline and loses the detail: exact file names, the reason for a decision, what was tried and did not work.

/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 also shows a warning above the input line, and that warning is the last good moment to run the continuation.

Large file reads, long command outputs, and wide searches fill the window fastest. If Claude is about to read a big file, ask for only the part you need, and if a command prints thousands of lines, ask Claude to summarize the output instead of showing it. This is the difference between a session that lasts an afternoon and one that is compressed before lunch.

/compact compresses by hand, at a time you choose, which is better than automatic compression but still loses detail. Continuation and /clear lose nothing, so prefer them.

If you forget to run it, memory (lesson 4) 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, if there was one, is still in /tmp until the computer restarts, and Claude can find it if you ask.

An example

The project is a small web service. The session fixed one bug and started a second one.

You:    /conexus:continuation

Claude: Paste this in the next session after /clear:

        cat /tmp/nexus-continuation-orders-api-2026-09-10.md

You copy the third line. Then you type /clear, or you close the terminal and come back the next day.

You:    cat /tmp/nexus-continuation-orders-api-2026-09-10.md

Claude: Reading the handoff.
        Finished yesterday: the timeout bug in the order endpoint (commit 4f2a91c,
        task orders-17 closed). Open: the duplicate-webhook bug, task orders-18,
        with the cause found (retries are not idempotent) and the fix not yet written.
        First actions from the handoff: I am on branch fix/orders-18, the tree is
        clean, and the memory entry webhook-idempotency has the analysis.
        Continuing with the fix. Starting with the test for the duplicate case.

Claude ran the first actions from the file: it checked the branch, checked that nothing was uncommitted, and read the memory entry the file named. Then it continued the open work, and you typed one line. The names in this example are invented, but the form is what you will see.

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. They are a handoff, and memory is the record.

Indexing is what makes every later search possible. It reads your repository and adds its chunks to the knowledge store, and after that Claude answers questions about the code by searching for meaning instead of reading 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 reads every file, cuts it into chunks, and stores the chunks, which takes a few minutes on a large repository. At the end the output shows Done. and, after the first index, the 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. The topics are groups of related code that Nexus found by itself, and together they are a map of your repository. Pick one that interests you 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.

Replace <TOPIC> with a topic from the list.

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, and Claude answers from those chunks and names the files. Open one of the files to check that the answer is correct.

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 and check that Nexus finds it. Then ask about something you are not sure about, because that is where semantic search helps most: 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.

Memory is the store Claude fills for itself and reads first in every new session. It holds facts and decisions about a project: a decision Claude made, a finding from an investigation, the state of the work at the end of a session. It is not a to-do list and not a place for your own notes. You work, and it fills.

How it fills

Spend a session with Claude on a real task: fix a bug, add a feature, investigate a question. As it works, Claude records what it decided and what it found, and if you close the session with /conexus:continuation (lesson 2), the state of the work is recorded too. Helper agents that Claude starts write their results to the same store.

Each entry has a project name and a title, and stays forever unless Claude gives it a shorter lifetime. When it does, each time Claude reads the entry, that lifetime stretches further, so facts that stay useful stick around and facts that nobody reads still expire.

How you notice it

Start a new session on the same project the next day, and Claude already knows what was decided. You see it in how it answers: it refers to yesterday's decision without you repeating it. To check directly, ask in any words you like, for example:

What do you already know about this project from earlier sessions?

Claude answers from the memory block it received at session start, and may call memory_search or memory_get for details. In a brand-new project the answer is "nothing yet".

When you correct it

Sometimes Claude remembers something that is wrong or out of date, or does not know a fact that is not in the code, such as a decision made in a meeting. Tell it in conversation, the way you would tell a colleague: "that was changed last week, we use X now" or "for the record, the team decided Y". Claude updates the store, and you see a memory_put tool call. No special phrase is needed.

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. Nexus deletes it when the session ends. You do not write to it, but it helps to know that it exists and what it looks like while in use.

Where you see it

Give Claude a task with several steps, such as an investigation of a bug with more than one possible cause, or /conexus:analyze-code on part of the codebase. Between the searches and file reads you see tool calls named scratch on the nexus server, which are Claude and its agents writing hypotheses and partial results for each other. When the task ends, the notes have done their job.

To see what is in there, ask in any words: "what have you noted so far", "what are the agents finding". Claude lists the notes.

What survives the session

Most scratch notes disappear at the end, which is the purpose of the store. A hypothesis that proved true does not stay a scratch note: Claude promotes it to memory during the session, or marks it and the plugin copies it to memory at session end. You see this as a scratch_manage call with the action promote. If you think a finding is worth keeping and Claude has not kept it, say so in passing. "Keep that" is enough.

From the terminal, nx scratch list shows the notes of the current session.

The knowledge store is permanent, and Claude searches it by meaning. In lesson 3 you added a repository. In this lesson 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

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 from then on a search about that subject finds this note from any project.

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. Nexus picks a PDF reader from the content, and a paper with many formulas goes to a reader that keeps them. A scanned PDF needs the OCR reader named, so if the paper is a scan, tell Claude. 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".

This lesson is the loop that Nexus is built for. You ask, Claude searches, you follow what it finds, you connect it to other things, and the store gets better each time. The lessons before this one put things into Nexus and took them out again. 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, and the findings are saved in the knowledge store so that the next search on that subject finds them.

Good subjects are the consensus protocol your database uses, the retry rules of an API you call, or a library your build depends on. Choose something you want to understand better, not something you already know.

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. This is how you move through the store, from one document to the documents near it, 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 3 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: "Search for <A QUESTION> inside the topic <TOPIC> only." Claude gives the topic to the search tool, and results outside it are left out.

When a topic is wrong, say so: "The topic <TOPIC> should be called <BETTER NAME>" or "Assign <DOCUMENT> to the topic <TOPIC>." 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.

A rendering is one readable document that Claude writes from the current state of the stores, and it is how most design work with Nexus is done. 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. The document and the stores stay in agreement.

Ask for a rendering

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 material with memory_search and memory_get for the decisions, search and query for the findings, and links on the catalog for what is connected. Then it writes one file. The result is not a copy of the entries but a structured document, written for a reader, from what the entries say.

Ask for the form you prefer. A Markdown file in the repository is easy to edit and commit, and a web page, which Claude Code can publish as an artifact, is easier to read and share. Both are renderings of the same state.

Change it

Read the rendering, and where it is wrong or incomplete, change it in whichever way is easiest:

• Edit the file directly, then tell Claude: "I changed the section on <TOPIC>, update the stores."
• Say what is wrong in conversation: "the second decision is out of date, we dropped that in March", "add the constraint about <X>", "this section is too long".
• On a web page, write comments on the parts you disagree with and ask Claude to go through them.

Claude changes the document, 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. You see those tool calls after the file edit. This step is what keeps the stores correct. Without it the document and the stores diverge, and the next session works from the old state.

Ask again

Later, after more work, ask for the rendering again. Claude writes it from the current state, so it includes everything that changed since the last one: what you edited, what the sessions between decided, what the research found. Compare it with the previous rendering to see the change.

Some questions need more than one or two searches: compare what the documentation says with what the code does, or collect one pattern from many files. For these, the plugin has a skill that plans several steps and combines the results.

/conexus:query Compare what the documentation says about <A CONCEPT FROM LESSON 3> 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: half of these calls take about 80 seconds and one in twenty takes over three minutes, so start it and do something else.

Use /conexus:query when one search cannot hold the answer. For a simple question, a normal sentence to Claude is faster. You can also ask the large question in plain words, and Claude recognizes it and plans the search without the command.

Other commands to know

Each command below starts one skill directly. You can describe the task in your own words instead, and Claude chooses the same skill. The commands are for when you want to be sure which skill runs.

This lesson is the short version. The full practice, from the first conversation to the close across many sessions, has its own page: Working with RDRs.

An RDR 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. When you close an RDR, Nexus indexes it into the knowledge store, so when you or Claude later work on a similar decision, the old RDR appears in search.

When to write one

• The problem has more than one good solution.
• A bug needs a real cause, not a quick fix.
• The change affects something that other people depend on.

Do not write one when the reason is clear from the code.

The steps

/conexus:rdr-create             # create the document, status Draft
/conexus:rdr-research add 12    # add a finding, with a tag that says how sure you are
/conexus:rdr-gate 12            # optional: automatic checks and a critique
/conexus:rdr-accept 12          # lock the decision

Replace 12 with the number that rdr-create gives you. Make the RDR as long as the decision needs. For a bug fix, three sections are enough: Problem, Root Cause, Fix. The full template is for large design decisions with real options.

Three things keep Nexus working: a health check, the correct way to update, and a current index.

Health check

Run nx doctor and tell me if anything is wrong.

Every line must show ✓. One line may say "credentials not set", which is normal for a local install. Inside Claude Code, /conexus:nx-preflight checks the plugin in the same way.

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.

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.

By default, a message that arrives while you are away from the keyboard waits until your next message to Claude, when a hook delivers it. Claude Code can instead push it into the session the moment it arrives. That needs a channel flag on every launch, and nothing Nexus installs can set that flag for you, so this lesson is the one manual step.

Add the launch flag

Two forms exist. Use the first if you can; it needs one more step, below, but shows no dialog once that step is done.

claude --channels plugin:conexus@nexus-plugins

claude --dangerously-load-development-channels server:nexus

The second form works everywhere the first does. It asks for a one-keystroke confirmation at every single launch, and Claude Code does not remember your answer between launches.

Skip the confirmation dialog

The first form shows no dialog once the plugin is on Claude Code's channel allowlist. That allowlist is Anthropic's own list, or your own allowedChannelPlugins setting. On macOS, an administrator writes the setting once:

sudo tee "/Library/Application Support/ClaudeCode/managed-settings.json" >/dev/null <<'JSON'
{"channelsEnabled": true, "allowedChannelPlugins": [{"marketplace": "nexus-plugins", "plugin": "conexus"}]}
JSON

This setting applies to the whole machine, not one project. Ask whoever manages your machine if you cannot write to /Library/Application Support/ClaudeCode/ yourself.

Make it stick

A flag applies to one launch only, so add it to how you already start Claude Code.

alias claude='claude --channels plugin:conexus@nexus-plugins'

Add this line to ~/.zshrc, or the equivalent file for the shell or launcher you use, then open a new terminal. Every later claude then carries the flag without you typing it.

Check it worked

At startup, Claude Code shows a line reading "Channels (experimental) messages from plugin:conexus@nexus-plugins inject directly in this session · restart without --channels to stop." A warning line under it names anything wrong with the allowlist.

Run nx doctor and tell me what the channel row says.

The tuples.channel_delivery row names whether the waiter is alive, when it last woke, how many messages it has announced in total, and how many are still pending. A launch with no flag at all, or a session whose waiter has not run yet, reports an informational line with no record at all.

Without the flag

Nothing breaks. A message still arrives, at your next prompt, through the hook that runs on every prompt whether or not the channel is on. Push delivery only removes the wait, and it needs the flag on every launch to do that. Channels are a Claude Code research preview, and are not available on Amazon Bedrock, Google Cloud Agent Platform, or Microsoft Foundry.