Getting Started

Getting started

This guide takes a repository from no Ragmir state to verified cited context for a coding agent or script. Ragmir requires Node.js 22 or later, indexes selected files locally, and keeps generated state under the ignored .ragmir/ directory. The default local-hash path performs ingestion and retrieval offline.

Guided setup

Paste the prompt below into the coding agent that already works with the repository. It inspects first, asks one concise approval batch, then adapts installation, sources, agent integrations, team diagnostics, optional semantic retrieval, Chat, TTS, and verification.

Option 1: paste this into your coding agent

Set up Ragmir in this repository. Work interactively: inspect first, ask one concise numbered batch of questions, wait for my answers, then execute. Never assume consent for dependency changes, model downloads, replacing skills, or sharing data.

Outcome: Core installed with the repository's package manager; useful sources selected; secrets and generated noise excluded; tools connected; cited retrieval verified. Semantic retrieval, team features, Chat, and TTS are optional.

1. Inspect without changes:
- Find the repository or monorepo root. Read package.json packageManager, lockfiles, workspace and Node/version-manager files, .gitignore, existing .ragmir state, README, AGENTS/CLAUDE/CODEX guidance, docs, specs/ADRs, apps/packages, important config, source, and tests.
- Detect Node 22+ and pnpm, npm, Yarn, or Bun. Prefer packageManager, then the lockfile. Respect workspace-root flags and mise/asdf/Volta. Never create a second lockfile. If signals conflict, ask.
- If Ragmir exists, inspect its version, config, status, sources, and rgr upgrade --check before changing it.

2. Ask only what the repository did not answer, then wait:
1) Which repository/monorepo base should own the knowledge base, and are nested app bases wanted?
2) Which clients: Claude Code, Codex, Kimi, OpenCode, Cline, another MCP client, or none?
3) Keep default offline local-hash, or allow one semantic-model download for better natural-language retrieval?
4) Solo or team? If team, is Git upstream authoritative, and should safe pulls be automatic or disabled with --no-pull?
5) Core only, or optional Chat? For Chat choose lite (~0.49 GB), fast (~3.35 GB), or quality (~5.15 GB).
6) Optional TTS? Ask language (en/fr/es offline; ja/th/zh require explicit Edge unless a local model is supplied) and whether text may reach Edge.
7) Which private/external folders are allowed, which must never be indexed, and may I install packages, edit local config, and run approved downloads now?

3. Implement after approval:
- Install @jcode.labs/ragmir as a dev dependency with the detected manager. Install Chat/TTS only if selected, at a compatible version.
- Run the matching rgr setup --no-ingest --agents <selected> command. Keep project scope. If a same-name skill is unmanaged, show the diff and ask before --force.
- Build a narrow .ragmir/config.json. Prefer stable relative globs for root guidance, docs/specs/ADRs, package READMEs/manifests, useful app config, and source/tests that explain behavior. Include locales only when useful.
- Exclude .env*, credentials, keys, unapproved dumps/customer data, dependencies, generated/build/cache/coverage/log folders, vendored code, binaries/media, and .ragmir storage/models. In monorepos, keep nested bases scoped and shared knowledge at root.
- Run preview and audit --unsupported before ingest. Review redactions, unsupported/oversized files, duplicates, chunks, and sensitive paths. Fix config first, then ingest.
- For an existing install, use rgr upgrade and doctor --fix as indicated. Never delete the active index first. Rebuild only for incompatible embedding, chunk, or index-policy changes.
- Enable semantic retrieval, preload Chat, or preload TTS only after consent. Use non-sensitive TTS preload text.
- For Git teams, run rgr team sync. It safely pulls and ingests; --no-pull keeps Git manual. Snapshots are advanced diagnostics.

4. Prove the result:
- Run rgr doctor --deep, rgr audit --unsupported, and rgr security-audit.
- Run representative searches with citations and --explain. Create a small local golden suite for project questions and run rgr evaluate; do not weaken gates to pass.
- Report detected tools, answers, packages, downloads, config/sources/exclusions, changed files, readiness, retrieval results, team status, and exact remaining actions.

Never commit .ragmir, corpus files, models, snapshots, logs, or secrets. Never claim offline, semantic, team synchronization, or retrieval quality without evidence.

Manual setup

1. Install Core in the repository

With pnpm:

pnpm add -D @jcode.labs/ragmir

With npm:

npm install --save-dev @jcode.labs/ragmir

At a pnpm workspace root, use pnpm add -Dw; otherwise install Ragmir in the package that owns the source files. The examples below use pnpm exec rgr. Replace it with npx rgr in an npm project. Core does not install the optional Chat or TTS packages. Add either package separately only when the workflow needs local answer generation or audio rendering.

2. Initialize local state

pnpm exec rgr setup --agents codex

Setup creates .ragmir/config.json, adds the local state directory to Git ignore rules, prepares the project runner, and installs the selected project-scoped agent helper. Replace codex with a comma-separated list such as claude,codex,kimi,opencode,cline. Omitting --agents installs helpers for every supported agent; use rgr init instead when a script only needs basic CLI or TypeScript configuration. Core uses the offline local-hash retrieval provider unless semantic retrieval is selected explicitly.

3. Select the evidence

Add only the paths the knowledge base should search. Entries may be files, directories, globs, or ! exclusions.

pnpm exec rgr sources add "docs/**/*.md" "src" "!docs/archive/**"
pnpm exec rgr sources list

Use separate Ragmir bases when parts of a monorepo have different trust boundaries or unrelated knowledge. rgr bases shows which base is active from the current directory.

4. Preview before indexing

Preview applies the active extraction, redaction, and chunking rules without writing an index.

pnpm exec rgr preview --path docs --max-files 5 --max-chunks 3

Review the source paths, redacted text, structural context, citations, and chunk-size summary. Adjust the source list or configuration before continuing if the preview includes material that should not be retrievable.

5. Ingest and search

pnpm exec rgr ingest
pnpm exec rgr search "Which decision changed the rollout?" --top-k 5

Ingestion is incremental. Each result identifies the source file and indexed chunk, with line ranges and PDF pages when available. Use --compact for a smaller machine-readable handoff or --json in automation.

6. Verify the knowledge base

pnpm exec rgr doctor
pnpm exec rgr audit --unsupported
pnpm exec rgr security-audit

• doctor checks setup, index freshness, and local integrations.
• audit --unsupported compares configured sources with the index and reports skipped files.
• security-audit checks ignored state, redaction, retrieval bounds, and other local controls.

After updating the package, check compatibility before retrieval with the new runtime:

pnpm exec rgr upgrade --check
pnpm exec rgr upgrade

The second command only rebuilds when required. It writes an incompatible replacement to a separate generation, validates it, and activates it atomically without deleting the current valid index first. Ordinary source edits only need incremental ingest. A current result can still include a non-blocking privacy advisory; inspect it with rgr security-audit without deleting the index.

7. Sync a Git-backed team

After a reviewed change merges into the current branch upstream, each developer can refresh source and index in one step:

pnpm exec rgr team sync

The command fast-forwards only a clean non-divergent branch, then ingests changed sources. It never stashes, resets, rebases, or deletes the valid index. Use --no-pull when branch updates must stay manual, and --check to preview. Snapshots are only for a non-Git authority or exact drift diagnosis. See Agent Integration for the full workflow.

Supported content

Ragmir handles common project and knowledge-base material:

• Markdown, plain text, source code, configuration, logs, CSV, JSON, JSONL, and YAML;
• PDFs with page-aware citations and optional local OCR for blank pages;
• DOCX, PPTX, XLSX, OpenDocument files, EPUB, HTML, RTF, email, and notebooks;
• additional text extensions explicitly configured by the project.

Images and legacy .doc files need an explicitly configured local extractor. Ragmir does not claim universal binary support, so use audit --unsupported to see exactly what was skipped and why.

Choose the next interface

Goal	Continue with
Operate the index from a terminal or script	CLI Reference
Adapt a complete project workflow	Use Cases
Give a coding agent or script bounded cited passages	Agent Integration
Embed retrieval in a script or stateful Node.js worker	TypeScript API
Tighten local privacy controls	Security Hardening
Generate answers with an optional local model	Offline Chat
Render a local audio brief	Offline TTS

The repository README is the canonical source for installation, supported content, and current workflows.