The Git API provides read-only access to the project’s git repository. Use it to check the working tree status, browse commit history, list branches, and view file diffs.

Capability required: git:read

Frontend (iframe)

import { createResourceClient } from "@rightplace/sdk";

const rp = createResourceClient();
await rp.ready();

// Get current git status
const status = await rp.git.status();
// -> { initialized: true, branch: "main", changedFiles: 3, ahead: 1, ... }

// Get recent commits
const commits = await rp.git.log(20);
// -> [{ hash: "abc123", message: "Fix bug", author: "Jane", timestamp: 1713000000, ... }]

// List branches
const branches = await rp.git.branches();
// -> [{ name: "main", isCurrent: true }, { name: "feature/new-ui", isCurrent: false }]

// Get diff for a specific file
const diff = await rp.git.diff("src/index.ts");
// -> unified diff string

Backend (Node.js)

import { createResourceServer } from "@rightplace/sdk/server";

const server = createResourceServer({
  methods: {
    getRepoSummary: async (_params, { rp }) => {
      const status = await rp.git.status();
      const branches = await rp.git.branches();
      return {
        branch: status.branch,
        changedFiles: status.changedFiles,
        branchCount: branches.length,
        hasRemote: status.hasRemote,
      };
    },
  },
});

server.start();

MCP

A much broader set of git operations is available to agents than to iframe resources - agents can stage, commit, branch, and checkout.

Tool	Purpose	Permission
rightplace_git_status	Working-tree status + branch + ahead/behind	git:read
rightplace_git_diff	Unified diff	git:read
rightplace_git_log	Commit history	git:read
rightplace_git_branches	List branches	git:read
rightplace_git_file_content	A file’s content at a ref	git:read
rightplace_git_file_at_ref	A file at an arbitrary ref	git:read
rightplace_git_stage	git add files	git:write
rightplace_git_commit	git commit	git:write
rightplace_git_create_branch	git branch <name>	git:write
rightplace_git_checkout	git checkout <ref>	git:write

Every tool takes the owning projectId (or resourceId of a git resource).

RobinPath Bridge

# Status + log
rightplace.git_status {projectId: "proj_abc"} into $status
log "branch:" $status.branch $status.changedFiles "files changed"

rightplace.git_log {projectId: "proj_abc", limit: 10} into $commits
for $c in $commits
  log $c.shortHash $c.message
endfor

# Stage + commit
rightplace.git_stage {projectId: "proj_abc", paths: ["README.md", "src/index.ts"]}
rightplace.git_commit {projectId: "proj_abc", message: "docs: refresh README"} into $commit
log "committed:" $commit.hash

# Branch + checkout
rightplace.git_create_branch {projectId: "proj_abc", name: "feature/script-demo"}
rightplace.git_checkout {projectId: "proj_abc", ref: "feature/script-demo"}

API Reference

rp.git.status()

Returns the current git working tree status.

Parameter	Type	Description
Returns	Promise<GitStatus>	Repository status

rp.git.log(limit?)

Returns recent commits from the current branch.

Parameter	Type	Description
limit	number	Max commits to return (default: 50)
Returns	Promise<GitCommitEntry[]>	Commit list

rp.git.branches()

Returns all local branches.

Parameter	Type	Description
Returns	Promise<GitBranchEntry[]>	Branch list

rp.git.diff(filePath)

Returns a unified diff for a specific file.

Parameter	Type	Description
filePath	string	Path relative to project root
Returns	Promise<string>	Unified diff

GitStatus

Field	Type	Description
initialized	boolean	Whether git is initialized
hasRemote	boolean	Whether a remote is configured
remoteUrl	string | null	Remote origin URL
branch	string | null	Current branch name
changedFiles	number	Number of changed files
untrackedFiles	number	Number of untracked files
commitCount	number	Total commits on current branch
ahead	number	Commits ahead of remote
behind	number	Commits behind remote
changedFilePaths	GitFileEntry[]	Changed file details

GitCommitEntry

Field	Type	Description
hash	string	Full commit hash
shortHash	string	Abbreviated hash
message	string	Commit message
author	string	Author name
timestamp	number	Unix timestamp
parentHashes	string[]	Parent commit hashes

GitBranchEntry

Field	Type	Description
name	string	Branch name
isCurrent	boolean	Whether this is the active branch

GitFileEntry

Field	Type	Description
path	string	File path
status	string	Status (e.g. “modified”, “added”, “deleted”)
staged	boolean	Whether the change is staged

Manifest Configuration

{
  "capabilities": [
    "git:read"
  ]
}

Notes

• This API is read-only. Resources cannot commit, push, pull, or modify the git repository.
• The project must have a folder path set and contain a .git directory.
• Diff output uses standard unified diff format.