Introduction

// Initialize the SDK
const mesa = new Mesa({ org: 'acme' });

// Create a repository - an isolated folder
// with its own version history and access controls
const repo = await mesa.repos.create({ name: 'my-workspace' });

// Open the repository locally as a virtual filesystem
const fs = await mesa.fs.mount({
  repos: [{ name: 'my-workspace', bookmark: 'main' }],
  mode: 'rw',
});
const bash = fs.bash({ cwd: '/acme/my-workspace' });

// Run an agent within the repository. All changes get persisted automatically.
await generateText({
  model: 'gpt-5.3-codex',
  prompt: 'Write a README for the repository',
  tools: {
    bash: tool({
      execute: ({ command }) => bash.exec(command),
      // ... other tool configuration ...
    }),
  }
});

const file = await mesa.content.get({
  repo: 'my-workspace',
  path: 'README.md',
});

const featureBookmark = await mesa.bookmarks
  .list({ repo: 'my-workspace' })
  .find((bookmark) => bookmark.name === 'my-feature')!;

const change = await mesa.changes.create({
  repo: 'my-workspace',
  base_change_id: featureBookmark.change_id,
  message: 'Update README',
  author: { name: 'My AI Agent', email: 'agent@acme.dev' },
  files: [
    {
      path: 'README.md',
      action: 'upsert',
      content: Buffer.from('...').toString('base64'),
      encoding: 'base64',
    },
  ],
});

await mesa.bookmarks.move({
  repo: 'my-workspace',
  bookmark: 'feature/readme',
  change_id: change.id,
});