openContext
Get started

Install

Start here

openContext runs on your computer. This website explains the product; it does not host your vault or a sign-in account.

New to openContext? The app and a separate demo are coming soon. Email Alec for beta access. A public download is not available yet. If you already have an invitation, open the private repository, clone it, and follow the setup instructions below.

Already installed?

From your openContext checkout, run npm run dev and leave the terminal open. Once it reports that the app is ready, open your local workspace. Your files and any sign-in stay on your own installation.

If the workspace does not open, check the terminal for a startup error and run npm run doctor in the checkout for an offline diagnostic. The link can only work on the computer where openContext is running.

Installation guide

Installing OpenContext is three commands on a machine with Node 22 and git: npm run setup, npm run doctor, npm run dev. (Acronyms on this page: CLI is the command-line tool, MCP is the Model Context Protocol, API is the programming interface a service exposes, and an API key is the credential that identifies your account with a provider.) It runs on macOS and Linux (Windows is best effort), needs one model credential or none at all in demo mode, and writes nothing outside the folder you point it at. The repository is private during the closed beta; invitees clone it from GitHub.

Prerequisites

  • Node 22 or newer (node --version; the repo ships an .nvmrc) and the npm that comes with it.
  • git installed where your shell can find it. Vault versioning, rollback, and repository ingestion all shell out to it.
  • A model credential, one of: an Anthropic API key (the credential that identifies your account with Anthropic), an OpenRouter key, or a logged-in Claude Code CLI (claude, then /login). Nothing yet? Demo mode below runs the whole pipeline on a simulator.
  • macOS and Linux are supported. Windows is best effort: the scripts avoid shell-specific syntax (npm run dev, npm run demo, npm start work), but npm run free-ports relies on lsof and does nothing there.
  • Disk: about 520 MB of node_modules after setup, as observed on one macOS machine; it varies by platform. Roughly 320 MB of that is the Claude runtime the Agent SDK (Anthropic's software development kit) downloads for your platform from the npm registry as an optional dependency at install time; no separate Claude Code install is needed.

Quick start

npm run setup          # npm install + web install + web build, in one go
npm run doctor         # free: names anything missing (Node, git, credential, ...)
npm run dev            # web on http://localhost:5173, API on loopback port 4477

Drop a document onto the Intake page and watch the live feed. npm run doctor writes nothing, spends nothing, and kills nothing: it checks the Node version, git, the Agent SDK's bundled runtime, the web build, .env, which model credential the server would see (presence only, never a value), the vault, and whether the ports are free, and exits 1 only on a hard failure. npm run doctor:live spends one small model call to prove the SDK authenticates with the credential and model the server would actually use.

Credentials

The ingestion agent runs on the Claude Agent SDK, which uses whichever credential it finds, in this order:

  1. an Anthropic API key pasted in Settings, Models, kept in vault/_state/anthropic.json (readable only by your own user account, never returned by the server, unreadable to the agents) and used by the next run, no restart; or
  2. ANTHROPIC_API_KEY in <repo>/.env. The server reads .env itself at boot, so restart after editing it. cp .env.example .env to begin; the example file lists every setting; or
  3. a logged-in Claude Code CLI: run claude in a terminal once and /login.

Prefer OpenRouter? Settings, Models can route every run through openrouter.ai instead: paste an OpenRouter key, flip the provider, and pick any model they serve. Or in .env: OPENROUTER_API_KEY=sk-or-... plus OPENCONTEXT_PROVIDER=openrouter. Vault-building leans on tool use, so models that support tool use are recommended.

Demo mode

No credential yet? Demo mode runs the full pipeline with a deterministic simulator instead of the model, spending no tokens:

npm run demo                         # any platform, disposable vault

The demo uses a temporary vault and cannot switch into your personal vault. Restart normally to return to your own files. The low-level OPENCONTEXT_FAKE_AGENT=1 test flag does not provide this isolation by itself and should only be used with an explicitly configured scratch vault.

Point your coding agents at it

With the app running, install the opencontext CLI from a repository you code in. The install also links that repository to the graph by writing a managed block into its AGENTS.md, CLAUDE.md, CODEX.md, and README.md. Run it yourself, or paste it at your agent:

curl -fsSL http://127.0.0.1:4477/install.sh | sh

on macOS and Linux, or on Windows (PowerShell):

irm http://127.0.0.1:4477/install.ps1 | iex

The package is built and served by your own local server; nothing comes from the internet or a registry. npm uninstall -g opencontext removes it. For Claude Desktop, Cursor, Codex, and other MCP clients, Settings, Connect your AI tools shows a ready-made install snippet per client for the MCP server. The for-agents page covers both surfaces.

Where the vault lives

The vault is a plain folder of markdown. At boot the server resolves it in this order: a vault chosen in the app (Settings, Environment, Switch vault), then OPENCONTEXT_VAULT from the environment or .env, then <repo>/vault. The default lives inside the app checkout, and the server says so at every boot: keep it elsewhere by setting OPENCONTEXT_VAULT to a folder outside the checkout, or switch in Settings. Boot refuses to scaffold a vault into a folder that already holds files OpenContext did not create unless OPENCONTEXT_VAULT_ADOPT=1 grants it.

Upgrade

git pull
npm run setup      # dependencies may have changed, and the web build must be redone
npm run typecheck
npm test
npm run dev

Nothing in the vault is migrated by an upgrade; the vault format is markdown and stays readable across versions. If the distillation logic changed, the app may report already-ingested sources as stale and offer to re-distill them. It never does so on its own.

Back up and restore

The vault is a git repository with one commit per operation, so local history is already a backup against your own mistakes. For an off-machine copy, connect a GitHub or GitLab account in Settings, Environment, point the vault at an empty remote repository, and push; or press Download my vault for a zip of every knowledge file, the _sources/ originals, and the full git history. Restore is a clone plus a pointer:

git clone <the vault remote> ~/opencontext-vault
# then set OPENCONTEXT_VAULT=/Users/you/opencontext-vault in .env and restart,
# or use Settings > Environment > Switch vault to point at it

A restore from the remote brings back the knowledge graph, not the secrets: reconnect Drive, Gmail, X, and the forges, and re-enter the model key in Settings, Models.

Development

npm run dev           # tsx watch server (4477) + vite (5173, proxies /api)
npm run typecheck     # server + web
npm test              # the whole offline suite - no network, no tokens, no spend

Every push and pull request runs the same three on Node 22 in GitHub Actions, with every model credential blanked so a green continuous-integration run can never have spent anything. This is release 0.2.0; the changelog has what changed.