Getting started

Welcome to Engrym. This page walks you through installing the CLI, setting up your agent, and asking your first question of the Brain, in about five minutes.

You'll need Node.js 18 or later.

1. Install the CLI

Engrym ships as an npm package:

npm install -g @engrym/cli

Verify the install:

engrym --version

2. Create a project in the dashboard

Sign up at dashboard.engrym.com and create a project. The onboarding flow generates a setup token (a per-project credential) and shows you a one-line connect command.

3. Set up your agent

Open a terminal in your repo folder, the folder where your .git lives, and run the command from the dashboard:

ENGRYM_SETUP_TOKEN=<your-token> npx @engrym/cli setup claude-code

Replace claude-code with your agent: claude-code, cursor, codex, gemini or windsurf. The project is resolved from the token. The command does two things:

  1. Connects Engrym to your agent. It saves the token once, in ~/.engrym/config.yaml (file mode 600), and registers the Engrym MCP server with your agent. The token is never written into the agent's own config.
  2. Writes Engrym's files into the folder you ran it in: Engrym's instructions block in your agent's instruction file (CLAUDE.md, AGENTS.md, GEMINI.md or .cursor/rules/engrym.md), ENGRYM.md, and the engrym-extract command.

If one of those files already has writing in it that Engrym did not put there, the command lists those files and asks once before it changes them. In your agent's instruction file, your own text outside the Engrym block stays as it is. Add --yes to answer yes ahead of time. The files belong to this repo, so run the command again in each project you use with Engrym.

claude-desktop is a setup target too. It has no project folder, so for it the command only registers the server. On ChatGPT, the web or iOS, where npx can't run, use the hosted connector at https://engrym-mcp-remote.fly.dev/mcp instead; you authorize once in the browser.

Check the connection:

engrym status

See MCP setup for per-agent details and the hosted connector, and CLI reference for every flag.

4. Bring in your docs and extract them

If your project knowledge already lives in Markdown, import it:

engrym import obsidian-vault ~/vaults/my-project
engrym import markdown-folder ./docs

Both commands print an import id; track progress with:

engrym import status <importId>

You can also create documents directly:

engrym doc create docs/architecture/providers.md --content "# Provider strategy"

A new project extracts on your own agent: your agent reads each Markdown document and proposes the decisions, conventions and constraints in it, on its own model and plan, with no API key. Start it from your agent:

The command needs an agent with terminal access. In a chat app, paste the extract prompt from the dashboard instead. What your agent extracts stays provisional until you accept it in Review. At the start of a session, Engrym's instructions tell your agent to ask you before extracting documents that are waiting.

Prefer extraction on Engrym's servers? Add your own provider API key under Settings → Extraction and switch the extraction mode. It is optional, and usage is billed to that key.

5. Query the Brain

Ask your AI agent (Claude Code, Cursor, Windsurf, Gemini CLI, Codex, ChatGPT) a question about your project. With the setup from step 3 in place, the agent surfaces the relevant atoms automatically. Or query directly from the terminal:

engrym brain query "provider strategy"

brain query is full-text search across atoms; it needs the project connection from step 3. For the composed context bundle an agent sees, try:

engrym brain context

Next steps