Projects & repositories

What a project holds, how a repository binds to one, and where settings live.

A project is the workspace for one codebase. It holds that codebase's tasks, runs, workflows, instructions, statuses, priorities, labels, wiki, and settings. An organization can have as many projects as it likes, and every run belongs to exactly one.

Connect a repository

Create a project from the dashboard, the desktop app, the Mac app, or a phone, and give it your repository's address — a repository is not a prerequisite.

A checkout can name its project in peractorrc.json at the root of your repository — the only file Peractor ever reads there:

{ "project": "3f9a…" }

That is the whole binding: run the peractor command line inside the checkout and it talks to that project without being told. An optional host field points the repository at a self-hosted server instead of Peractor Cloud.

One project, one repository

A run works against its project's repository and nothing else. There are no per-task repository overrides to audit.

On Peractor Cloud the repository must be a git remote; a self-hosted server can also point a project at a folder on its own disk.

Projects without a repository

Marketing, sales, ops and HR teams have no repository, and they don't need one. Leave the repository field empty when you create a project and Peractor keeps the project's files: its wiki, Assets, the documents you make in the Office editors, its memory, and what its runs produce once they are merged. Nothing on such a project says "repository", "branch" or "commit" — the wiki and Assets simply Save. The Code view still shows every file with its history, for the people who want it.

Its settings show Files — Kept by Peractor with the room it takes. The organization's projects share the storage its plan includes.

• Move to GitHub or GitLab. When the team grows into engineering, create an empty repository and choose Move to GitHub or GitLab… in the project's settings. Peractor pushes the files, their whole history and the large files there, then works in that repository from then on. A repository that already has its own history is refused rather than overwritten; Delete the files and bind… is there for a project whose files you don't need.
• Unbinding keeps a copy. Clearing a project's repository copies its branches, tags and large files, and Peractor keeps them from then on — the wiki and Assets carry on as they were.
• Cloning it. In Code, Clone… shows the address. An API key with View files in the project is the password (and Edit files to push); a key limited to some of the project's folders can't clone, since a clone can't leave the rest out.

Where settings live

Everything except peractorrc.json is stored on the server and edited in the apps. Nothing to commit, nothing to drift.

Trackers follow the same split: the authorization belongs to the organization, but what each project follows — and the tasks that result — belongs to that project alone. See Connect trackers.

Shared projects

A project can be shared with the organization: every other project may then pick its workflows, instructions, personas, skills, task templates and memory. Sharing is a switch in the project's settings, beside Private, for whoever holds Share projects. A shared project can't be private — nobody else could see what it offers — and it can't stop being shared, or be deleted, while another project picks from it: the refusal names those projects.

Every organization has a default shared project, named after it. It is listed first wherever a project picks, every new project receives its memory, and a pack you install lands there unless you choose another project. What the organization kept for itself before — its shared workflows, instructions, personas, skills, task templates and memory — is in it now, under the same ids, so nothing a project had picked changed. Organization settings choose which shared project is the default.

Sharing works by picking, never overriding. Each project ticks what it wants under Settings → Shared library, grouped by shared project, which takes Manage workflows. A picked workflow runs in the picking project, against its repository, statuses and people, and finds its own instructions in the project it came from. A project that needs a shared workflow to be different duplicates it. MCP servers stay the organization's, because they hold its tokens, and are picked the same way. Whole sets of workflows and instructions can also be installed from the marketplace.

Guidelines

The house rules you would otherwise repeat in every task live in the project's memory, under Settings → Memory, as its Project guidelines entry:

Follow the repository's existing conventions. Keep changes small
and focused. Always add or update tests for the code you touch.

A project with a repository keeps its memory there, in .peractor/memory/, beside the code it describes. What an agent is told is layered, outermost first:

1. The shared projects' memory it receives — the default shared project's unless the project chose otherwise. Additive: a project adds to it and never edits it.
2. This project's memory.
3. The workflow's base prompt.
4. The step's instruction.

Every layer adds: a workflow cannot switch the project's guidelines off. Every run's transcript shows all four layers separately, so you can always see what an agent was actually told — and, under the Organization and Project layers, which memory entries it was sent in full, which it was only told it could open, and which the organization's own entry overrode. What earlier steps of the same run worked out is the separate Run notes layer.

Key, tasks, and wiki

Three project settings are worth knowing about on day one:

• Key — two to five letters, unique in your organization, used to name tasks (WEB-14) and their branches. Seeded from the project name and editable; changing it renames every task's key at once.
• Tasks — on by default. Turning it off stops new tasks being written here; tasks synced from a tracker still appear, so the board never disappears.
• Wiki — off by default. Turning it on names the folders in your repository that hold pages. See The project wiki.

Who can see it

In a new organization every member can see every project. A project can be private: then only the roles and people its Access settings let in can see it — besides the owner and people with Administrator, who see every project — and to everyone else it is missing from every list, search and link. The same settings can give a role or a person more, or less, in this project than they have elsewhere, and a folder or a file in its repository can have settings of its own. See Private projects & access.

Housekeeping

The Project block in Settings → General edits the name, key, and repository; changing a project's settings, or deleting it, takes the Manage project permission, and making a new project takes Create projects (see Roles & permissions). A fresh project needs none of this to be useful — the built-in default workflow and priority scale apply until you define your own.