Your agents start every session with amnesia. devnexus fixes that.
One command. Shared brain across repos, sessions, and engineers. Decisions survive, context compounds, no one re-discovers dead ends.
When one engineer's agent discovers that approach X doesn't work, that knowledge dies when the session ends. The next engineer — or the same engineer tomorrow — re-discovers the same dead end.
devnexus gives every agent a vault they read before writing any code. Decisions, architecture, and API contracts persist across sessions and engineers. Context compounds instead of resetting.
npm install -g devnexus
mkdir my-project && cd my-project
devnexus initThat's it. devnexus creates an Obsidian vault alongside your repos that acts as the shared brain. Your agents read it before writing any code.
mkdir example-proj && cd example-proj
devnexus init? Do you have an existing project vault? No
? What's your project called? example-proj
? Describe your project: Restaurant booking platform with AI recommendations
? What's your tech stack? Next.js + FastAPI + Supabase (or auto-detected from your repos)
? What's your name? Sarah
? Repo: https://github.com/example/frontend.git
? Repo: https://github.com/example/backend.git
? Repo: (enter)
? Which AI agents do you use?
◉ claude
◯ cursor
◯ codex
◯ windsurf
Open example-proj-vault/ in Obsidian and run devnexus index to generate the code graph. Start coding.
The vault needs a git remote to sync across machines and teammates.
- Create a new repo on GitHub (private recommended)
- Add it as the vault remote:
cd your-vault git remote add origin https://github.com/you/your-vault.git git push -u origin main - Open Obsidian → File → Open Vault → select
your-vault/ - Settings → Community Plugins → install "Git" (by Vinzent)
The Git plugin is pre-configured by devnexus init — auto-commit and auto-pull every minute, push after commit, pull on startup.
One engineer's discovery is every engineer's context — within minutes, not meetings.
10:00am Engineer A's agent tries approach X on UserSync → fails
10:01am Agent creates decisions/2026-04-16-usersync-polling-rejected.md → git push
10:01am Obsidian Git syncs on Engineer B's machine (~1 min)
10:15am Engineer B opens UserSync's node file → sees the decision linked
before they even think about editing it
Decisions about specific code symbols go in decisions/ as individual files with explicit refs. devnexus index links them back into the code graph. Project-level decisions (tooling, license, infra) stay in DECISIONS.md append-only. See Decision System for details.
Sync model: Obsidian Git auto-pulls every minute and pushes after commits. This is git-based, not a server — scales with your git host. Merge conflicts are rare because vault entries are append-only or in separate files.
Joining an existing workspace:
mkdir my-project && cd my-project
devnexus init
# "Do you have an existing project vault?" → Yes
# Provide the vault git URL or local folder name
# Add your repos, pick your agents — doneThe vault is cloned (or linked) into your workspace. Nothing in it is modified.
devnexus init set up a new AI-augmented workspace
devnexus upgrade update devnexus and regenerate workspace rules
devnexus update regenerate .ai-rules/ and git hooks with latest templates
devnexus add <repo> add a repo (HTTPS, SSH, or local folder)
devnexus remove <repo> remove a repo from workspace tracking
devnexus analyze [target] run GitNexus analyze (all repos or specific repo)
devnexus index build code graph, structural analysis, GRAPH_REPORT.md
devnexus index --force rebuild even if index is up to date
devnexus status workspace health dashboard
devnexus doctor deep diagnostic
devnexus doctor --fix auto-repair common issues
devnexus agent ls list agents configured per repo
devnexus agent add <agent> add an agent (claude, cursor, codex, windsurf)
devnexus agent rm <agent> remove an agent
devnexus completion install set up shell tab completion (bash/zsh/fish)
devnexus completion uninstall remove tab completion
devnexus builds a code graph from your repos and writes it into the vault as browsable Obsidian files.
devnexus analyze builds a raw graph per repo — every function, class, and type becomes a node, call relationships become edges. devnexus index merges them into a single cross-repo view and computes structural analysis:
- God nodes — symbols with high betweenness centrality. Many shortest paths route through them, so changes ripple further than edge count suggests. Always surfaced so agents check before editing.
- Communities — groups of symbols that call each other more than they call outside the group. Auto-detected, named from file paths, with hub nodes identified.
- Bridges — the sole call edge between two communities. If it breaks, those communities disconnect.
- Knowledge gaps — thin communities, oversized communities, low cohesion. Structural warning signs.
What ends up in the vault:
| File | What it is |
|---|---|
nodes/{community}/*.md |
Individual symbol files — callers, callees, linked decisions |
NODE_INDEX.md |
Every symbol with tier (god/hub/regular), edges, centrality score |
GRAPH_REPORT.md |
Structural analysis — god nodes, bridges, gaps, diff from last index |
decisions/DECISION_INDEX.md |
Auto-generated index of symbol-linked decisions |
Cross-repo symbols are namespaced (frontend::UserCard vs backend::UserCard), so the merged graph shows how repos connect without collisions.
devnexus works on its own. GitNexus adds deeper code intelligence if you want it — devnexus manages it for you.
| Tool | What it adds | How to use |
|---|---|---|
| GitNexus | Code intelligence — blast radius, execution flows, safe renames via MCP | Prompted during devnexus init — auto-installs if you say yes |
devnexus analyze |
Runs GitNexus analyze on all repos (or a specific one) | Built-in command |
devnexus index |
Builds vault code graph, structural analysis, GRAPH_REPORT.md | Built-in command, no extra install |
For details: Integrations Guide
| Required | Purpose | |
|---|---|---|
git |
Yes | Vault sync, repo cloning |
node ≥18 |
Yes | Running devnexus |
| Obsidian | Yes | Free markdown editor — browse and sync the vault |
| AI agent (Claude Code, Cursor, Windsurf, Codex) | Yes | At least one |
| GitNexus | No | Code intelligence — see Integrations |
Can I use this with one repo? Yes. The vault still adds value as persistent memory across sessions.
Should I edit .ai-rules/?
No — it's managed by devnexus. Your customizations belong in pointer files (CLAUDE.md, .cursorrules, etc.), which are never overwritten.
How do I add an agent later?
devnexus agent add windsurf. List: devnexus agent ls. Remove: devnexus agent rm cursor.
How do I update?
devnexus upgrade. Updates the package and regenerates .ai-rules/ and git hooks.
What is the contract drift check?
A pre-push hook that blocks pushes when API dirs change without updating API_CONTRACTS.md. Bypass with git push --no-verify.
Second project?
devnexus init in a new folder. It reuses your existing ~/.ai-profile/.
PolyForm Noncommercial 1.0.0 — free for personal and noncommercial use.
For commercial or enterprise licensing, contact josh@settled.live.