Agent Nexus

Archived (2026-08-11): Agent Nexus is retired and no longer an active deployment authority. The complete repository was moved to /Users/lfan/Project/archive/agent-nexus for historical rollback only. Codex uses native user/project configuration and owning-repository skills; do not run new syncs from this archive without an explicit reviewed restoration.

The safe package manager for your agent workspace.
Declare MCPs, skills, hooks, and agent packages once. Preview every executable change, sync native config, verify with doctor, and trace the result with a lockfile.

nexus.personal.yml → dry-run review → sync native config → doctor → lockfile

---

Why Nexus?

Agent workspaces sprawl fast: Claude Code, Cursor, Google Antigravity, and Codex each have their own places for skills, MCP servers, hooks, and config. Useful capabilities also live in GitHub repos, local folders, docs, and one-off install notes.

Agent Nexus turns that into one reviewable workflow:

Before	After
Hand-edit four target configs	Declare the stack once in nexus.personal.yml or nexus.yml
Copy MCP commands into different formats	Preview executable MCP and hook changes before writing
Wonder which package installed what	Trace deployed assets back to package snapshots and a lockfile
Check each tool manually	Run doctor and inspect the localhost dashboard

The 30-second demo

name: my-agent-workspace
version: 1.0.0

targets:
  - claude
  - cursor
  - antigravity
  - codex
# Use targets: ["*"] only when you want all 41 skill target presets.

packages:
  - repo: lifan-builds/context-harness
    ref: main
    hooks:
      - codex

mcps:
  - name: sequential-thinking
    command: npx
    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"]

nexus audit --redact-home
nexus sync --dry-run
nexus sync
nexus doctor

audit reads local state without writing. sync --dry-run shows the MCP and hook review before target config changes. sync applies the reviewed plan. doctor verifies what landed.

5-minute safe start

1. Install

You need Python 3.10+ and Git. Node.js is needed only for MCP servers that use npx.

Until a PyPI release is published, install directly from GitHub:

uv tool install 'agent-nexus @ git+https://github.com/lifan-builds/agent-nexus.git'
# or
pipx install 'git+https://github.com/lifan-builds/agent-nexus.git'

For contributor/source-checkout mode:

git clone https://github.com/lifan-builds/agent-nexus.git ~/.agent-nexus
cd ~/.agent-nexus
scripts/install-local.sh

The source installer creates a reversible ~/.local/bin/nexus symlink. See the quickstart for virtual-environment install and uninstall options.

2. Choose the workspace

Run Nexus from the workspace you want to manage. It uses --project-dir, then NEXUS_PROJECT_DIR, then the nearest parent containing a Nexus manifest.

3. Inspect, initialize, preview

nexus audit --json --redact-home
nexus init
nexus sync --dry-run

nexus init creates a safe empty nexus.personal.yml with no packages, MCPs, or hooks. Use nexus init --template example only when you explicitly want the comprehensive example. Commit nexus.yml only for a reviewed shared team stack.

4. Deploy after review

nexus sync
nexus doctor

Dry-run uses temporary storage for uncached packages and leaves no persistent target or Nexus-cache changes. A real sync prints the review and asks for approval unless you pass --yes.

Let your agent install it

Paste this into Claude Code, Codex, Cursor, or another coding agent from the directory where you want Agent Nexus installed:

Install Agent Nexus for me safely.

Goal:
- Set up Agent Nexus as the review-first package manager for my coding-agent workspace.
- Use a personal manifest unless I explicitly ask for a committed team manifest.
- Do not overwrite existing agent config without showing me the dry-run output first.

Steps:
1. Check that Python 3.10+, Git, and PyYAML are available. If PyYAML is missing, install it with `python -m pip install pyyaml` after asking me if needed.
2. Clone `https://github.com/lifan-builds/agent-nexus.git` to `~/.agent-nexus`, or use the existing checkout if I am already inside one.
3. Run `scripts/install-local.sh` to install the reversible `~/.local/bin/nexus` wrapper, or keep using `python nexus.py` if `~/.local/bin` is not on PATH.
4. Run `nexus audit --redact-home` and summarize detected targets and existing managed assets.
5. Run `nexus init` only if `nexus.personal.yml` does not already exist.
6. Help me edit `nexus.personal.yml` with targets, packages, skill filters, MCP servers, and `${ENV_VAR}` placeholders for secrets.
7. Run `nexus sync --dry-run` and show me the MCP commands, hook commands, and deployment plan.
8. Stop and ask for my approval before running a real sync.
9. After I approve, run `nexus sync`, then `nexus doctor`.
10. Report the lockfile path, warnings, and the next command I should run if something failed.

Safety rules:
- Prefer `nexus.personal.yml` for local setup.
- Keep secrets out of git; use `${ENV_VAR}` placeholders.
- Do not pass `--yes` unless I explicitly ask for unattended setup.
- Do not delete or overwrite unmanaged Claude Code, Cursor, Antigravity, or Codex config.

For unattended setup after you already trust the manifest:

nexus sync --yes

Dashboard

nexus dashboard

The dashboard is a localhost-only review console for the same workflow as the CLI:

• Start with deploy readiness and the next safe step: preview the dry-run review.
• Inspect package source, discovered assets, skill policy, MCP servers, target health, and lockfile state.
• Tune package skill policy and global target policy in the manifest.
• Run deploy only after the dashboard asks you to type deploy.

For scripting or troubleshooting without starting the server:

nexus dashboard --json

Use --no-open when you want the server URL without automatically opening a browser.

What Nexus manages

Capability	What Nexus does
One manifest	Keep agent capabilities in nexus.yml or a gitignored nexus.personal.yml.
GitHub/local packages	Fetch package snapshots, discover skills, hooks, commands, and agents, and record them in the lockfile.
MCP servers	Merge declared MCP servers into tested target config formats, with per-server target filters, while preserving unmanaged entries and local secrets.
Skills	Link package skills into selected targets and support package-level skill filters.
Hooks	Review managed hook commands, deploy supported target hooks, and deduplicate stale managed entries.
Target overlays	Generate target-specific skill metadata without mutating package snapshots.
Dashboard controls	Inspect state, tune skill and target policy, and run a confirmed deploy from localhost.
Traceability	Record resolved packages, deployed resources, overlays, and managed MCPs in nexus.lock.yml.

Browser tooling policy

Keep browser and desktop access narrow and intentional. Route directly by task type and host rather than treating this list as a mandatory waterfall:

1. Use built-in WebSearch/WebFetch for ordinary research and static page retrieval.
2. Use a pinned existing-profile browser MCP such as Playwriter for dynamic or authenticated work in explicit task-owned pages. General workflows may keep multiple persistent page handles and navigate to arbitrary HTTP(S) destinations; fixed sensitive operations must use an explicit selected/pinned page. A Nexus target filter controls host discovery, not page attachment or runtime authority.
3. Use Chrome DevTools MCP only for focused Lighthouse, performance-trace, Core Web Vitals, heap, console, or network diagnostics. Keep task-local diagnostics in native project configuration rather than Nexus-managed by default.
4. When the browser layer cannot address browser chrome, windows, menus, dialogs, permissions, or non-browser applications, use vanilla Open Computer Use on Claude Code, Cursor, or Antigravity and Codex's native computer-use capability. Per-MCP target filters keep Codex excluded.

Retired controllers and bridges such as Peekaboo and Kimi WebBridge stay absent from the manifest, managed targets, and local runtime unless a fresh explicit install and security review approves their return. Use exactly one browser or desktop controller at a time.

Use an MCP-level targets filter when a reusable server belongs on only a subset of the configured MCP-capable hosts. Package-level targets still controls package assets such as skills and does not implicitly filter a separate MCP declaration. Repository-only MCPs remain in native project configuration because MCP target filters select hosts, not repositories.

Playwright MCP remains optional for isolated, reproducible browser automation and end-to-end testing. Put it under optional_mcps rather than enabling it for every sync.

See docs/mcp.md for configuration and pruning behavior.

Supported targets

Nexus focuses on four tested native targets and can deploy skills to 41 target presets when you opt in.

Target	Skills	MCP servers	Hooks
Claude Code	~/.claude/skills/	~/.claude.json	repo .github/hooks/
Cursor	~/.cursor/skills/	~/.cursor/mcp.json	repo .cursor/hooks.json
Google Antigravity	~/.gemini/antigravity/skills/	~/.gemini/antigravity/mcp_config.json	not deployed
Codex	~/.codex/skills/	managed block in ~/.codex/config.toml	~/.codex/hooks.json or $CODEX_HOME/hooks.json

If targets is omitted, Nexus uses the four core targets. Use targets: ["*"] only when you want skill deployment across all target presets. Additional skill presets are listed in docs/targets.md, along with implemented, partial, lockfile-only, and planned behavior.

Safety model

Agent Nexus writes to local agent config, so the default path is review-first.

• audit inventories local state without writing.
• sync --dry-run previews package discovery, MCP commands, hook commands, and deployment plans.
• sync prints executable MCP and hook changes before applying them.
• Existing unmanaged MCP servers and placeholder-backed local env values are preserved; explicit env: {} clears stale env keys on that managed server.
• Codex MCP config is isolated inside a Nexus-managed TOML block.
• The dashboard binds to localhost, redacts secrets, and requires typed confirmation before deploy.
• Every sync writes a lockfile for traceability.

Read the full model in docs/security-model.md. For exact target support, read docs/targets.md. For MCP merge details, read docs/mcp.md.

Common workflows

Keep a personal agent stack synced

nexus audit --redact-home
nexus init
$EDITOR nexus.personal.yml
nexus sync --dry-run
nexus sync
nexus doctor
nexus dashboard

Share a team-standard agent setup

1. Commit nexus.yml to the repo.
2. Put shared packages, skills, MCP names, and targets in that file.
3. Keep secrets out of git with ${ENV_VAR} placeholders.
4. Ask each developer to run nexus sync --dry-run before first deploy.

Deploy Context Harness everywhere

targets: [claude, cursor, antigravity, codex]

packages:
  - repo: lifan-builds/context-harness
    ref: main
    hooks:
      - codex

Then:

nexus sync

Context Harness is treated like any other Nexus package: fetched, discovered, deployed, locked, and verified.

Further reading

• Manifest reference
• Target and resource matrix
• Package reference
• Package trust and lockfile traceability
• MCP configuration
• Hook lifecycle
• Security model
• Demo transcript
• Screenshot checklist
• Comparison guide
• Example manifests
• Quickstart
• Contributing
• Security policy
• Changelog

Repository map

• nexus.py — supported CLI and localhost dashboard runtime.
• tests/ — unit, CLI, repository, package, and browser verification.
• docs/ — user, security, target, package, demo, and release documentation.
• examples/ — reviewed manifest patterns; not automatic defaults.
• .github/ — CI and community metadata; only .github/hooks/ is generated by sync.
• AGENTS.md and .trellis/ — project-local agent activation, workflow, specifications, and task context.
• nexus.sh — deprecated historical reference; use nexus or nexus.py.

Troubleshooting

Problem	Fix
Error: PyYAML is required	Run python -m pip install pyyaml.
Error: git is required	Install Git and make sure it is available on PATH.
npx MCP servers fail after sync	Install Node.js or change the MCP entry to a command available on your machine.
nexus doctor reports missing MCP config	Run nexus sync --dry-run, then nexus sync, then nexus doctor.
nexus.personal.yml already exists	nexus init refuses to overwrite personal config. Use nexus init --force only when you intentionally want to replace it.

Development verification

python -m pytest tests
python -m py_compile nexus.py
python nexus.py audit --json
python nexus.py sync --dry-run
python nexus.py doctor
python nexus.py dashboard --json

Agent Nexus intentionally keeps the runtime small: Python plus PyYAML.

Positioning

Agent Nexus is not trying to be the broadest possible agent hub, a generic dotfiles sync tool, or a replacement for native plugin systems in Claude Code, Cursor, Antigravity, or Codex.

It is the package-oriented deployment layer for serious agent workspaces:

Install agent capabilities from GitHub, review every executable change before it touches local config, deploy native target files, and trace the result with a lockfile and doctor.

Use native marketplaces when you want platform-specific discovery and first-party install UX. Use broad hubs when your top priority is maximum target count. Use Agent Nexus when you want a safe, inspectable workflow for keeping MCP servers, skills, hooks, and agent packages consistent across the coding agents you actually use.