Documentation

The lay of the land

Where everything lives, and how to move around it.

• Layout & navigation The four regions of the Brisal window — header, sidebar, pane, breadcrumb — and how to move between workspaces, projects, and sessions.
• Explorer A session's collapsible side panel — its working-tree diff, file browser, and session-level actions (annotated messages, commit, push). Session-scoped: each session remembers its own Explorer state. Its side (left or right) is a per-workspace appearance preference.
• Workspaces The top-level container that walls off one context — its projects, providers, agents, skills, and theme — from another. Most people make one; the feature exists for those who need the separation.
• Projects A project is the container inside a workspace where the actual work happens — it holds your sessions and its own agents and skills. Trust is the gate that keeps a project's own skills and hooks inert until you approve them.

Set up a chat

The three pieces that turn an LLM into an agent you can talk to — set up in this order.

• 1 Providers The LLM service Brisal talks to — like Mistral — configured with the endpoint, limits, and key needed to reach it. Brisal ships built-in providers you connect into a workspace and then own.
• 2 Models The specific LLM a request actually runs — like Mistral Medium 3.5 — belonging to a provider and carrying its own context limits, capabilities, and cost. Brisal ships built-in models you add to a provider and then own.
• 3 Agents The assistant you actually chat with — a chosen model wrapped in a system prompt and behavior settings so it acts a certain way. Brisal ships a built-in agent you clone into a workspace and then own.

Doing the work

The chat loop itself, the branches its changes live on, and the skills an agent can draw on.

• Sessions A session is one conversation with an agent, scoped to a project — the chat-and-work loop where you send messages, the agent streams back replies and runs tools, and everything is kept as a transcript you can leave and return to. It's the place all the other pieces (provider, model, agent, skills) finally meet real work.
• Annotations A line-by-line review you attach to a message the agent sent — tag each line as Question, Edit, Note, or Remove, add a preamble and conclusion, then send it as your next turn. Saved as a draft while you write, so you can close it and come back.
• Worktrees A worktree is an isolated git checkout — one branch, its own files — that a session binds to. The Worktrees tab lets you create, switch, diff, merge, rebase, delete them, and resolve conflicts.
• Skills A skill is a packaged, reusable instruction set an agent can draw on — a Markdown file (SKILL.md) with a little frontmatter, discovered from one of four tiers (builtin, external, workspace, project). The agent can pull one in on its own, or you can invoke it by name with /skill.

Control & safety

Guardrails, configuration, and making Brisal your own.

• Trust Deny-by-default gate on a project's own skills and hooks. Trust is an exposure gate, not a sandbox.
• Settings Configure Brisal via two tiers: machine-wide system defaults and per-workspace overrides. Appearance and shortcuts merge; providers, models, and agents are copied from a read-only catalog. You edit in workspaces, not the system tier.
• Appearance & Theming How Brisal looks is set along three axes — mode (light/dark), font size, and palette (the color identity). Appearance is per-workspace, resolved over a system-wide default. Palettes are data: a palette is a token-only CSS file you drop into a workspace's themes folder, and it appears in the picker.

More

• Installation How to get Brisal onto your machine and updated — today the path is a local build from source (there's no prebuilt download channel yet), the prerequisites you need, and the first-run and update friction to expect on macOS, Windows, and Linux.
• External skills The one skill tier that reaches outside a single workspace — your personal ~/.agents/skills folder, shared across every workspace on your machine and other tools. Opt-in: off until enabled via first-launch prompt or Settings › Skills.
• In-app help The assistant can answer questions about Brisal itself — "how do I … in Brisal?" — by reading this same documentation. It's powered by brisal-docs, a Builtin skill that ships with the app and is always on.
• Cloning a repository over SSH Create Remote projects from private SSH repos: accepted URL forms, agent requirement, auth failure fix, host key re-pinning.
• Delegation An agent hands scoped work to subagents that run in parallel, then reasons over their results; you watch and control the tree.

Reference

Field tables and shortcuts for hand-tuning — look them up when you need them.