nexus

module

v0.2.0 Latest Latest Go to latest Published: May 19, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/CarriedWorldUniverse/nexus

Links

Open Source Insights

README ¶

Nexus

A coordination layer for running multiple AI agents as a coherent team.

Nexus is a single central process (broker + orchestrator) plus a lightweight per-agent runtime. Agents register on boot, communicate through a shared message bus, and can invoke each other's stateless capabilities ("Hands") over that same bus. All context is owned by Nexus, not by the underlying AI provider — sessions live as tree-structured JSONL files, compaction is proactive, and rewind is a non-destructive tree operation.

Status

Early scaffold. The design is drafted in docs/2026-04-22-nexus-registration-spec.md (v0.4). No runtime code yet. See BUILD.md for the build plan and current step.

Shape

Nexus process — central broker (messaging + REST), orchestrator (polling, watches, alarms), and an embedded frame-agent. Single long-running process.
Agent runtime — one executable (agent) that reads an agent's home folder and runs it. Comms-first; no terminal attach, no direct user-to-agent bypass.
Three context modes per agent: global (one long-running session), thread (one session per chat thread), stateless (no persistence; the mode Hands live in).
Provider layer — the runtime is AI-agnostic. A provider module implements invoke / tokenCount / compact against a specific backend. v1 ships claude-api only; OpenAI and others are module-drops.
Hands — stateless, single-turn capabilities invoked via comms messages. An agent can call its own Hands to offload noisy subtasks, or another agent's Hands for cross-domain work. Audit trail is automatic because invocations flow through the same message bus as chat.

Design principles

Comms-first. Every interaction is a message on the bus. No agent is reachable outside the bus, which means every exchange is auditable, broker-logged, and visible to operators.
Context is Nexus's responsibility. The runtime owns session JSONL, not the provider. This keeps providers swappable and makes rewind, fork, branch-summary, and proactive compaction first-class operations rather than provider-specific features.
Registration is dynamic. Nexus doesn't know what agents exist at startup. Agents register with POST /aspects/register and announce their capabilities; the roster is a live runtime construct, not a config artifact. This is the honest prototype of federation: cross-Nexus is the same protocol over the wire.
Proactive over reactive. Compaction fires before the model degrades (tokens > window - reserve), not after. Rewind preserves history in-tree rather than truncating.

Cross-platform

Windows, Linux, and macOS. The runtime and Nexus process are built as Go single-static-binary executables — nexus and agent.

Repository layout

nexus/       central process (broker, orchestrator, embedded frame-agent, admin)
runtime/     agent.exe: providers, context persistence, comms dispatch, Hand dispatch
agents/      per-agent home folders (populated at migration time)
shared/      path resolution, auth, schemas
docs/        design specs and decision records
scripts/     build and launch helpers
tests/       end-to-end harness

See the README in each subdirectory for detail.

License

See LICENSE.

Status note

This repository is currently private. It will open once there's something usable to share — probably once the end-to-end Hand invocation path works and at least two agents can register and coordinate. See BUILD.md for where we are in that plan.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
relay-cli command Command relay-cli is the operator-facing CLI for the Frame-to-Frame relay (interchange).	Command relay-cli is the operator-facing CLI for the Frame-to-Frame relay (interchange).
internal
version Package version holds the build-time version string shared by every binary in this repo (nexus, agentfunnel, nexus-comms-mcp, nexus-imap-mcp, nexus-jira-mcp, nexus-watch, aspect, outpost, etc).	Package version holds the build-time version string shared by every binary in this repo (nexus, agentfunnel, nexus-comms-mcp, nexus-imap-mcp, nexus-jira-mcp, nexus-watch, aspect, outpost, etc).
nexus
aspects
autospawn Package autospawn scans a directory for aspect home folders and fires off a harness subprocess per aspect.	Package autospawn scans a directory for aspect home folders and fires off a harness subprocess per aspect.
broker Per-aspect bearer-token authentication and identity resolution.	Per-aspect bearer-token authentication and identity resolution.
chat
cmd/nexus command TLS cert bootstrap subcommand for nexus.	TLS cert bootstrap subcommand for nexus.
cmd/outpost command Command outpost is the Outpost relay binary.	Command outpost is the Outpost relay binary.
credentials Package credentials manages broker-mediated credentials for external services that aspects need to call (Anthropic, OpenAI, DeepSeek, Jira, IMAP, future kinds).	Package credentials manages broker-mediated credentials for external services that aspects need to call (Anthropic, OpenAI, DeepSeek, Jira, IMAP, future kinds).
frame Package frame holds the Nexus's Frame role: detection, embedding, admin surface, chat routing rules.	Package frame holds the Nexus's Frame role: detection, embedding, admin surface, chat routing rules.
frame/framecomms
frame/funnel Package funnel is the Frame's deliberation engine — the layer that owns context-window management, comms-inbox folding, summarization triggers, and the deliberation loop itself.	Package funnel is the Frame's deliberation engine — the layer that owns context-window management, comms-inbox folding, summarization triggers, and the deliberation loop itself.
frame/funnel/rewriter Package rewriter implements per-turn distillation of claude-code's session jsonl.	Package rewriter implements per-turn distillation of claude-code's session jsonl.
frame/route Package route codifies the Frame's chat-routing rules.	Package route codifies the Frame's chat-routing rules.
frame/templates Package templates renders the personality bundle (aspect.json + SOUL.md + CLAUDE.md + PRIMER.md) for a new Frame.	Package templates renders the personality bundle (aspect.json + SOUL.md + CLAUDE.md + PRIMER.md) for a new Frame.
frames Package frames defines the on-the-wire frame format used by every Nexus-component WebSocket connection (aspect↔Outpost, aspect↔Nexus, Outpost↔Nexus).	Package frames defines the on-the-wire frame format used by every Nexus-component WebSocket connection (aspect↔Outpost, aspect↔Nexus, Outpost↔Nexus).
handqueue Package handqueue implements the dispatcher's worker-execution queue per hand-dispatch v0.1 §2-§3: a fairness-scheduled FIFO queue with per-aspect active-worker tracking, soft-cap N, hard-ceiling H, and spillover for idle aspects.	Package handqueue implements the dispatcher's worker-execution queue per hand-dispatch v0.1 §2-§3: a fairness-scheduled FIFO queue with per-aspect active-worker tracking, soft-cap N, hard-ceiling H, and spillover for idle aspects.
identity
internal/testcerts Package testcerts mints a self-signed loopback cert + key on disk for tests that need a real TLS server.	Package testcerts mints a self-signed loopback cert + key on disk for tests that need a real TLS server.
issuenotify
jwt
knowledge Package knowledge implements the cross-session knowledge store per registration spec §2.8.	Package knowledge implements the cross-session knowledge store per registration spec §2.8.
observability Package observability is the shared core for nexus's per-aspect observability surface — the data layer that both the dashboard SPA and the nexus-watch terminal binary render.	Package observability is the shared core for nexus's per-aspect observability surface — the data layer that both the dashboard SPA and the nexus-watch terminal binary render.
observability/jsonlsink Package jsonlsink persists observability frames as JSONL files for retrospective debugging.	Package jsonlsink persists observability frames as JSONL files for retrospective debugging.
operator Package operator implements the operator-identity substrate for the dashboard-ws-port spec (2026-05-09).	Package operator implements the operator-identity substrate for the dashboard-ws-port spec (2026-05-09).
outpost Package outpost implements the per-host relay process.	Package outpost implements the per-host relay process.
roster Package roster holds the live set of registered aspects.	Package roster holds the live set of registered aspects.
sessions Package sessions owns Nexus's read-only mirror of aspect session trees.	Package sessions owns Nexus's read-only mirror of aspect session trees.
storage Package storage opens the Nexus SQLite database and runs the idempotent schema DDL.	Package storage opens the Nexus SQLite database and runs the idempotent schema DDL.
usage
relay Package relay implements the Nexus-side client for the Frame-to-Frame Relay protocol (v3 spec).	Package relay implements the Nexus-side client for the Frame-to-Frame Relay protocol (v3 spec).
runtime
agent Package agent implements the per-aspect runtime.	Package agent implements the per-aspect runtime.
aspect/wsasp
brokercreds Package brokercreds is the aspect-side client helper for fetching kind-typed credentials from the Nexus broker via the credential.fetch WS frame (NEX-77).	Package brokercreds is the aspect-side client helper for fetching kind-typed credentials from the Nexus broker via the credential.fetch WS frame (NEX-77).
cmd/agent command Command agent is the single-aspect runtime binary.	Command agent is the single-aspect runtime binary.
cmd/agentfunnel command
cmd/aspect command
cmd/nexus-comms-mcp command Command nexus-comms-mcp bridges nexus's WebSocket chat substrate to stdio MCP.	Command nexus-comms-mcp bridges nexus's WebSocket chat substrate to stdio MCP.
cmd/nexus-github-mcp command GitHub REST API client.	GitHub REST API client.
cmd/nexus-imap-mcp command
cmd/nexus-issue-mcp command Command nexus-issue-mcp bridges the in-process nexus issue tracker to stdio MCP.	Command nexus-issue-mcp bridges the in-process nexus issue tracker to stdio MCP.
cmd/nexus-jira-mcp command Command nexus-jira-mcp bridges Atlassian Jira REST to stdio MCP.	Command nexus-jira-mcp bridges Atlassian Jira REST to stdio MCP.
cmd/nexus-watch command Command nexus-watch is a terminal observer for one aspect's observability stream.	Command nexus-watch is a terminal observer for one aspect's observability stream.
cmd/nexus-wstest command Command nexus-wstest is a comprehensive WS frame tester that exercises every operator + aspect frame the broker exposes.	Command nexus-wstest is a comprehensive WS frame tester that exercises every operator + aspect frame the broker exposes.
compactor Package compactor implements the proactive compaction trigger per registration spec §2.7.	Package compactor implements the proactive compaction trigger per registration spec §2.7.
context/tree Package tree implements the tree-structured session JSONL format per registration spec §2.6.	Package tree implements the tree-structured session JSONL format per registration spec §2.6.
handexec Package handexec implements dispatch-mode execution for the harness binary.	Package handexec implements dispatch-mode execution for the harness binary.
keyfile
obsforward Package obsforward wires a remote aspect's funnel observability hook to the broker over the existing aspect WS connection.	Package obsforward wires a remote aspect's funnel observability hook to the broker over the existing aspect WS connection.
providers Package providers defines the Nexus Provider interface and the normalised types that flow across the adapter boundary.	Package providers defines the Nexus Provider interface and the normalised types that flow across the adapter boundary.
providers/claude-api Package claudeapi implements the Nexus provider contract against Anthropic's Claude API.	Package claudeapi implements the Nexus provider contract against Anthropic's Claude API.
providers/ollama-local Package ollamalocal implements the embeddings half of the Nexus provider contract against a locally-hosted Ollama instance.	Package ollamalocal implements the embeddings half of the Nexus provider contract against a locally-hosted Ollama instance.
wsclient Package wsclient is the aspect-and-Outpost-side WebSocket client.	Package wsclient is the aspect-and-Outpost-side WebSocket client.
scripts
check-chat command
check-knowledge command check-knowledge dumps row counts + a sample from knowledge in the current nexus.db.	check-knowledge dumps row counts + a sample from knowledge in the current nexus.db.
check-triage command check-triage prints the most recent rows from inbox_triage for diligence verification.	check-triage prints the most recent rows from inbox_triage for diligence verification.
cutover-smoke command Command cutover-smoke exercises the dashboard-ws-port surface against a running nexus.	Command cutover-smoke exercises the dashboard-ws-port surface against a running nexus.
delete-knowledge command delete-knowledge removes a single (from_agent, topic) entry.	delete-knowledge removes a single (from_agent, topic) entry.
dry-parse-aspect command
migrate-knowledge command migrate-knowledge copies the agent-network broker's `knowledge` rows into nexus.db's `knowledge` table.	migrate-knowledge copies the agent-network broker's `knowledge` rows into nexus.db's `knowledge` table.
nexus-tail command
smoke-e2e command Command smoke-e2e exercises the §6.4 cross-aspect stack end-to-end: spawns a Nexus, auto-starts a wren aspect from a test aspect dir, drives a `dispatch` frame over WS, asserts the `dispatch.result` round-trip — everything talks WS.	Command smoke-e2e exercises the §6.4 cross-aspect stack end-to-end: spawns a Nexus, auto-starts a wren aspect from a test aspect dir, drives a `dispatch` frame over WS, asserts the `dispatch.result` round-trip — everything talks WS.
shared
schemas Package schemas defines the on-the-wire shapes shared between the Nexus process and the agent runtime.	Package schemas defines the on-the-wire shapes shared between the Nexus process and the agent runtime.