> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Project setup

> Create and manage BRICKS projects

A project is a directory on your machine that contains an `application.json` file. [BRICKS](https://bricks.tools) CTOR runs in a single window and displays all open projects in the sidebar.

## Open a project

1. Click the **Open Project** button in the sidebar
2. Select a directory that contains a BRICKS project (or a parent directory — the app scans up to 3 levels deep)
3. Discovered projects appear as nodes in the sidebar

<Info>
  If the selected directory does not contain any `application.json` file, the app shows an error message. Dismiss it and try a different directory.
</Info>

## Create a new project

You have two ways to create a project:

* **Ask the main chat agent (recommended).** Describe what you want to build in the [main chat](/ctor/guide/main-chat) and the agent runs `bricks app ctor-init` for you. When it finishes, a **Created projects** card appears at the bottom of the chat — click **Start session** to open a project-scoped chat with the new project already selected. Any context from the main chat is handed over via `CONTEXT.md` so the project agent picks up where you left off.
* **Use the New Project dialog (manual).** Click **New Project** in the sidebar to scaffold a project from a form, without going through the agent.

The rest of this section walks through the manual flow.

### New Project dialog

The **New Project** dialog has two tabs: **From Existing** and **Create New**.

If you have multiple authenticated [profiles](/ctor/guide/authentication#multi-profile-support), a **Profile** dropdown appears at the top of the dialog so you can browse and create apps under any workspace.

### From an existing app

Use the **From Existing** tab to create a local project from an app that already exists on [BRICKS Controller](/controller).

<Steps>
  <Step title="Open the new project dialog">
    Click **New Project** in the sidebar.
  </Step>

  <Step title="Select an app">
    The dialog lists apps from the selected profile's workspace. Use the search field to filter by name or description.
  </Step>

  <Step title="Choose a directory">
    Select an app, click **Create Project**, and pick a directory on your machine. The app initializes the project in that directory.
  </Step>
</Steps>

### Create a new app

Use the **Create New** tab to create a new app on the server and initialize a local project in one step.

<Steps>
  <Step title="Open the new project dialog">
    Click **New Project** in the sidebar, then select the **Create New** tab.
  </Step>

  <Step title="Enter app details">
    * **App Name** (required) — the name for your new app
    * **Description** (optional) — a short description of what the app does
  </Step>

  <Step title="Create the app and project">
    Click **Create App & Project**, then pick a directory. This creates the app on the BRICKS server and initializes a local project. A new session opens automatically.
  </Step>
</Steps>

## Managing projects

Each open project appears as an expandable node in the sidebar. Click a project to expand it and view its sessions. Sessions are scoped per project — selecting a project shows only its chat sessions.

### Remove a project

To remove a project from the sidebar:

1. Hover over the project and click the **X** button
2. Click the confirmation button that appears (or wait 3 seconds for it to reset)

Removing a project only removes it from the sidebar. Your project files on disk are not deleted.

### Recent projects

Previously opened projects appear in the recent projects list for quick access. The app also restores all open projects when you restart it.

## Project context files

Place a `CLAUDE.md` or `AGENTS.md` file in your project root to provide custom instructions to the AI agent. These files are automatically included in the agent's system prompt for every session in that project.

This is useful for:

* Defining project-specific coding conventions
* Describing your project architecture
* Adding custom rules the agent should follow

The app also reads `application.json` from the project root to include app metadata in the agent's context.

## Next steps

<CardGroup cols={2}>
  <Card title="Start using the AI agent" icon="robot" href="/ctor/guide/agent-usage">
    Chat with the AI agent to build your application.
  </Card>

  <Card title="bricks-ctor SDK" icon="cube" href="/ctor-pkg">
    Learn about the TypeScript SDK that powers your bricks-ctor applications.
  </Card>
</CardGroup>