# Projects
import Screenshot from "@docs/Screenshot.astro"
import Video from "@docs/Video.astro"
import SurfaceTabs from "@docs/SurfaceTabs.astro"
import AskRen from "@docs/AskRen.astro"
A project groups chats for one kind of work within a [space](/docs/concepts/spaces/). It holds the instructions, repositories, apps, skills, storage, and permissions for its chats. Channels and schedules send requests to it.
Create a project when work needs different instructions or tools. For example, an Engineering space can contain **Plan**, **Build**, **Review**, and **Test** projects. They write specs, write code, review pull requests, and run tests. Each has its own instructions and permissions, and they all share the space's members and machine.
In the API and CLI, a project is `project`.
## Create a project
You need a space and a name. Everything else is optional and can change later.
1. Select **Teams** in the sidebar and open a space.
2. Open the **Projects** tab and select **New project**.
3. Enter a **Name**. You can also pick an icon and add a **Description**, **Instructions**, and repositories.
4. On the **@Ren** step, choose where work can reach the project, like a Slack channel or an email address. You can skip this step.
5. On the **Permissions** step, choose what Ren may do without asking.
6. Select **Create project**.
```sh
ren projects create --pod-id --name "Code review"
```
Ren creates a file store and memory store for each new project. Both use the project's name, like **Code review Files** and **Code review Memory**. See [Storage](/docs/concepts/storage/).
## Project settings
Edit the icon, name, description, and **Default model** on **Overview**. Chats use this model unless you select another. Without a project default, Ren checks the space default, then the organization default, then Ren's default.
To archive a project, select **Project actions** (the **⋯** button), then **Archive project**. You can't archive the **Default** project in your personal space.
## Instructions
Project instructions are standing rules for every chat in the project, like "Always open a pull request instead of pushing to main."
Ren reads instructions from three levels in every chat, from broad to narrow:
1. The organization's instructions, from **Settings → General**.
2. The space's instructions, from the space's **Instructions** tab.
3. The project's instructions.
All three apply. Put company-wide rules in the organization, team or client rules in the space, and rules for this kind of work in the project.
Open the project's **Instructions** tab and edit the text.
```sh
ren projects update --instructions "Run the tests before you open a pull request."
```
## Repositories
Add the repositories Ren should work on. Ren clones each one into the project on the space's machine, so it can read and change the code. A project can have several repositories.
1. Open the project's **Repositories** tab and select **Add repository**.
2. Search for a repository and select it. You can select several.
3. Select **Add repository**.
The list shows GitHub repositories the Ren GitHub app can reach. In your personal space, it shows repositories from your own GitHub account instead. If GitHub isn't connected yet, the dialog asks you to connect it first. See [GitHub](/docs/channels/github/).
To change a repository's URL, branch, or alias, select **Edit** on its row.
You can mention a repository in the composer by its alias, like `@storefront`.
## Apps, skills, custom MCPs, and storage
Attach tools and stores to make them available to every chat in the project.
- **Apps, skills, and custom MCPs:** The project's **Connections** tab groups **Apps**, **Custom MCPs**, and **Skills**, with **Add app**, **Add custom MCP**, and **Add skill** buttons. You can also add items through **Marketplace**. In the chat composer, select **Connect** beside **+** to add or remove items in these groups. After you attach items, their icons replace **Connect**.
- **Storage:** Open the project's **Storage** tab and choose **Memory** or **Files**. Select **Attach memory store** or **Attach file store**. To detach a store, select **Detach** on its row. The store stays in your organization.
```sh
ren projects skills add --skill-id
ren projects mcps add --mcp-id
ren projects file-stores add --file-store-id
ren projects memory-stores add --memory-store-id
```
See [Apps](/docs/concepts/apps/), [Skills](/docs/concepts/skills/), [Custom MCPs](/docs/concepts/custom-mcps/), and [Storage](/docs/concepts/storage/).
## Permissions
Permissions decide which actions Ren takes on its own, which ones it asks you about first, and which ones it never takes. Each action is set to **Allow**, **Ask**, or **Deny**.
1. Open the project's **Permissions** tab.
2. Pick a preset:
- **Safe:** reads files on its own, asks before most other actions, and never touches folders outside the project.
- **Balanced:** reads files and uses the internet on its own, and asks before changes and commands.
- **Autonomous:** does most things on its own, and still asks before using folders outside the project.
3. To fine-tune, set **Allow**, **Ask**, or **Deny** for each action in the list, like **Run commands** or **Access websites**.
4. For rules that match specific commands or paths, select **Advanced**. Add a rule with a permission, a pattern, and a behavior, or edit the rules as JSON.
You can also change the project's permissions from a chat: select **+** in the composer, then **Permissions**.
```sh
ren projects update --body '{"permission": {"bash": "allow", "external_directory": "deny"}}'
```
When an action is set to **Ask** in a chat you're in, Ren shows the request above the composer. Choose **Allow once**, **Always allow**, or **Deny**, or type what Ren should do instead.
Channel and scheduled chats deny actions set to **Ask** and continue without them. Set required actions to **Allow** before the chat starts.
## Channels
The **@Ren** tab maps channels to this project: Slack channels, Linear projects, GitHub repositories, Telegram chats, and the project's email address. Messages from a mapped channel start chats in this project. See [Channels](/docs/channels/).
## Usage
The **Usage** tab shows chat costs. Select **Spend** or **LLM calls**, then choose a period of 7, 30, or 90 days. Open **Per session** for individual chat costs.