# Projects

A **project** is the organizational unit that ties agents, file stores, memory stores, and permissions together into a single deployable context. If a [pod](/docs/deep-dives/concepts/compute/pods/) is the machine where agents run, a project is one _piece of work_ on that machine: the specific set of agents, data, and rules that belong together.

A pull-request reviewer needs a Git repo, a working file store, and a memory of past reviews; a Slack triager needs different stores and a different permission profile. A project collects those bindings (which agents work together, which stores they share, what they're allowed to do) once, so every session inherits the full context. This matters most when a primary agent delegates to subagents that all need the same repo and memory.

## Where a project lives

Every project belongs to exactly one [pod](/docs/deep-dives/concepts/compute/pods/). The pod provides the compute, filesystem, and network; the project defines _what runs inside it_ and _what it has access to_. A pod can hold multiple projects, each with its own agents, stores, and permissions, sharing the same sandbox.

Each project gets its own root directory in the sandbox, which is the working directory agents see when a session starts.

## Agents and their roles

A project assigns each [agent](/docs/deep-dives/concepts/agents/agents/) a role:

- **Primary**: the entry point. A new session goes to the primary agent, which handles the task or delegates to a subagent.
- **Subagent**: a specialist the primary delegates to. Subagents don't receive session messages directly; the primary invokes them when needed.
- **All**: acts as both, for simple projects where one agent does everything.

A project needs at least one primary agent to run. The primary-subagent split is what enables [multi-agent coordination](/docs/deep-dives/concepts/agents/agents/): the primary routes, subagents provide depth.

## Stores: files and memory

A project attaches [file stores](/docs/deep-dives/concepts/stores/file-stores/) for persistent artifacts (code, documents, config) and [memory stores](/docs/deep-dives/concepts/stores/memory-stores/) for long-term recall. A store can be shared across projects, and a project can mount several.

Attaching stores at the project level means every agent in the project sees the same data. A primary agent writes a plan to a file store, and its subagents read it.

## Git repositories

A project can bind a GitHub repository: the repo URL, an optional base branch, and an optional path to clone into. When a session opens, Ren clones the repo into the sandbox, giving agents a real working tree to read, edit, run tests against, and open pull requests from.

## Permissions

Each project has a [permission policy](/docs/deep-dives/concepts/sharing/permissions/) that controls what agents in it are allowed to do: file reads, shell commands, web access, and so on. Because permissions are scoped to the project, the same agent can have read-only access in one project and full write access in another.

## The CLI surface

Projects are managed through the Ren CLI:

```bash
# Create a project inside a pod
ren projects create --pod-id <podId> --name "My Project"

# List projects
ren projects list

# Attach an agent to a project
ren projects agents add <projectId> --agent-id <agentId> --type primary

# Attach a file store
ren projects file-stores add <projectId> --file-store-id <fileStoreId>

# Attach a memory store
ren projects memory-stores add <projectId> --memory-store-id <memoryStoreId>
```

## How it fits together

An org owns pods, pods contain projects, and projects bind agents and stores. Within a project everything is a first-class attachment, not a nested child, so you can reuse the same agent across projects, share a file store between projects in a pod, and reassign agents without rebuilding anything.

The project is where reusable definitions (agents, skills, stores) meet a concrete deployment (a pod, a repo, a permission policy).