nxsflow
ende
All guides
nexus-flow

Getting Started

nxs is the umbrella of the nexus-flow suite. It is one binary carrying three building blocks — flow (nxf: projects, tasks, dependencies), memory (nxm: durable project knowledge) and chat (nxc: agent-to-agent coordination) — over one shared store. You install it once and then decide, per workspace, which of the three to activate.

This guide takes you from nothing installed to a workspace whose agent restores its own context at the start of every session. It is the one place that first setup is written down; the building blocks' own guides start from here.

Install

curl -fsSL https://nxsflow.com/nxs/install.sh | sh

The script detects your platform, verifies the download — a sha256 and a signature — and installs one program: nxs. The other names are symlinks to it: nxf, nxm and nxc are the same binary, which decides which persona it is from the name you typed. That is why the four can never drift apart in version — there is only one program to update.

Signature verification needs either minisign or an OpenSSL that can do Ed25519. A stock macOS has neither (its openssl is LibreSSL), so either install minisign — brew install minisign — or bootstrap with NXF_INSECURE=1, which checks the sha256 alone and proves integrity but not origin. nxs self-update verifies signatures unconditionally from then on.

nxs --version

Set up a workspace

A workspace is a .nxs/ directory in your project: one store that every activated building block writes into. Create it with:

nxs init

On a real terminal this asks which building blocks you want, with the arrow keys. A block's own sub-configuration runs inside that frame — flow asks which plugin to use, because that choice decides the vocabulary you will read and write for the life of the workspace.

On an agent, or in a script, name the blocks instead of being asked:

nxs init --module flow --module memory --json

Either way you land on the same workspace. To activate another block later, run nxs init again and tick it — the command is idempotent and adds rather than replaces.

What nxs init leaves behind

Four things, and it is worth knowing all four:

  • .nxs/ — the workspace itself: one SQLite store that every active block folds its own views over. It is git-ignored and local to this machine.
  • The shared agent file — the AGENTS.md section each active block contributes, assembled into one document rather than three competing ones. Not CLAUDE.md: that belongs to the host running the hook below, which has already delivered the same thing.
  • One SessionStart hook per active block — nxf prime, nxm prime, nxc prime.
  • An entry with the background service — the workspace is added to the list that service attends, so a deferral or a window declared here has something that will actually look at it. It is a local index entry and nothing more: it does not sync anything anywhere, and nothing is sent off this machine. nxs sync unregister takes it back off the list.

The workspace goes through each of them in detail.

The background service, and the question init asks about it

One process per machine keeps the deadlines of every workspace it attends, and syncs the ones that are bound to a stream. Without it, a deferral that comes due in this project simply never fires — which is why nxs init offers, on a real terminal, to set it up:

Set up the nexus-flow background service on this machine?

Say no and the answer is recorded in this workspace, so no later nxs init asks again; the frame still tells you where the service stands, and nxs sync daemon install sets it up whenever you change your mind. In a script or under --json the question is never asked and nothing is installed: name it explicitly with nxs init --service, or settle it with nxs init --no-service.

The installer is macOS-only (it is a launchd agent). Everywhere else, run nxs sync daemon in the foreground under your own supervisor — systemd, runit, whatever you already have — and it keeps exactly the same deadlines.

What restores context at the start of a session

The hooks are one per active block, not one for the umbrella — and that is a deliberate reversal of the earlier shape. The host truncates each hook's output on its own, at 10,240 bytes, so three hooks carry three budgets instead of one. That was measured, not assumed: three blocks' hooks of roughly 8 KB each arrived whole, 24 KB between them, where one combined hook would have been cut off at 10 KB.

nxs prime still exists, and it is still the fan-out:

nxs prime

It runs the prime verb of every active block and hands back one answer — flow's board, memory's index, chat's channel — in a fixed order, with a single shared now, so a deferred date means the same thing to every block in the same run. That is what you type when you want the whole picture in one place. The session hooks simply no longer go through it.

Either way the effect is the one that matters: an agent starts a session already knowing what this project is doing, what it has learned, and who else is working on it. A flow-only workspace yields exactly flow's prime; memory appears the day you activate memory. Nothing is configured for that — the hook set is derived from the active blocks.

Which block do I reach for?

Short version: flow for what needs doing, memory for what the project knows, chat for agents talking to each other. Modules is the longer answer, and it is worth reading before the three detail guides.

Where to go next

flow — what needs doing

The issue tracker of the suite: items, the dependencies between them, due and defer dates, an append-only note stream, and the reason each item was closed. That is the record of what a project is doing, and why.

One property separates it from a list of tickets, and it is worth knowing before anything else: the work list is derived, not stored. nxf next and nxf blocked are computed from the dependency graph at the moment you ask for them, so they cannot go stale and cannot disagree with the graph. Nothing sets an item to actionable; closing its last prerequisite is what makes it so.

That shapes the first move. It is not "write a task" — it is record what exists, and what it waits on:

nxf create --type feature --title "Ship the 1.0 release" --priority P1
nxf dep add <item> <prerequisite>
nxf next

What an item is comes from a plugin: the types you may create, the vocabulary you read and write, and the ranking policy behind next. The choice is made once per workspace, because it shapes everything you type afterwards — a coding project's issue tracker and a personal to-do list are the two that ship, and both drive the same engine.

Every command answers --json with byte-stable output, and that is the surface agents build on: an agent can drive the whole board without a human reading a table first.

Where to go from here

  • Getting started — from an empty directory to a planned, tracked piece of work.
  • Core concepts — items, dependencies, and how the two lanes are derived rather than stored.
  • Deferring and waiting — the one distinction that is easy to get wrong: a real calendar date, versus waiting on something that has to ship first.

memory — what the project knows

Durable facts that outlive the session which learned them: a convention, a gotcha, the reason a decision went the way it did. nxm remember writes one, nxm recall <key> reads it back in full, and a stable key lets a fact be corrected in place rather than accumulating contradictory copies of itself.

The point is not storage but replay. Memories are handed back at the start of every session, so the next agent begins already knowing what the last one learned. Nothing about that is a search problem: there is no model on the write path, no embedding and no similarity ranking, so the same store answers the same way today and in six months.

The first step is one line, and the discipline it starts is a hard rule the session banner repeats: durable project knowledge goes into nxm remember and nowhere else. A MEMORY.md, or any other file invented for the purpose, is never read back — the knowledge in it is silently lost.

nxm remember "The four cargo gates run in CI, not locally" --key gates
nxm memories                  # the index — one line per memory
nxm recall gates              # one memory, in full

What arrives is that index, not the memories themselves: one line each, saying what the memory says. That is why the line is worth writing carefully — nobody looks up a rule before breaking it, so the index line has to state it.

Where to go from here

  • Getting started — what memory needs before it can run, and your first remembered fact.
  • Core concepts — keys and auto-keys, the three registers, the retrieval rule, and the tombstone.
  • Agents and MCP — the memory_* tools an MCP host gets, and where an agent writes.

chat — how agents coordinate

The channel between the agents working in one workspace. nxc send --to <handle> starts something, nxc reply --thread <id> answers it, and --escalate is how an agent says I cannot instead of guessing.

Chat is a substrate, not a chat app, and the difference is the whole reason it exists. A message is not in flight: it is a row in the same workspace store flow and memory write to, so it is durable, it syncs with everything else, and it is replayed rather than remembered. There is no daemon to run and no server to point at. That is also the rule agents are given at session start — never coordinate through scratch files or ad-hoc notes: they are not delivered, not synced, and never replayed.

Who may be addressed, and how a group of agents proceeds, is declared rather than configured. A persona file per agent under .nxs-personas/ gives it an identity, its prompt layers, a model band, its tools, and who is allowed to address it; a channel declares a group — and an ordered one (flow: sequential) is the workflow, not a description of one.

nxc send --to <handle> "<what needs doing>"   # a thread id comes back
nxc reply --thread <id> "<the answer>"

Because agents run unattended, the limits are part of the design and not an afterthought: a hop cap so a conversation cannot ring forever, a human gate in front of what an agent does not decide, and a lease on the working copy so two agents cannot edit one checkout at the same time.

Where to go from here

  • Getting started — declare a persona and get your first answer back.
  • Personas and channels — the two declarations, and the ordered channel that carries a flow.
  • Limits and safety — the hop cap, the human gate, and what an agent does not decide.

Build on it, or help build it

Everything above this point answers how do I use this. This part answers how is it built, and what may I build on — and there are two doors, both open.

Build on it. nexus-flow is a library first. An app links nexus-flow-facade, holds one Engine, and reads exactly the lanes the CLI reads — in-process, with no subprocess and no daemon in between. That is not a claim the repository leaves to prose: examples/tauri-board/ is a small, real desktop app that does it in about 120 lines of Rust and one HTML file. Its window lists the work and re-renders on its own whenever anything else writes to the same workspace, because it subscribes to the engine's change stream instead of polling. If you are here to put your own interface on top, that example is the shortest way in.

Help build it. The project takes contributions. The engine, the CLIs, the guides you are reading and the tests that keep them honest all live in one Cargo workspace, and the whole quality bar is four commands you can run on your own machine — the next page lists them, and says which of them CI runs when. The seams are documented rather than guessed at, which is what the pages below are for.

The two doors share a first step: get the source, build it, and run something. Getting started is that step, for both cases.

Where to go from here

Type to search. Matches are found by wording and by meaning, so a section can answer a question it does not spell out.