New project · first agent

From a repository to your first lease.

Set up a project, connect an agent, take a first lease, and see what happens when a second agent wants the same file.

Start the setup Joining a project?

The path

Do these in order.

Steps 1 to 4 connect your repository. Steps 5 to 8 show what SyncStaff does once agents start working.

Install

Open your repository

SyncStaff runs through npx, so there is nothing to install globally. You need Node.js 22.5 or newer.

Check your machine

cd path/to/your/repository
node -v

↳If the version is lower than 22.5, install a current Node.js release and check again.

Configure

Run setup

This creates a project named after the folder and writes the configuration your coding agents need.

Run from the repository folder

npx -y syncstaff-mcp setup --create-project

↳Add --project my-project to choose the name. Setup writes files for Claude Code, Codex, Gemini CLI, Cursor, Muse and other MCP clients. They hold no credentials and can be committed. The credential goes in .syncstaff/, which setup adds to .gitignore.

Connect

Approve, then restart your agent

The terminal prints a link and a six-character code, then waits. Open the link, check the code and the project, and approve. Setup finishes by itself. Then restart your coding agent so it loads SyncStaff.

↳Approval gives the agent a credential for this project only. It never gets your GitHub session.

Check the repository is connected

This folder is now bound to the project. Your agent appears on the Team page after its first call.

↳Repeat setup on each machine or repository folder. If an agent doesn’t appear, see the common fixes in the connect guide.

First declaration

Give the agent a small change

Ask in a normal prompt. Before editing, the agent declares what it plans to change, and SyncStaff answers clear, conflict or escalate.

Ask your agent

Change the greeting in src/app.ts.

↳Use any small change in your own repository. With nothing else running, the answer is clear.

First lease

Watch it reserve the file

The agent then asks for a lease on the file. A lease lasts 15 minutes and renews while the agent keeps running.

↳Claude Code, Codex and Gemini CLI stop file edits that don’t hold a lease. Other tools get the same answer, but nothing blocks the edit.

First conflict

Ask a second agent for the same file

While the first agent holds its lease, open a second session in the same repository and ask it to change the same file.

Ask a second agent

Also change the greeting in src/app.ts.

↳Without a model configured, the declaration can still come back clear. The overlap is then caught when the second agent asks for the lease.

Agent instructions

Read what the agent is told

The refusal names the file, who holds it and what they are doing. The agent can narrow its plan, pick up something else, or wait. A full refusal also becomes a decision that can reach a person.

What the second agent receives

{
  "granted": false,
  "conflicts": [{
    "path": "src/app.ts",
    "held_by_human": "your-github-login",
    "vendor": "claude_code",
    "intent_summary": "Change the greeting",
    "expires_at": "2026-10-30T22:09:47Z"
  }],
  "partial_grant_available": false,
  "human_decision_required": true,
  "suggested_action": "wait"
}

↳Shortened from a real refusal. Your agent reads this for you, so you don’t need to act on it unless a decision reaches you.