Projects
A project is where work actually happens in Brisal. A workspace is the wall around a context; a project is one unit of work inside that wall — a single codebase, task, or effort you open sessions against.
Everything a session needs lives in the project: the sessions themselves and the project’s own agents and skills. A workspace can hold as many projects as you like, and they’re all isolated from the projects in every other workspace.
Project vs workspace
Keeping the two containers straight makes the rest of this page easy:
| Workspace | Project | |
|---|---|---|
| Role | The wall — compartmentalizes one whole context from another | One unit of work inside that wall |
| Holds | Projects, providers, models, agents, skills, theme | Sessions, its own agents & skills |
| How many | Usually one; more only if you need separation | As many as you want per workspace |
| Selection | Exactly one workspace is selected at a time | Exactly one project is selected within the workspace |
Creating a project
Every project has a source — where its files come from. Today you create a project from scratch: an empty project with no code attached, ready for sessions, notes, or planning.
A workspace with no projects yet. Create Project — or + New Project in the top-right — starts the flow.
To create one:
- Open the Projects list inside your selected workspace.
- Press + New Project.
- Choose From Scratch.
- Give it a Name (required) and an optional Description, then press Create Project.
Naming a from-scratch project — only the name is required.
Creating a project also selects it, so you land ready to start your first session.
What lives inside a project
A project is its own small world under the workspace. Each project owns:
| Inside a project | |
|---|---|
| Sessions | The chats you run against this project — see Sessions |
| Agents & skills | Project-scoped agents and skills that only exist here |
Project-scoped skills sit at the most specific end of Brisal’s four skill tiers (builtin → external → workspace → project) and take precedence over the broader ones. They are also the reason trust exists (below): a project’s own skills and hooks are inert until you approve the project.
Selecting a project
The selected project is the one you’re working in — the project whose sessions you see and create. Exactly one project is selected at a time within a workspace, and its card carries a Selected badge.
Press Select on a project’s card to switch to it. Selecting a project deselects whatever was selected before, the same way workspaces work one level up.
A project card: the Selected badge and the Select · Edit · Lock · Archive · Delete action row covered below.
Lifecycle: lock, archive, delete
Alongside Select, each project card carries the actions for managing a project over its life. All of them are real, wired actions today:
| Action | What it does | When it’s unavailable |
|---|---|---|
| Select | Make this the project you’re working in | While the project is locked |
| Edit | Change the project’s name or description | — |
| Lock / Unlock | Freeze a project so it can’t be selected, archived, or deleted by accident. Unlock to act on it again. | Lock is unavailable while a project is archived |
| Archive / Unarchive | Set a project aside to declutter the list without deleting it. Unarchive to bring it back. | Archive is unavailable while a project is locked |
| Delete | Permanently remove the project | While the project is selected or locked |
In short: lock protects a project from lifecycle changes, and archive tidies it out of the way — both are reversible. To delete or re-select a locked project, unlock it first; to delete the selected project, select a different one first.
Project trust
Because a project can ship its own skills and hooks — project-local code Brisal would run automatically, as you, on your machine — a brand-new project is untrusted: that code stays inert until you explicitly trust it. When you open an untrusted project, an amber “Trust not set” banner offers a Manage trust button. Trust gates whether that code loads; it is not a sandbox.
The full story — the banner, the dialog, trust vs. deny vs. reset, and per-worktree decisions — lives on its own page: Trust.
What to read next
A project is the stage; the work itself is a session on it.
- Sessions — the chats you run inside a project, how they persist, and how branches and worktrees fit in (including finer-grained, per-worktree trust).
- Skills and Agents — what project-scoped skills and agents are, and how project scope overrides the workspace and system layers.
- Workspaces — the wall a project lives inside.