Agent Integration

Agent integration

For a repository-aware first installation, use the canonical prompt in Getting Started. It detects the package manager and existing Ragmir state, asks before changes or downloads, then configures and verifies the selected clients.

Ragmir indexes selected project files locally and gives the AI or automation you choose cited passages through CLI, TypeScript, or a stdio MCP server. Core keeps the corpus and generated index on the workstation, works offline by default with local-hash, and never uploads source documents or calls a model.

Choose the handoff

Path	What stays local	What crosses the boundary
Hosted coding agent	Corpus, index, and retrieval	Only passages returned to the consumer
Local coding agent or script	Corpus, index, retrieval, and consumer	Nothing unless that consumer uses a network service
Ragmir Chat	Corpus, index, retrieval, and answer generation	One explicit model download during setup, then no network

Install native helpers

rgr setup --agents claude,codex,kimi,opencode,cline
rgr doctor

Setup creates an ignored .ragmir/run.cjs project runner, local MCP helpers, and project-scoped skill links for the selected clients. Re-run installation when you need a different scope or copy mode:

rgr install-agent --agents codex,claude

Project scope is the default. --mode copy is a fallback for filesystems that cannot follow symlinks. Ragmir refuses to overwrite unmanaged same-name skills unless --force is explicitly selected.

Use Ragmir through MCP

Read ragmir://context first when the client supports resources. It identifies the active knowledge base, readiness, freshness, source coverage, and available operations.

Resource	Use
ragmir://context	Active base identity, readiness, freshness, coverage, and capabilities
ragmir://sources	Source coverage, skipped-file counts, and index drift, with complete totals and per-file lists capped at 50

Use compact retrieval first, then expand one returned citation only when more context is required:

1. ragmir_status verifies the active base.
2. ragmir_route_prompt decides whether retrieval is useful.
3. ragmir_search, ragmir_ask, or ragmir_research returns bounded cited evidence.
4. ragmir_expand opens one exact indexed chunk with a small neighbor window.
5. ragmir_audit and ragmir_security_audit verify coverage and privacy posture.

The server also exposes ragmir_evaluate for local golden-query checks and ragmir_usage_report for metadata-only retrieval usage. Search, ask, research, expansion, audit, and evaluation accept an optional maxBytes. Every tool and resource JSON response stays below the configured mcpMaxOutputBytes budget and an absolute 1 MiB ceiling.

ragmir_ask returns cited evidence, not a model-generated answer. A hosted consumer receives the passages it requests, so use a local consumer when that handoff is not acceptable.

Advanced: MCP safety annotations and server lifecycle

Every tool advertises non-destructive behavior. Search, ask, research, and evaluation conservatively advertise open-world behavior because explicitly enabled semantic models may download public weights. The prompt router, security audit, and usage report also advertise read-only, idempotent behavior. Other tools conservatively do not because they can initialize ignored local state or append metadata-only access logs. ragmir_evaluate accepts only an existing project-relative golden file and rejects absolute paths, traversal, and symlinks outside the project. Strict mode returns that relative path, replaces evaluation failures with a generic message, and masks configured model, storage, source, and access-log paths in diagnostic responses.

Embedding applications can use createMcpServer(cwd) to construct a server around a caller-owned transport, or connectMcpServer(transport, cwd) to connect it and receive a closeable handle. serveMcp(cwd) remains the simplest local stdio entry point. A server lazily reuses one RagmirClient per effective configuration for its pinned project root, refreshes it after configuration changes, and closes the active client during shutdown. Request cancellation reaches retrieval, audit, evaluation, security, usage, and bounded resource operations. Native filesystem and LanceDB calls that cannot receive an AbortSignal directly are checked immediately before and after the call. Ragmir does not open an HTTP port, so a network-facing host owns its authentication and authorization boundary.

Team knowledge bases

Ragmir keeps one private local index per developer. For a Git-backed team, the current branch upstream is the only declared authority. Configure it once, then use one command:

rgr team sync

The everyday workflow

flowchart LR
    A["Push a reviewable change"] --> B["Merge to the declared upstream"]
    B --> C["rgr team sync"]
    C --> D["Safe fast-forward, if possible"]
    D --> E["Incremental local ingest"]
    E --> F["Ready private index"]

Loading

1. A developer opens or updates a pull request (or merge request).
2. The team reviews and merges it into the declared upstream.
3. Other developers run rgr team sync to update sources and private local evidence together.

Git already shows what changed and needs review. Ragmir does not add labels, snapshots, or another source of truth to this normal path. The command reports current, updated, or one clear action. It fetches only the declared upstream and fast-forwards only a clean non-divergent branch with no unpublished commits. It never stashes, resets, rebases, creates a merge commit, chooses another branch, or deletes the active index.

Need	Command
Normal update	rgr team sync
Keep branch updates manual	rgr team sync --no-pull
Preview only	rgr team sync --check
Work offline	rgr team sync --no-fetch
Enforce in automation	rgr team sync --strict --json

A dirty, ahead, diverged, detached, untracked, or no-upstream branch is never rewritten. Fetch or ingestion failure keeps the last valid local index available. Resolve the Git state through the normal pull-request or merge-request workflow, then run the same command again.

The ignored .ragmir/config.json remains local. If every workstation needs the same source contract, version a reviewed template and apply it during setup. Never synchronize an actively written .ragmir/storage/ directory.

Exact drift is an advanced diagnosis

Snapshots are for a non-Git authority, such as Drive, or a specific configuration and per-file comparison. They are not part of the normal Git workflow:

Compare two authorized snapshots without sharing source text

rgr team snapshot --label local --output .ragmir/team/local.json
rgr team compare .ragmir/team/local.json --local-label peer

The snapshot contains relative paths, checksums, readiness, version, and index settings, never source text or an absolute project path. Treat it as sensitive metadata. The comparison identifies configuration drift, local-only files, peer-only files, changed files, and ordered repair actions. Use the declared non-Git authority to choose a side. Existing v2.19 snapshots remain compatible.

An agent should run rgr team sync --json before relying on a Git-backed shared knowledge base. When synchronization is blocked, it should warn the user, present the first recommended action, and state when the last valid index may be older than upstream. It must never stash, reset, rebase, or overwrite source files.

Monorepos

rgr bases --json
rgr --project-root apps/web search "checkout contract"

Ragmir selects the nearest .ragmir/config.json. Root and nested bases keep separate storage. Generated MCP helpers pin RAGMIR_PROJECT_ROOT, and nested bases use deterministic server names so an agent does not silently query the wrong index.

If a client can see more than one Ragmir server, call ragmir_status and verify knowledgeBaseId before retrieval.

Canonical source: docs/agent-integration.md.