Nexo Hub — AI Sessions & Usage

Your AI work, organized across apps.

Nexo Hub is a free, MIT-licensed extension for VS Code and compatible Cursor releases. Its main workspace organizes projects, sessions, and usage across Cursor, Claude Code, Grok Bot, Antigravity, Gemini CLI, Codex, and Grok Build. Engram provides optional shared memory and a visual memory graph alongside that work.

Nexo is an original implementation. No code, branding, or assets from the proprietary Claude Code and Codex Assist extension are included.

Install

From an extension listing, choose Install. To install a downloaded VSIX:

1. Download nexo-ai-hub-0.3.1.vsix.
2. In VS Code or Cursor, open the Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux).
3. Run Extensions: Install from VSIX… and select the file.
4. Reload the editor if prompted.
5. Click Nexo in the Activity Bar, or run Nexo: Open AI Workspace.

Requires VS Code 1.96 or a compatible desktop Cursor release. The same VSIX contains the webview, parsers, and SQLite WebAssembly runtime for macOS, Windows and Linux. Native Cursor storage is experimental because its schema is not a stable public API.

Switching from the earlier Nexo Sessions preview

Version 0.3.1 uses the new extension ID esteban-morales.nexo-ai-hub. If the old esteban-morales.nexo-sessions extension is installed, disable or uninstall it before enabling Nexo Hub so their commands and views do not conflict. If you connected Claude usage in the old extension, disconnect that connection there before switching, then reconnect it in Nexo Hub.

Existing nexo.* editor settings still apply. Pins, project assignments, connection records, and saved Engram HTTP tokens belong to the old extension's storage and do not automatically migrate. Local source histories and the Engram database remain in their original locations and can be connected again.

Start here

1. Find your conversations. Open Nexo and click Refresh. Cursor and Claude Code history on this computer is detected automatically. If an app is empty, use its Set up history instructions under Connections.
2. Put related work together. Open a conversation, choose Assign project, and enter a name such as “Ascent.” Repeat for related sessions from other apps. They appear together on Projects.
3. Check usage. Open Usage, choose an app, and follow its connection steps. For Cursor, click Connect Cursor usage; imports are optional fallbacks. For Grok Bot conversations, follow the three export/download/import steps shown in its card.

The Projects page has the same short Start here guide. You can hide it and reopen it through Getting started. Each setup area explains its next step and what unavailable data means.

What you can do

Also available: a cross-session file timeline, native Claude/Codex resume commands, portable exports, and a context handoff combining recent conversation excerpts with Engram project context. Handoffs are extractive, not AI-generated summaries; Nexo needs no AI API key.

What changed in 0.3.0

Projects is now the main view. The primary workflow is Projects → Sessions → Usage, with shared memory available when needed. Cursor, Claude Code, Grok Bot, and Antigravity appear first in the app coverage view.

Use Assign project on a session to bring related conversations into a group such as “Ascent,” even when they come from different apps or folders. Assignments are local Nexo metadata; original histories, working directories, and recorded project names remain intact. Resetting an assignment restores the recorded project. Identically named folders in different locations stay separate until you explicitly group them.

Grok Bot supports collections of Bots and conversations, an all-Bots export request, Bot filters, recorded snapshot dates, and explicit coverage information. Updated archives deduplicate known Bot/conversation identities without summing usage or inventing missing transcript turns.

Usage now includes automatic Cursor/Grok Bot account reads through the existing Cursor sign-in, Claude Code's optional status-line connection, Antigravity CLI quota refresh, and optional Cursor CSV usage imports. An imported account report, local token total, and remaining plan allowance are different measurements and are displayed separately. Missing readings stay unavailable.

Session names use real saved titles or the first meaningful request. Known injected IDE/browser context is collapsed, with complete original text still available. Readable model labels retain their raw identifiers in tooltips. Selecting an app with no sessions clears the previous conversation.

Source attribution

A transcript format does not establish which app produced a conversation. Codex-compatible files without a recognized recorded coding-client origin now appear under Other histories. They do not count as Codex usage, contribute Codex quota snapshots, or receive a native Resume button. Source details shows the exact recorded client, format, model provider, and file path. Nexo does not infer an app from phrases such as “Claude in Chrome” inside a prompt. Local origin metadata is editable and is not a cryptographic attestation.

Bring Grok Bot conversations into Nexo

1. Open Connections → Grok Bot and click Copy all-Bots export request.
2. Paste the request into a Grok Bot on your account. It uses its available ReadTranscript tool to read its own and other owned Bots' accessible conversations.
3. The request asks it to page back through every identified conversation, record missing or inaccessible histories, and create a downloadable collection. If it cannot discover the full Bot/conversation inventory, it must ask you for the missing names or IDs and mark account coverage incomplete.
4. Download the archive and use Import bot archive. You can import multiple files or choose a folder of archives to rescan.
5. Filter sessions by Grok Bot, then by Bot. Assign conversations to projects and inspect original messages, memory notes, task summaries, export date, and declared coverage.

Use Copy export request when you only want the current Bot conversation. Nexo accepts its own nexo.grok-bot.v1 and nexo.grok-bot.collection.v1 archive formats; these are not claimed to be official export schemas. Explicit Markdown imports are context documents and do not invent role boundaries.

A Bot can read other Bots on the same account through the supported tool, but there is no documented public account-history API or complete inventory endpoint. Nexo cannot promise automatic discovery of all conversations. Account coverage is export-reported, never independently verified; deleted or inaccessible histories may be unavailable. Imported snapshots do not expose the Bot's running hidden context or live account quota. See docs/grok-bot-source.md for primary sources and merge behavior.

Connect usage

On The X Subscription, Cursor, Grok Bot, and Grok apps share one weekly allowance. Legacy Cursor plans can use different monthly pools. Nexo never adds product-card percentages into a fictitious combined allowance. The official dashboard is authoritative for your plan and current account.

Claude readings update on status-line events and are labeled accordingly. They are not an on-demand authenticated API fetch. Nexo persists only quota percentages, reset timestamps, and capture time from the status-line payload; it does not persist its prompt, transcript, account, or credential fields. It retains the previous status-line command solely so it continues to work and can be restored.

Optional Cursor CSV fallback

If the automatic account connection is unavailable or you want to inspect individual exported request rows, open Usage → Account export. Download a usage report from your Cursor dashboard’s Usage or Spending section if CSV export is offered, then choose Import Cursor usage CSV. Keep that file in place so Nexo can reload it locally. The latest selected report replaces the prior report; reports are never added to local session totals. Nonnumeric Included/Free costs remain unavailable. A CSV report does not contain conversation text or a live remaining allowance.

Cursor connection boundaries

Cursor’s account endpoints are internal interfaces, so their response formats can change. Nexo validates known fields and shows an actionable error when the response no longer matches; it does not invent percentages. The credential comes only from cursorAuth/accessToken in the selected Cursor installation’s database. Plaintext tokens stay in process memory. On macOS, supported encrypted tokens use only the exact Cursor Safe Storage Keychain item; a denied request is not retried through another credential source. Nexo never reads browser cookies or refresh tokens and never changes the Cursor login. Disconnecting stops Nexo’s checks.

Connect your existing Engram

The connector targets Gentleman Programming's Engram. It was integration-tested against the official Engram 3.6.0 Linux release in a separate, disposable database.

Recommended: local MCP

If engram already works in your terminal:

1. Open Nexo → Memory, or its Memory graph.
2. Click Connect Engram.
3. Nexo starts its own engram mcp client process using your existing database. It does not modify the MCP configuration of your other assistants.

You do not need engram serve for this transport. If the editor cannot find the binary, set Nexo: Engram Executable to its full path. An Apple Silicon Homebrew example is:

{
  "nexo.engram.transport": "stdio",
  "nexo.engram.executable": "/opt/homebrew/bin/engram",
  "nexo.engram.args": ["mcp"]
}

For a nondefault database, set nexo.engram.dataDirectory. Otherwise the client preserves ENGRAM_DATA_DIR, or Engram uses its own default. Nexo does not copy or migrate the database. An optional nexo.engram.project sets an exact project override when your Engram project names differ from local folder names.

MCP browsing: Engram 3.6.0 does not expose a general list-recent-observations MCP tool. The initial view therefore shows real project-context cards for up to 12 discovered projects. Enter a search query to retrieve individual observations across projects, or select another project. Search responses are bounded at 60 observations; full contents load when an observation is opened.

Alternative: existing local HTTP server

Start Engram yourself in a terminal:

engram serve

Configure:

{
  "nexo.engram.transport": "http",
  "nexo.engram.url": "http://127.0.0.1:7437"
}

HTTP mode also lists up to 60 recent observations. If your server needs a token, use Nexo: Set Engram HTTP Token. The token is kept in the editor's SecretStorage and is not exposed to the webview. Only direct loopback HTTP/HTTPS addresses are accepted. Remote endpoints and redirects are rejected.

Writing memories

Use Save a memory in the Memory view, or Remember on a session. Review the title, memory type, exact project, content, and optional topic key, then click Save to Engram.

Browsing and searching do not create observations or register write sessions. An explicit save creates a separate Nexo-owned Engram session, saves the reviewed observation, and closes that session. It never impersonates a Claude or Codex session. If a write acknowledgement is lost, Nexo does not silently retry; check Engram before trying again.

What the brain means

The graph displays the data currently loaded in the view. Project clusters group matching project labels. An additional session link appears only when Engram's recorded session_id exactly matches an indexed assistant session's native ID. This is not an embedding-derived semantic graph.

Memory circles, project-context diamonds, and session squares have distinct shapes. Clicking a project narrows the graph. Clicking a memory opens its actual contents; clicking a session opens the transcript. Search Engram to explore a different part of the database.

For responsiveness the graph displays at most 120 loaded memory/context cards and 100 sessions at once, or 160 sessions within a selected project. The graph shows its visible-subset counts. These display limits are independent of transcript age and are not payment restrictions.

Local history sources

Use Connections or the nexo.sources.* application settings for custom paths. Empty source-path settings use autodetection, except Grok Bot and imports, which require a chosen archive. Imports can point at JSONL transcripts, JSON exports, or explicitly marked Grok Bot Markdown. Imported normalized JSON remains an imported conversation and cannot acquire native resume privileges from an arbitrary provider field.

Cursor also checks sibling workspaceStorage and profiles directories. When running inside Cursor, Nexo adds the editor-reported storage location to support custom user-data paths. Current JSONL and older text agent transcripts are supported. Available database and transcript copies merge into one conversation without adding their token totals twice.

Cursor's supported composer/bubble layouts are read from an in-memory SQLite snapshot, including validated committed WAL frames when present. The source database is never opened for writing. If a snapshot is inconsistent, incomplete, too large, or uses an unsupported format, Connections displays a diagnostic.

The default limits are 64 MiB per transcript and 256 MiB for a Cursor database plus WAL. Both are configurable. Large databases need memory proportional to their size; a multi-GB Cursor history may require a smaller export or a future disk-backed reader. No history is excluded solely because it is older than seven days.

The extension runs on the local editor side. Cloud-only conversations and history on a different SSH/container host do not appear automatically. Native OpenCode and Copilot adapters are not included in 0.3.0; use normalized exports for other tools. Grok Build and Grok Bot are separate sources. Grok Bot support imports explicit context archives; it does not read a live cloud conversation automatically. Gemini support targets Gemini CLI, not the Gemini website. Other hosted conversations need a supported export.

Gemini, Grok and Antigravity details

• Gemini CLI: reads both legacy session-*.json and newer JSONL message/update logs. Project names are resolved from bounded .project_root markers or Gemini’s project registry. Rewound/discarded branches are not invented; the reader reports retained-history limits.
• Grok Build: reads chat_history.jsonl with the session’s summary.json and usage.json sidecars. This is the model’s retained raw context, which can be compacted or rewound; it may not reproduce every earlier UI message. Nexo does not read Grok authentication files.
• Antigravity: reads documented plaintext brain/<id>/.system_generated/logs/transcript.jsonl logs using a conservative compatibility parser. The line schema is not a versioned public API. Where no readable transcript exists, standard task/plan/walkthrough files appear as Artifacts only, not a fabricated conversation. Opaque legacy database/protobuf files are not decoded.

The source archive includes separate researched format notes for all three adapters. Each session exposes source notes so missing metadata and format limitations remain visible.

Usage, costs, and recorded operations

• Token numbers come from local source records. Missing usage is labeled unavailable. Codex cumulative totals are not summed repeatedly; cache categories are normalized so cached input is not counted twice.
• Mixed-model sessions are labeled Multiple models. Their aggregate tokens are not attributed to the final model and are left unpriced.
• Cost is optional. Configure exact-model USD rates per million tokens in nexo.pricing. Unknown models or missing applicable cache rates remain unpriced. These are estimated API-equivalent costs, not subscription invoices or actual charges.
• The activity chart groups conversations by their latest recorded activity date. It does not measure daily consumption for a session spanning multiple days.
• Plan limits display only supplied percentages, with their capture time and expired/reset state. They are never inferred from local token totals. Refresh account limits on Codex uses the official local codex app-server protocol and its account/rateLimits/read method with your already signed-in CLI account. It does not start a model turn. Set nexo.codex.executable if the editor cannot find Codex. Cursor/Grok Bot account readings, Claude status-line readings, Antigravity CLI quota refresh and optional Cursor account CSV reports have their own explicit sources and timestamps. Cursor/Grok Bot account reads use only the explicitly connected Cursor installation. Nexo does not inspect browser cookies, refresh tokens, or unrelated credentials.
• File operations are evidence of tool requests. Their presence is not proof execution succeeded. Edit diffs show recorded fragments; Write contents are shown without inventing the previous file. Nexo does not apply, undo, or reapply changes to your workspace.

Example pricing configuration (replace with rates you choose; these are illustrative, not current provider prices):

{
  "nexo.pricing": {
    "your-exact-model-id": {
      "input": 3,
      "output": 15,
      "cacheRead": 0.3,
      "cacheWrite": 3.75
    }
  }
}

Privacy and security

Nexo has no telemetry, hosted backend, extension subscription, or AI API charges. Local transcript content stays in the editor process unless you explicitly export/copy it or save chosen content to your local Engram. Your existing Engram server's own sync configuration is separate from Nexo; its behavior still applies in HTTP mode. After you connect Cursor usage, Nexo authenticates read-only requests to Cursor’s fixed first-party endpoints; local conversation contents are not sent.

The webview uses a restrictive content security policy. Transcript HTML, executable command links, and remote images are disabled. Engram and the optional Codex/Antigravity quota readers are launched without a shell; executable settings are application-scoped. The optional Claude bridge forwards the existing user-configured status-line command through its shell, preserving stdin and output; transcript text is never interpolated into that command. Resume accepts validated native session IDs and only runs after an explicit user action in a trusted workspace. Project-file opening validates real paths to reject traversal and symlink escapes. Restricted mode can browse history but cannot launch Engram, refresh account limits through a CLI, or resume an assistant.

Demo data is entirely synthetic. Demo mode cannot save to Engram, change Claude usage setup, import real account usage, resume sessions, or open example project files.

Develop and build

Use Node.js 22 or later for the development toolchain. The bundled extension targets Node.js 18-compatible syntax; the editor engine requirement is VS Code 1.96+.

npm ci
npm run check
npm test
npm run package

The installer is written to dist/nexo-ai-hub-0.3.1.vsix. The source archive includes the lockfile, source, tests, build scripts, and documentation. Runtime dependencies are bundled; installation does not run npm.

For UI testing:

npx playwright install chromium
npm run test:ui

For the optional actual-Engram integration test, set NEXO_ENGRAM_BIN to a trusted Engram executable before running the test suite. That test creates a fresh temporary workspace/data directory and uses only synthetic observations. Without that variable it is explicitly skipped. Default Engram tests use isolated local HTTP servers and a fake MCP subprocess.

The suite covers parsing, cache/cumulative accounting, immutable Cursor WAL snapshots, safe resume IDs, export/handoff behavior, extension-host wiring, and the browser interface. Browser checks use a mocked VS Code bridge. Actual installation on your own Cursor/VS Code and your existing history remains the final environment-specific check.

Press F5 from the source workspace to open a development host after npm run build.

Troubleshooting

For exact source-format and transport evidence, see docs/source-formats.md and docs/engram-integration.md in the source archive. Third-party license text is included in THIRD_PARTY_NOTICES.md.