@morphllm/gitmorph-sdk

@morphllm/gitmorph-sdk

Agent-native TypeScript SDK for reading, searching, and navigating Git repositories through GitMorph. No cloning. Every operation is a single HTTP call against a server-side mirror.

Built for AI coding agents that need to understand codebases: read files with line ranges, grep across repos, glob for file patterns, list directories, walk commits. All server-side, all fast.

npm install @morphllm/gitmorph-sdk

Quick start

import { GitMorph } from "@morphllm/gitmorph-sdk";

const gm = new GitMorph();
const repo = gm.repo("facebook/react");

// Read a file
const file = await repo.readFile("package.json");

// Grep for a pattern
const results = await repo.grep({ pattern: "useState" });

// Glob for files
const tsFiles = await repo.glob({ patterns: ["**/*.ts"] });

Give your agent access to any repo

Paste this into Claude Code (or any agent with tool-use) to give it read access to any mirrored repository:

You have access to the @morphllm/gitmorph-sdk for reading Git repositories without cloning.
The SDK is already installed and authenticated via ~/.config/gm/config.json.

To use it, write a quick TypeScript script and run it with `npx tsx`:

```ts
import { GitMorph } from "@morphllm/gitmorph-sdk";
const gm = new GitMorph();
const repo = gm.repo("owner/repo");
```

Available methods on `repo`:
- `repo.readFile(path, { ref?, lines?: [{ start, end }] })` - read a file, optionally specific line ranges (1-indexed, inclusive)
- `repo.getFileContents(paths[], { ref? })` - batch read multiple files in one call
- `repo.grep({ pattern, language?, caseSensitive?, maxMatches?, page? })` - server-side code search within the repo
- `repo.glob({ patterns[], ref?, prefix?, sizes?, limit? })` - find files matching glob patterns (e.g. `["**/*.ts", "!**/*.test.ts"]`)
- `repo.listDir({ path?, ref?, recursive? })` - list directory contents
- `repo.listBranches({ page?, limit? })` - list branches
- `repo.listCommits({ sha?, path?, since?, until?, page?, limit? })` - list commits

Available methods on `gm` (instance-wide):
- `gm.grepAll({ pattern, language?, page?, limit?, sortByStars? })` - search code across ALL repos
- `gm.mirror(source, options?)` - mirror a GitHub/GitLab/Gitea repo (e.g. `gm.mirror("facebook/react")`)
- `gm.getRepositoryInfo("owner/repo")` - get repo metadata

Use these to explore, search, and read code. Prefer grep and glob over listing directories manually.

Drop-in LLM tools

The SDK ships framework-native tool adapters under subpath exports. Import, pass to your agent, go. No hand-written schemas, no dispatcher wiring.

Every adapter exposes the same factories:

• createGitmorphTools(gm, opts?) — multi-repo; every tool takes repo: "owner/name".
• createGitmorphRepoTools(gm, "owner/name", opts?) — pinned to one repo; tools drop the repo arg.

Each adapter is an optional peer dependency — you only install what you use.

Vercel AI SDK

npm install ai zod

import { GitMorph } from "@morphllm/gitmorph-sdk";
import { createGitmorphRepoTools, GITMORPH_SYSTEM_PROMPT } from "@morphllm/gitmorph-sdk/ai";
import { anthropic } from "@ai-sdk/anthropic";
import { generateText } from "ai";

const gm = new GitMorph();
const { text } = await generateText({
  model: anthropic("claude-sonnet-4-6"),
  system: GITMORPH_SYSTEM_PROMPT,
  tools: createGitmorphRepoTools(gm, "facebook/react"),
  prompt: "What testing framework does this repo use? Read package.json to confirm.",
  maxSteps: 5,
});

Pass only as a const tuple to narrow the return type — autocomplete shows exactly the tools you asked for:

const tools = createGitmorphTools(gm, { only: ["gm_grep", "gm_read_file"] as const });
// tools has exactly { gm_grep: Tool; gm_read_file: Tool }

Anthropic SDK

npm install @anthropic-ai/sdk zod zod-to-json-schema

import Anthropic from "@anthropic-ai/sdk";
import { GitMorph } from "@morphllm/gitmorph-sdk";
import { createGitmorphTools, GITMORPH_SYSTEM_PROMPT } from "@morphllm/gitmorph-sdk/anthropic";

const anthropic = new Anthropic();
const gm = new GitMorph();
const { tools, handleToolUse } = createGitmorphTools(gm, { cacheControl: true });

const messages: Anthropic.Messages.MessageParam[] = [
  { role: "user", content: "Find every useEffect in facebook/react" },
];

let msg = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 4096,
  system: GITMORPH_SYSTEM_PROMPT,
  tools,
  messages,
});

while (msg.stop_reason === "tool_use") {
  const uses = msg.content.filter((b): b is Anthropic.Messages.ToolUseBlock => b.type === "tool_use");
  const results = await Promise.all(uses.map(handleToolUse));
  messages.push({ role: "assistant", content: msg.content });
  messages.push({ role: "user", content: results });
  msg = await anthropic.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 4096,
    system: GITMORPH_SYSTEM_PROMPT,
    tools,
    messages,
  });
}

handleToolUse never throws. Errors become tool_result blocks with is_error: true so the model can recover in the next turn. cacheControl: true attaches Anthropic prompt caching to the tool list — stable tool sets become a cached prefix of every request.

OpenAI SDK

npm install openai zod zod-to-json-schema

import OpenAI from "openai";
import { GitMorph } from "@morphllm/gitmorph-sdk";
import { createGitmorphTools, GITMORPH_SYSTEM_PROMPT } from "@morphllm/gitmorph-sdk/openai";

const openai = new OpenAI();
const gm = new GitMorph();
const { tools, handleToolCall } = createGitmorphTools(gm);

const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
  { role: "system", content: GITMORPH_SYSTEM_PROMPT },
  { role: "user", content: "Find every useEffect in facebook/react" },
];

for (let step = 0; step < 10; step++) {
  const res = await openai.chat.completions.create({ model: "gpt-4o", tools, messages });
  const msg = res.choices[0]!.message;
  messages.push(msg);
  if (!msg.tool_calls?.length) break;
  const results = await Promise.all(msg.tool_calls.map(handleToolCall));
  messages.push(...results);
}

MCP (Claude Desktop / Cursor / Claude Code)

Zero-code path. Add GitMorph to your MCP client's config:

{
  "mcpServers": {
    "gitmorph": {
      "command": "npx",
      "args": ["-y", "@morphllm/gitmorph-sdk", "mcp"],
      "env": { "GM_TOKEN": "gm_..." }
    }
  }
}

No install. No global CLI. The bin entry in this package registers gitmorph-mcp, and npx -y runs it directly. Auth resolves from the env block, from ~/.config/gm/config.json, or from your shell environment.

To embed the MCP server in your own Node process:

import { GitMorph } from "@morphllm/gitmorph-sdk";
import { startGitmorphMcpServer } from "@morphllm/gitmorph-sdk/mcp";

await startGitmorphMcpServer(new GitMorph());

Tool reference

All adapters expose the same 9 tools by default (gm_mirror is opt-in via includeMirror: true):

Tool	Purpose
gm_read_file	Read a file, optionally a specific line range
gm_read_files	Batch-read multiple files in one call
gm_grep	Search file contents within one repo (regex or keyword)
gm_glob	Find files by path pattern (**/*.ts)
gm_list_dir	List entries in a directory
gm_list_branches	List branches with head commits
gm_list_commits	List commits, filterable by path or date range
gm_grep_all	Search code across all mirrored repositories
gm_get_repo_info	Fetch metadata for a repository
gm_mirror	Opt-in. Mirror a GitHub/GitLab/Gitea repo into GitMorph

Customizing

Every factory accepts the same options:

createGitmorphTools(gm, {
  only: ["gm_grep", "gm_read_file"] as const,  // whitelist (narrows the return type)
  exclude: ["gm_list_branches"],               // drop specific tools
  rename: { gm_grep: "search_code" },          // rename to match your agent's naming scheme
  includeMirror: false,                         // enable the opt-in gm_mirror tool
  maxOutputBytes: 262_144,                      // cap per-call output (Anthropic/OpenAI/MCP)
});

GITMORPH_SYSTEM_PROMPT is re-exported from every subpath — append it to your system message to give the model explicit guidance on when to reach for each tool.

Auth

Credentials resolve in order:

• Constructor options: new GitMorph({ token: "...", host: "..." })
• Environment variables: GM_TOKEN, GM_HOST
• Config file: ~/.config/gm/config.json

The host defaults to gitmorph.com if not set.

API reference

GitMorph (client)

Method	Description
gm.repo("owner/repo")	Get a repo handle for file/search operations
gm.getRepositoryInfo("owner/repo")	Repo metadata (branches, stars, language, etc.)
gm.mirror(source, opts?)	Mirror a repo from GitHub/GitLab/Gitea into GitMorph
gm.grepAll({ pattern, ... })	Search code across all repos on the instance

GitMorphRepo (per-repo operations)

Method	Description
repo.readFile(path, opts?)	Read a file, optionally specific line ranges
repo.getFileContents(paths[], opts?)	Batch read multiple files in one call
repo.grep({ pattern, ... })	Server-side code search within this repo
repo.glob({ patterns[], ... })	Find files matching glob patterns
repo.listDir(opts?)	List directory contents (optionally recursive)
repo.listBranches(opts?)	List branches with latest commit info
repo.listCommits(opts?)	List commits with filtering by path, date range

Read files

// Full file
const file = await repo.readFile("src/index.ts");
// file.content, file.totalLines

// Specific line ranges (1-indexed, inclusive)
const snippet = await repo.readFile("src/index.ts", {
  ref: "main",
  lines: [{ start: 10, end: 25 }, { start: 100, end: 110 }],
});

Batch read

const files = await repo.getFileContents([
  "package.json",
  "tsconfig.json",
  "src/index.ts",
]);
// Returns (FileContentEntry | null)[] -- null for files that don't exist

Grep (single repo)

const result = await repo.grep({
  pattern: "createServer",
  language: "TypeScript",
  caseSensitive: true,
  maxMatches: 20,
});

for (const match of result.matches) {
  console.log(`${match.path}:${match.lineNumber}  ${match.lineContent}`);
  // match.submatches[] has character offsets within the line
}

Grep all (cross-repo)

const result = await gm.grepAll({
  pattern: "fastApply",
  language: "TypeScript",
  sortByStars: true,
  limit: 10,
});

for (const match of result.matches) {
  console.log(`${match.repoName}  ${match.filename}`);
  for (const line of match.lines) {
    console.log(`  L${line.num}: ${line.content}`);
  }
}

Glob

const result = await repo.glob({
  patterns: ["src/**/*.ts", "!**/*.test.ts", "!**/*.spec.ts"],
  prefix: "src/",
  limit: 500,
});

for (const entry of result.entries) {
  console.log(`${entry.path}  ${entry.size} bytes`);
}

List directory

// Top-level
const root = await repo.listDir();

// Subdirectory, recursive
const src = await repo.listDir({ path: "src", recursive: true, ref: "develop" });

for (const entry of src.entries) {
  console.log(`${entry.type === "dir" ? "d" : "f"}  ${entry.path}`);
}

Branches

const branches = await repo.listBranches({ limit: 50 });
for (const b of branches) {
  console.log(`${b.name}  ${b.commit.id.slice(0, 8)}  ${b.commit.message}`);
}

Commits

const commits = await repo.listCommits({
  sha: "main",
  path: "src/",
  since: "2025-01-01T00:00:00Z",
  limit: 20,
});

for (const c of commits) {
  console.log(`${c.sha.slice(0, 8)}  ${c.author.name}  ${c.message}`);
}

Mirror

// Shorthand (defaults to GitHub)
const { repository, repo } = await gm.mirror("facebook/react");

// Full URL with options
const { repository } = await gm.mirror("https://gitlab.com/org/repo", {
  private: true,
  issues: true,
  pullRequests: true,
  releases: true,
});

// repo is a GitMorphRepo handle, ready to use immediately
const files = await repo.glob({ patterns: ["**/*.ts"] });

Error handling

All errors extend GitMorphError:

import {
  GitMorphError,
  ApiError,
  AuthenticationError,
  GrepError,
  MirrorError,
} from "@morphllm/gitmorph-sdk";

try {
  await repo.readFile("missing.txt");
} catch (err) {
  if (err instanceof ApiError) {
    console.log(err.status, err.url); // 404, https://gitmorph.com/api/v1/...
  }
}

Error class	When
AuthenticationError	No token found in options, env, or config file
ApiError	HTTP error from the API (has .status and .url)
GrepError	Invalid grep pattern or search failure
MirrorError	Mirror/migrate operation failed

License

MIT