Skip to content

docs: refresh README for Developer Preview #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NoraSoong merged 1 commit into from
Aug 12, 2026
Merged

docs: refresh README for Developer Preview #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
249 changes: 117 additions & 132 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,208 +1,193 @@
# Nexus
<p align="center">
<img src="packaging/AppIcon-master.png" width="96" alt="Nexus app icon">
</p>

[![Verify](https://github.com/NoraSoong/Nexus/actions/workflows/verify.yml/badge.svg)](https://github.com/NoraSoong/Nexus/actions/workflows/verify.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Swift](https://img.shields.io/badge/Swift-6.3-orange.svg)]()
[![macOS](https://img.shields.io/badge/macOS-14%2B-lightgrey.svg)]()
<h1 align="center">Nexus</h1>

[中文说明](README.zh.md)
<p align="center">
A local-first context compiler for coding assistants on macOS.
</p>

Nexus is a local-first trusted work-context layer for coding assistants on macOS.
<p align="center">
<a href="https://github.com/NoraSoong/Nexus/releases/tag/v0.1.0-preview.1">Download Developer Preview</a>
·
<a href="README.zh.md">中文说明</a>
·
<a href="https://github.com/NoraSoong/Nexus/issues">Issues</a>
</p>

It turns requirements, API examples, SQL, logs, source files, and human notes into a concise, reviewable, source-backed **Context Pack**, then carries later code changes forward as separate evidence. Once approved, that context is available to coding assistants such as Codex and Claude through MCP without injecting every raw material by default.
<p align="center">
<a href="https://github.com/NoraSoong/Nexus/actions/workflows/verify.yml"><img src="https://github.com/NoraSoong/Nexus/actions/workflows/verify.yml/badge.svg" alt="Verify"></a>
<a href="https://github.com/NoraSoong/Nexus/releases"><img src="https://img.shields.io/github/v/release/NoraSoong/Nexus?include_prereleases&label=preview" alt="Preview release"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="Apache 2.0 license"></a>
<img src="https://img.shields.io/badge/platform-macOS%2014%2B-lightgrey.svg" alt="macOS 14 or later">
</p>

> Status: pre-alpha Apple Silicon Developer Preview. The preview DMG includes a private Node Runtime and MCP Helper, but it is not Developer ID signed or notarized.
> **Status:** pre-alpha Apple Silicon Developer Preview. The preview DMG includes a private Node.js Runtime and MCP Helper. It is not Developer ID signed or notarized.

## Why Nexus
Nexus helps a coding assistant understand **what you are working on, which materials are authoritative, what remains uncertain, and what changed in the code workspace**.

Opening another assistant conversation preserves chat history, but it does not reliably answer:
It turns selected requirements, API examples, SQL, logs, source files, and notes into a short, reviewable, source-backed **Context Pack**. After you approve it, Codex, Claude, and other MCP-compatible assistants can read the current context without receiving every raw material by default.

- which source is authoritative now;
- which claims are facts, assumptions, or unresolved questions;
- which local materials an assistant may read;
- which parallel work item belongs to each worktree;
- how to keep growing context short and traceable.
Nexus does not replace your coding assistant. The assistant explores and edits code; Nexus keeps the work context clear, bounded, and portable between tools and workspaces.

Nexus does not manage agents or take over Git. It manages the work context between them that otherwise becomes lost, ambiguous, or stale:
## The Core Loop

```mermaid
flowchart LR
Materials["Messy materials"] --> Draft["Model-generated draft"]
Materials["Selected materials"] --> Draft["Prepared draft"]
Draft --> Review["Human review"]
Review --> Pack["Approved Context Pack"]
Pack --> MCP["Controlled MCP projection"]
MCP --> Assistants["Coding assistants"]
Assistants --> Git["Workspace code changes"]
Pack --> MCP["Controlled MCP context"]
MCP --> Assistant["Codex / Claude / other assistants"]
Assistant --> Git["Workspace changes"]
Git --> Draft
```

Model output is always a draft. It affects MCP only after explicit approval.
Model output is always a draft. It changes the context exposed through MCP only after explicit user approval.

## Current Capabilities
## Why Nexus

- Native SwiftUI Mac app with a menu-bar entry and quick switching;
- Work creation, editing, archive, restore, and delete flows;
- local files and pasted text with per-material assistant visibility;
- streamed UTF-8 and UTF-16 text extraction with per-source budgets and a 64 MiB hard safety limit;
- DeepSeek and OpenAI preparation with provider-specific keys in macOS Keychain; DeepSeek supports Flash for everyday work and Pro for more complex material;
- per-request short source citations (`S1`, `S2`, ...) are model-only metadata that Nexus resolves back to immutable source IDs before saving and never exposes to users or assistants;
- one automatic compact retry when a model reaches its output limit;
- source-backed objectives, scope, facts, constraints, acceptance criteria, assumptions, and questions;
- Context Pack review, diff, approval, and source-change freshness;
- Git repository, branch, and existing worktree association, plus commit and working-tree activity since the confirmed baseline;
- separate material freshness and code activity, so ordinary coding does not make requirement context stale;
- workspace bindings that pin different worktrees from one repository to different Work items;
- explicit workspace association errors that explain when to choose another worktree;
- read-only stdio MCP Helper with layered confirmed context, source freshness, workspace activity, and streamed paginated material reads;
- no Nexus tools while the app is not running or assistant access is paused.
Opening another assistant conversation preserves chat history, but it does not reliably preserve:

Nexus does not run coding agents or decide implementation strategy. It never switches, merges, or deletes code automatically; after explicit confirmation, it can create a standard Git worktree and bind the new directory to the current Work.
- which source is authoritative now;
- which claims are facts, assumptions, or unresolved questions;
- which local materials the assistant may read;
- which worktree belongs to which parallel Work;
- what changed since the last confirmed context.

## Requirements
Nexus is the context layer between your development materials, code workspaces, and existing coding assistants. It is intentionally not an agent runner, a full Git client, or a project-management system.

For the Developer Preview, use an Apple Silicon Mac running macOS 14 or later. Node.js is bundled with the DMG and is not required for normal use.
## What You Can Do Today

Source-development baseline:
- Create and switch lightweight Work items from a native SwiftUI Mac app and menu bar;
- add local files or pasted text and choose which materials assistants may read;
- prepare a compact Context Pack with DeepSeek or OpenAI;
- review facts, constraints, acceptance criteria, assumptions, questions, and sources before approval;
- keep material freshness separate from code activity;
- see commits and working-tree changes since the confirmed context;
- associate an existing code directory or create a standard isolated Git worktree;
- pin different worktrees from one repository to different Work items;
- expose one compact, read-only context through a bundled stdio MCP Helper;
- read visible text materials on demand with bounded, paginated access.

- macOS 14 or later;
- Xcode 26.5 / Swift 6.3.2;
- Node.js `v26.5.0`, pinned in [`.node-version`](.node-version);
- npm `11.17.0`.
Nexus never switches, stashes, resets, commits, merges, pushes, or deletes user code automatically.

The MCP Helper uses `node:sqlite`; it does not depend on the system SQLite CLI or a third-party native addon.
## Download

## Build and Run
For the current preview, download **[Nexus-0.1.0-preview.1-arm64.dmg](https://github.com/NoraSoong/Nexus/releases/download/v0.1.0-preview.1/Nexus-0.1.0-preview.1-arm64.dmg)** from the [GitHub Release](https://github.com/NoraSoong/Nexus/releases/tag/v0.1.0-preview.1).

Build the Apple Silicon Developer Preview DMG:
Requirements:

```bash
scripts/build-preview.sh
scripts/verify-preview.sh
```
- Apple Silicon Mac;
- macOS 14 or later;
- no separate Node.js installation is required.

The DMG is written to `dist/preview/`. The build downloads the pinned official Node Runtime, verifies its SHA-256 checksum, and embeds it in `Nexus.app`; the runtime is not committed to this repository.
The preview is unsigned and notarized neither by Developer ID nor by the Mac App Store. macOS may require the usual local-preview confirmation when opening it for the first time.

The preview is not Developer ID signed or notarized. macOS may require opening it from Finder with the usual local preview confirmation.
## Try It

Build and test Swift:
1. Open Nexus from Applications and open its main window from the menu bar.
2. Create a Work with a title and a one-sentence goal.
3. Add a few relevant files or a pasted text note. Mark only the materials the assistant may read.
4. Choose **Prepare Current Work**, inspect the material selection, and review the generated draft.
5. Answer or correct the questions, then explicitly approve the Context Pack.
6. Connect your MCP client once. The client can then read the current context through the stable Helper path.
7. When code changes later, Nexus shows them as evidence for a future update. It does not silently rewrite the confirmed context.

```bash
swift build
swift test
```
## MCP Setup

Build the MCP Helper:
The Developer Preview installs a stable Helper path on first launch. It includes its own Node.js Runtime, so users do not need Node.js or a SQLite CLI:

```bash
cd adapters/mcp
npm ci
npm run build
```text
~/Library/Application Support/Nexus/bin/nexus-mcp
```

Run the development Mac app:
For Codex:

```bash
.build/debug/NexusMac
```

Nexus stores local data in:

```text
~/Library/Application Support/Nexus
codex mcp add nexus \
-- "$HOME/Library/Application Support/Nexus/bin/nexus-mcp"
```

Users do not configure a database path or environment variable. `NEXUS_HOME` exists only for isolated development tests.

## Basic Workflow

1. Start Nexus and open its main window from the menu bar.
2. Create a Work item with a title and one-sentence goal.
3. Optionally choose an existing code directory, or let Nexus create an isolated one.
4. Drop relevant files or add pasted text.
5. Choose which materials assistants may read.
6. Add an optional note when the materials do not capture recent progress or caveats.
7. Choose **Prepare Current Work** and review the included, excluded, and truncated sources.
8. Review the generated draft, answer critical questions, or correct the wording.
9. Approve it explicitly. The main **Current Context** card updates immediately, and assistants read that version.
10. Later commits or uncommitted changes appear as code activity. They update confirmed context only after another explicit preparation and approval.

An approved Context Pack can be expanded in the main workspace to inspect its full content and sources. The optional note is only an input to future preparation, not a structured status form.

## MCP Helper

When Nexus is installed from the Developer Preview DMG, the first app launch automatically installs the bundled Helper into the user's Nexus Application Support directory and creates the stable command path below. No Node.js installation or manual Helper script is required.

For source development only, install the development helper shim:
To pin a client to a particular code directory:

```bash
scripts/install-helper.sh
codex mcp add nexus-workspace \
-- "$HOME/Library/Application Support/Nexus/bin/nexus-mcp" \
--workspace /path/to/worktree
```

Default location:
The preferred read-only tools are:

```text
~/Library/Application Support/Nexus/bin/nexus-mcp
```
- `get_current_development_context`: one compact object containing confirmed context, material freshness, and workspace activity;
- `read_context_material`: bounded, on-demand reads of visible text materials.

Nexus exposes no context while the app is not running or assistant access is paused. See the [assistant rules example](docs/agent-rules.md) for guidance on when an assistant should consult Nexus.

Check the Helper:
Diagnostics:

```bash
"$HOME/Library/Application Support/Nexus/bin/nexus-mcp" --version
"$HOME/Library/Application Support/Nexus/bin/nexus-mcp" --doctor
```

`--doctor` reports the Helper version, MCP SDK version, private Node version, SQLite adapter, database, app runtime, and projection compatibility.
## Parallel Workspaces

Example Codex configuration:
One Git directory can only have one checked-out branch at a time. For parallel Work items in one repository, create separate directories instead:

```bash
codex mcp add nexus \
-- "$HOME/Library/Application Support/Nexus/bin/nexus-mcp"
```

Pin a client to an existing code directory:

```bash
codex mcp add nexus-worktree \
-- "$HOME/Library/Application Support/Nexus/bin/nexus-mcp" \
--workspace /path/to/worktree
```text
Work A -> worktree A -> MCP binding A -> Context Pack A
Work B -> worktree B -> MCP binding B -> Context Pack B
```

Preferred entry points:
From a Work's code section, choose **Create Isolated Code Directory**, review the base branch, new branch, and destination, then confirm. Open each resulting directory in your preferred development tool: IDEA, VS Code, Xcode, Cursor, or a terminal. Nexus does not install an editor plugin or automatically switch branches.

- `get_current_development_context`: one compact object split into `confirmed_context`, `source_freshness`, and `workspace_activity`;
- `read_context_material`: on-demand reads for visible text materials in the resolved binding.

Legacy fine-grained tools remain for compatibility. Assistants should not call Nexus by default when the current conversation is already sufficient. See [docs/agent-rules.md](docs/agent-rules.md).
Archiving or deleting a Work does not delete a Nexus-created directory or Git branch. Unlinking removes only the Nexus binding; code remains on disk.

## Data and Security

- Data is local by default;
- Nexus reads only explicitly added or associated files and repositories;
- MCP is currently read-only;
- Product data and MCP projections stay under `~/Library/Application Support/Nexus` by default;
- only explicitly added or associated files and repositories are read;
- hidden materials cannot be read through MCP;
- model calls require an explicit user action;
- model credentials are managed through a small in-app connection panel and stay local to this Mac;
- API keys are not stored in SQLite or exposed through MCP;
- model calls require a direct user action;
- provider credentials stay in the macOS Keychain and never enter SQLite, MCP output, logs, or Context Packs;
- failed, cancelled, or unapproved drafts never change the current Context Pack;
- empty, binary, invalidly encoded, unsupported, and oversized files are excluded with distinct reasons;
- Git integration reads state, commit summaries, and budgeted change evidence. After explicit confirmation, Nexus may run one standard `git worktree add` to create an isolated code directory, but it never checks out, stashes, resets, commits, merges, or deletes user code.
- unsupported, binary, invalidly encoded, empty, and oversized files are excluded with distinct reasons;
- Git reads status, commit summaries, and bounded change evidence; it does not manage the user's code lifecycle.

## Build From Source

Source development requires macOS 14 or later, Xcode 26.5 / Swift 6.3.2, Node.js `v26.5.0`, and npm `11.17.0`.

```bash
swift build
swift test

cd adapters/mcp
npm ci
npm run build
```

### Parallel code work in your preferred editor
Build and verify the Apple Silicon preview package:

Parallel Work items in one Git repository need separate code directories. From a Work's code section, choose **Create Isolated Code Directory**, review the base branch, new branch, and destination, then confirm. Copy the resulting path and open each directory in a separate window of your preferred development tool, such as IDEA, VS Code, Xcode, Cursor, or a terminal. Nexus does not install an editor plugin or switch branches automatically.
```bash
scripts/build-preview.sh
scripts/verify-preview.sh
```

Archiving or deleting a Work does not delete a Nexus-created directory or Git branch. Unlinking only removes Nexus's binding; the code stays on disk.
The build downloads and verifies the pinned official Node.js Runtime, then embeds it in the generated app. Runtime files and generated `dist/` output are not committed.

## Documentation

- [Architecture](docs/architecture.md)
- [Development guide](docs/development.md)
- [Developer Preview release](docs/release.md)
- [Developer Preview release notes](docs/release.md)
- [Contributing](CONTRIBUTING.md)
- [Security policy](SECURITY.md)
- [Assistant rules example](docs/agent-rules.md)
- [中文说明](README.zh.md)

## License

Licensed under the [Apache License 2.0](LICENSE).
Nexus is licensed under the [Apache License 2.0](LICENSE).
Loading
Loading