Nexus

Home Command Center — Discovery + Config Management + AI

Nexus is a single Rust binary that gives you a complete picture of your machine:

Deep-index your home directory with instant full-text search
Manage configs for 20+ tools — backup, diff, restore, profile
Track changes in real time with a filesystem daemon
Ask AI questions about your filesystem via Claude

Three surfaces — CLI, TUI dashboard, Web UI — all sharing the same core.

Why Nexus?

Your home directory is a sprawling, undocumented system. Config files scattered across ~/.config, dotfiles everywhere, projects in various states. Nexus brings order:

One scan indexes everything into SQLite with FTS5 — search is instant
One backup snapshots all your configs — restore any tool to any point in time
One daemon watches for changes — never lose track of what changed and when
One question to AI — “what rust projects do I have?” gets a real answer

Supported Config Tools

atuin, btop, fish, flutter, gcloud, gh, git, gitui, katana, mise, nushell, nvim, raycast, sniffnet, starship, stripe, uv, wezterm, zellij, zsh

Installation

Pre-built binaries

Download the latest release from GitHub Releases.

Binaries are available for:

macOS — Apple Silicon (aarch64) and Intel (x86_64)
Linux — x86_64

# macOS Apple Silicon
curl -sL https://github.com/mbaneshi/nexus/releases/latest/download/nexus-latest-aarch64-apple-darwin.tar.gz | tar xz
sudo mv nexus /usr/local/bin/

Build from source

Requirements: Rust 1.85+ (edition 2024)

git clone https://github.com/mbaneshi/nexus.git
cd nexus
cargo build --release
# Binary at target/release/nexus

Verify installation

nexus --help

Quick Start

1. Index your home directory

nexus scan

This recursively walks ~, respecting .gitignore patterns, and indexes everything into SQLite with FTS5.

2. Search

nexus search "nvim config"
nexus search --category config "keybinding"

3. Manage configs

nexus config list          # discover tools in ~/.config
nexus config backup        # snapshot all configs
nexus config diff nvim     # see what changed since last backup

4. Start the watcher

nexus daemon start         # watch ~/.config for changes
nexus changes              # see recent filesystem changes

5. Launch the dashboard

nexus tui                  # terminal UI
# or
nexus serve                # web server at localhost:3000

6. Ask AI (optional)

Set ANTHROPIC_API_KEY in your environment, then:

nexus ask "what are my largest config files?"

CLI Reference

The nexus binary provides 17 commands organized into groups.

Global Flags

Flag	Description
`--json`	Output in JSON format
`--verbose`	Enable verbose logging

Discovery

`nexus scan`

Index your home directory. Uses the ignore crate for parallel walking (respects .gitignore).

`nexus search <query>`

Full-text search across indexed files.

Flag	Description
`--category <cat>`	Filter by category (config, code, doc, image, cache)
`--limit <n>`	Max results (default 20)

`nexus stats`

Show home directory statistics: file counts by category, total size, last scan time.

Config Management

`nexus config list`

List all discovered config tools in ~/.config.

`nexus config show <tool>`

Display config files for a specific tool.

`nexus config backup`

Create a gzip-compressed snapshot of all config files.

`nexus config snapshots`

List all saved snapshots with timestamps and sizes.

`nexus config restore <snapshot-id>`

Restore config files from a snapshot.

`nexus config diff <tool>`

Show diff between current config and the last snapshot (added/modified/removed files).

`nexus config init`

Initialize the nexus config file at ~/.config/nexus/config.toml.

`nexus config path`

Print the config file path.

Profiles

`nexus config profile save <name>`

Save current configs as a named profile for machine provisioning.

`nexus config profile list`

List all saved profiles.

`nexus config profile apply <name>`

Apply a saved profile (restore configs from it).

`nexus config profile delete <name>`

Delete a saved profile.

Daemon

`nexus daemon start`

Start the filesystem watcher daemon. Monitors ~/.config for changes and records them. Auto-snapshots when a registered tool’s config changes.

`nexus daemon stop`

Stop the running daemon.

`nexus daemon status`

Show whether the daemon is running.

`nexus changes`

Display recent filesystem changes recorded by the daemon.

Flag	Description
`--limit <n>`	Max changes to show

AI

`nexus ask "<query>"`

Ask a natural language question about your filesystem. Requires ANTHROPIC_API_KEY.

Surfaces

`nexus tui`

Launch the terminal dashboard (4 screens: overview, configs, search, changes).

`nexus serve`

Start the web server at http://localhost:3000.

TUI Dashboard

Launch with nexus tui. The terminal UI has 4 screens navigable with Tab/Shift+Tab.

Screens

Overview

Home directory stats at a glance: file counts by category, total size, last scan time, category breakdown chart.

Configs

Browse discovered config tools. Select a tool to view its files with syntax highlighting (via syntect). Navigate with arrow keys.

Search

Interactive full-text search. Type your query and see FTS5 results update. Navigate results with arrow keys.

Changes

Recent filesystem changes recorded by the daemon. Shows file path, change type, and timestamp.

Keybindings

Key	Action
`Tab` / `Shift+Tab`	Switch screens
`↑` / `↓`	Navigate lists
`Enter`	Select item
`Ctrl+R`	Refresh data
`?`	Toggle help overlay
`q` / `Esc`	Quit

REST API

Start the server with nexus serve. All endpoints are prefixed with /api.

Endpoints

`GET /api/health`

Health check. Returns 200 OK.

`GET /api/stats`

Home directory statistics.

{
  "total_files": 150000,
  "total_size": 5368709120,
  "categories": { "code": 45000, "config": 3200, ... },
  "last_scan": "2026-03-24T10:00:00Z"
}

`GET /api/search?q=<query>&category=<cat>&limit=<n>`

Full-text search.

Param	Required	Description
`q`	yes	Search query
`category`	no	Filter by category
`limit`	no	Max results (default 20)

`GET /api/config/tools`

List all discovered config tools.

`GET /api/config/snapshots`

List all config snapshots.

`POST /api/config/backup`

Create a new config snapshot. Returns the snapshot ID.

`POST /api/config/restore/:id`

Restore configs from a snapshot.

`GET /api/config/:tool/diff`

Diff current config vs last snapshot for a specific tool.

`GET /api/daemon/status`

Daemon running status.

`GET /api/changes?limit=<n>`

Recent filesystem changes.

Param	Required	Description
`limit`	no	Max changes to return

Configuration

Nexus stores its own config at ~/.config/nexus/config.toml.

Initialize

nexus config init

This creates a default config file. View the path with:

nexus config path

Settings

# ~/.config/nexus/config.toml

[scan]
# Directories to exclude from scanning
exclude = ["node_modules", ".git", "target", "__pycache__"]

[database]
# Database location (default: ~/.local/share/nexus/nexus.db)
path = "~/.local/share/nexus/nexus.db"

[server]
# Server port
port = 3000

[ai]
# Claude model to use
model = "claude-sonnet-4-20250514"

Environment Variables

Variable	Description
`ANTHROPIC_API_KEY`	Required for AI features (`nexus ask`)
`NEXUS_LOG`	Set log level (e.g., `debug`, `info`, `warn`)

Database

All data is stored in a single SQLite database at ~/.local/share/nexus/nexus.db.

WAL mode for concurrent reads
64 MB cache, 256 MB mmap
FTS5 for instant full-text search
Parameterized queries only (no string interpolation)

Architecture Overview

Nexus is a Rust workspace with 8 crates using a hybrid architecture — concrete types everywhere, port traits only where abstraction is needed.

Dependency Graph

nexus-core  (zero deps on other workspace crates)
  │
  ├── nexus-discovery   (depends on core only)
  ├── nexus-configs     (depends on core only)
  ├── nexus-watcher     (depends on core only)
  ├── nexus-ai          (depends on core only)
  │
  ├── nexus-cli         (composes all feature crates)
  ├── nexus-tui         (composes core + discovery + configs)
  └── nexus-server      (composes core + discovery + configs + ai)

Rule: Feature crates never depend on each other.

Design Principles

Feature crate isolation — each concern is its own crate, depends only on core
Minimal abstraction — only 2 port traits: LlmPort (AI) and ConfigStorePort (nexus config)
Sync-first — feature crates use synchronous iterator-based APIs (except ai which is async)
Parallelism via rayon — scanner uses ignore crate’s parallel walker
Message-passing TUI — Event enum → update → draw cycle
spawn_blocking bridge — async server wraps sync feature crate calls

Data Flow

User Input
    │
    ▼
┌──────────┐     ┌──────────────┐     ┌──────────┐
│ Surface  │────▶│ Feature Crate│────▶│   Core   │
│ (CLI/TUI/│     │ (discovery/  │     │ (SQLite  │
│  Server) │     │  configs/ai) │     │  models) │
└──────────┘     └──────────────┘     └──────────┘

Surfaces compose feature crates. Feature crates use core for data access. Core owns the database and domain types.

Crate Layout

crates/
  core/          — models, config, db (SQLite WAL + FTS5), error, output
  discovery/     — home scanner, indexer, searcher, categorizer
  configs/       — ~/.config manager: registry, backup, diff, restore, profiles
  watcher/       — filesystem daemon (notify + IPC + auto-snapshots)
  ai/            — Claude API adapter, query templates, context builder
  cli/           — clap binary with subcommands
  tui/           — ratatui dashboard (4 screens)
  server/        — axum REST API + embedded SvelteKit

nexus-core

The foundation. Zero dependencies on other workspace crates.

Domain types: FileEntry, ConfigTool, ConfigFile, ConfigSnapshot, SearchQuery
Database: SQLite WAL + FTS5, migrations, pragmas (9 tables)
Config: TOML loader for ~/.config/nexus/config.toml
Error types: NexusError with variants for each concern
Port traits: LlmPort (AI abstraction)
Output: formatting utilities (JSON, table, human-readable sizes)

nexus-discovery

Home directory scanner and search engine.

Scanner: recursive walk using ignore crate (parallel, respects .gitignore)
Indexer: batched SQLite inserts (5000 entries per transaction) with FTS5 triggers
Searcher: FTS5 queries with category/size filtering
Categorizer: classifies files (config, code, document, image, cache, etc.)

nexus-configs

Config file manager for ~/.config.

Registry: 20 known tool definitions (path patterns, languages)
Scanner: discovers installed tools, hashes files with blake3
Backup: gzip-compressed snapshots stored as BLOBs in SQLite
Restore: decompress and write files from snapshots
Diff: current vs snapshot, snapshot vs snapshot comparison
Profiles: named config sets for machine provisioning

nexus-watcher

Filesystem change tracking daemon.

Watcher: notify crate with debouncing
Daemon: PID file management, start/stop/status
Auto-snapshot: snapshots ~/.config tools when their files change
Change log: records all changes to file_changes table

nexus-ai

Claude API integration.

Adapter: implements LlmPort trait for Claude API
Context builder: aggregates DB stats into LLM context
Templates: system prompts for filesystem and config queries
History: stores queries and responses in SQLite

nexus-cli

The binary. Composes all feature crates via clap subcommands (17 commands).

nexus-tui

Terminal dashboard with 4 screens (overview, configs, search, changes). Uses ratatui with message-passing architecture.

nexus-server

Axum REST API with 10 endpoints. Uses spawn_blocking to bridge sync feature crates into async handlers.

Database

Nexus uses a single SQLite database at ~/.local/share/nexus/nexus.db.

Configuration

WAL mode for concurrent reads
64 MB cache (cache_size = -65536)
256 MB mmap (mmap_size = 268435456)
Parameterized queries only — no string interpolation

Tables

Table	Purpose
`files`	Indexed home directory entries (path, name, size, category, hash, timestamps)
`files_fts`	FTS5 virtual table for full-text search (indexes path and name)
`scans`	Scan history (start time, end time, file count, status)
`config_tools`	Discovered tools in `~/.config` (name, path, language)
`config_files`	Individual config files with blake3 content hashes
`config_snapshots`	Backup metadata (timestamp, tool, size)
`snapshot_files`	Gzip-compressed file contents (BLOBs)
`file_changes`	Filesystem change log from the watcher daemon
`ai_queries`	AI query history (query, response, model, tokens)

FTS5 Search

The files_fts table uses SQLite FTS5 for instant full-text search. It indexes file paths and names, supporting:

Phrase queries: "nvim config"
Prefix queries: rust*
Boolean operators: nvim AND lua
Column filtering: path:projects

Migrations

All schema migrations are versioned in the core::db module and run automatically on first database open.

Architecture Decision Records

ADR-001: Hybrid Architecture (Concrete + Ports)

Decision: Use concrete types everywhere except for LLM access, which gets a port trait.

Context: Full hexagonal architecture with 15 port traits is overhead for a solo builder maintaining 8 crates. Only LLM access genuinely benefits from abstraction (swappable providers).

Consequence: Only LlmPort is abstract. Database, filesystem, and config access use concrete types. This can be expanded later if needed.

ADR-002: Single SQLite Database

Decision: Store everything in one SQLite database at ~/.local/share/nexus/nexus.db.

Context: Separate databases would complicate joins and backups. SQLite WAL mode handles concurrent reads well.

Consequence: Config snapshots stored as gzip-compressed BLOBs. Portable — copy one file to provision a new machine.

ADR-003: Feature Crate Isolation

Decision: Feature crates depend only on nexus-core, never on each other.

Context: Prevents circular dependencies and allows independent compilation.

Consequence: If configs needs search, it goes through core types, not by importing discovery.

ADR-004: FTS5 with Path Indexing

Decision: Include file paths in the FTS5 index, not just names.

Context: Users search by directory context (“rust projects”, “nvim config”). Path-aware search is significantly more useful.

Consequence: Larger FTS index, but home directories are manageable in size.

ADR-005: Config Snapshots as Compressed BLOBs

Decision: Store config file contents as gzip-compressed BLOBs in SQLite.

Context: Alternatives considered: git repo for dotfiles, tar archives. SQLite BLOBs are simplest — no external dependencies, self-contained, easy to restore.

Consequence: Git-backed versioning is a future enhancement, not a requirement.

ADR-006: Three Surfaces, One Core

Decision: CLI, TUI, and Web server all compose the same feature crates.

Context: Each surface has different UX needs but identical data access patterns. Sharing core logic prevents divergence.

Consequence: Feature crates must be surface-agnostic. No stdout printing in library code.

ADR-007: Known Tool Registry

Decision: Hard-code definitions for 20 known config tools rather than auto-detecting.

Context: Auto-detection would require heuristics and produce false positives. A curated registry is more reliable.

Consequence: Adding a new tool requires a code change. Acceptable — the list changes rarely.

ADR-008: Claude-First AI

Decision: Ship with Claude API only, use LlmPort trait for future providers.

Context: Adding Ollama/OpenAI support can come later through the trait abstraction without changing calling code.

Consequence: Requires ANTHROPIC_API_KEY for AI features. All other features work without it.

ADR-009: CI/CD from Day One

Decision: Ship with GitHub Actions CI (fmt, clippy, test, build, coverage) and multi-platform release automation.

Consequence: Every PR runs the full pipeline. Releases triggered by git tags (v*).

Contributing

Setup

git clone https://github.com/mbaneshi/nexus.git
cd nexus
cargo build
cargo test

Requirements:

Rust 1.85+ (edition 2024)
lefthook for git hooks (optional but recommended)

Development workflow

# Run tests
cargo test

# Lint (must pass with 0 warnings)
cargo clippy -- -D warnings

# Format
cargo fmt --all

# Check format without changing
cargo fmt --all --check

Code conventions

All public functions must have doc comments
Error handling: thiserror in library crates, color-eyre in the binary
Use tracing for logging, never println! in library code
Database access only through core::db — no raw SQL in binaries
All SQL queries use parameterized statements
TUI: follow ratatui’s Widget trait pattern
Frontend: use pnpm, never npm

Architecture rules

core has zero dependency on any other workspace crate
Feature crates depend on core only, never on each other
Surfaces (CLI, TUI, server) compose feature crates
Only 2 port traits: LlmPort and ConfigStorePort

Pull requests

CI must pass (fmt, clippy, test, build)
Keep PRs focused — one concern per PR
Write tests for new functionality

Testing

Nexus has 34 tests across the workspace.

Running tests

# All tests
cargo test

# Specific crate
cargo test -p nexus-core
cargo test -p nexus-discovery
cargo test -p nexus-configs
cargo test -p nexus-server
cargo test -p nexus-watcher

# With output
cargo test -- --nocapture

Test breakdown

Crate	Tests	Coverage
core	8	DB operations, config loading, output formatting
discovery	4	scan, index, search, stats
configs	8	discovery, scan, backup, diff, profiles
server	10	all 10 API endpoints
watcher	4	watch, modify detection, nonexistent paths, daemon status

Test strategy

Unit tests are inline in each module (#[cfg(test)])
Integration tests live in each crate’s tests/ directory
Core provides open_in_memory() for test databases — no disk I/O in tests
Server tests use axum’s TestClient for endpoint testing
Frontend tests use vitest + Playwright (when the SvelteKit frontend is ready)

Coverage

CI runs cargo-llvm-cov and uploads to Codecov. View coverage on the Codecov dashboard.

Keyboard shortcuts

Nexus Documentation