Onboarding

Prerequisites

Sign up for a Relace account.
Create an API key.
Install the Relace TypeScript SDK: npm install @relace-ai/relace

Transfer Existing Source to Relace

Start by transferring your existing repositories to Relace.

import { Relace } from '@relace-ai/relace';

const client = new Relace({ apiKey: 'YOUR_API_KEY' });

const repo = await client.repo.create({
  source: {
    type: 'git',
    url: 'https://github.com/relace-ai/vite-template',
    branch: 'main',
  },
  metadata: {}, // Optional: add any custom properties
});

console.log(`Repository created with ID: ${repo.repo_id}`);

import { Relace } from '@relace-ai/relace';

const client = new Relace({ apiKey: 'YOUR_API_KEY' });

const repo = await client.repo.create({
  source: {
    type: 'files',
    files: [
      {
        filename: 'src/main.py',
        content:
          "def main():\n    print('Hello from my existing project!')\n\nif __name__ == '__main__':\n    main()",
      },
      // Add more files as needed
    ],
  },
  metadata: {}, // Optional: add any custom properties
});

console.log(`Repository created with ID: ${repo.repo_id}`);

Keep track of the Relace repo_id in your database for future reference. You can optionally include a metadata parameter to add any properties of repos you want to maintain.If you have a lot of repos to transfer, you’ll have to perform this step in batches. See the policies section for information on rate limits.

Create New Relace Repos

For creating new repositories, we recommend using Relace Templates to minimize repo creation latency. However, you can also use the same functions above.

import { Relace } from '@relace-ai/relace';

const client = new Relace({ apiKey: 'YOUR_API_KEY' });

const repo = await client.repo.create({
  source: {
    type: 'relace',
    repo_id: 'your-template-repo-id',
  },
  metadata: {}, // Optional: add any custom properties
});

console.log(`Repository created with ID: ${repo.repo_id}`);

import { Relace } from '@relace-ai/relace';

const client = new Relace({ apiKey: 'YOUR_API_KEY' });

const repo = await client.repo.create({
  source: {
    type: 'git',
    url: 'https://github.com/username/new-repository',
    branch: 'main',
  },
  metadata: {}, // Optional: add any custom properties
});

console.log(`Repository created with ID: ${repo.repo_id}`);

import { Relace } from '@relace-ai/relace';

const client = new Relace({ apiKey: 'YOUR_API_KEY' });

const repo = await client.repo.create({
  source: {
    type: 'files',
    files: [
      {
        filename: 'src/main.py',
        content:
          "def main():\n    print('Hello from my new project!')\n\nif __name__ == '__main__':\n    main()",
      },
      // Add more files as needed
    ],
  },
  metadata: {}, // Optional: add any custom properties
});

console.log(`Repository created with ID: ${repo.repo_id}`);

Integrate Repos with Your Agent

Now that your repositories live in Relace, you can integrate them with your agent’s local file system. You can fetch the stored files directly from our API without needing to setup git on your host:

import { Relace } from '@relace-ai/relace';

const client = new Relace({ apiKey: 'YOUR_API_KEY' });

const repoFiles = await client.repo.clone(repoId);

// The response contains all files with their content
for (const file of repoFiles.files) {
  console.log(`File: ${file.filename}`);
  console.log(`Content: ${file.content.substring(0, 100)}...`); // First 100 characters
}

After your agent modifies files, push the changes back to Relace. You can either update specific files or overwrite all repository content.

import { Relace } from '@relace-ai/relace';

const client = new Relace({ apiKey: 'YOUR_API_KEY' });

// Apply specific file operations using diff mode
const result = await client.repo.update(repoId, {
  source: {
    type: 'diff',
    operations: [
      {
        type: 'write',
        filename: 'src/main.py',
        content:
          "def main():\n    print('Agent updated this function')\n    return True",
      },
      {
        type: 'rename',
        old_filename: 'src/helpers.ts',
        new_filename: 'src/utils.ts',
      },
      {
        type: 'delete',
        filename: 'old-unused-file.py',
      },
    ],
  },
});

console.log(`Applied diff operations: ${JSON.stringify(result)}`);

import { Relace } from '@relace-ai/relace';

const client = new Relace({ apiKey: 'YOUR_API_KEY' });

// Overwrite all repository content
const result = await client.repo.update(repoId, {
  source: {
    type: 'files',
    files: [
      {
        filename: 'src/main.py',
        content:
          "def main():\n    print('Agent completely rewrote this')\n    return True",
      },
      {
        filename: 'README.md',
        content:
          '# Agent Updated Project\n\nThis project was updated by an AI agent.',
      },
    ],
  },
});

console.log(`Overwrote repository: ${JSON.stringify(result)}`);

The update operation will return a response with the new head of the repo:

{
  repo_id: "8d2e491a-935b-4872-b1fc-d9e84fba3c5d",
  repo_head: "7c5151736f4b4b1e68313201f9f24cb5da738ad3"
}

Use Built-In Agentic Search

Repositories stored in Relace can be searched with our fast agentic search agent, which always runs on the current state of the code. Use the search endpoint as an agent tool to find files based on relevance to a user query.

import { Relace } from '@relace-ai/relace';

const client = new Relace({ apiKey: 'YOUR_API_KEY' });

const results = await client.repo.search(repoId, {
  query: 'Add a user profile component with avatar and edit functionality',
});

for await (const event of results) {
  console.log(event);
}

The response will be a stream of Server-Sent Events with real-time updates as the agent explores the repo. The final report_back event provides an explanation of the findings and the relevant files with line ranges.

{
  "name": "report_back",
  "explanation": "The user profile components live in src/components/UserProfile.tsx, with shared types in src/types/user.ts. ...",
  "files": {
    "src/components/UserProfile.tsx": [[1, 120]],
    "src/types/user.ts": [[1, 40]]
  }
}

For more details, see our search guide.

Getting Started

Model Guides

Repos

Agents

Prerequisites

​Prerequisites

Prerequisites