Documentation

The lay of the land

Where everything lives, and how to move around it.

• Layout & navigationThe four regions of the Brisal window — header, sidebar, pane, breadcrumb — and how to move between workspaces, projects, and sessions.
• ExplorerA 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.
• WorkspacesThe 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.
• ProjectsA 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.

• 1ProvidersThe 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.
• 2ModelsThe 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.
• 3AgentsThe 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.

• SessionsA 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.
• AnnotationsA 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.
• WorktreesA 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.
• SkillsA 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.

• TrustDeny-by-default gate on a project's own skills and hooks. Trust is an exposure gate, not a sandbox.
• SettingsConfigure 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 & ThemingHow 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

• InstallationHow 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.
• Onboarding wizardThe required first-run setup that creates a workspace, connects Mistral, adds its starter model, and clones a default agent — then sends you straight to projects.
• External skillsThe 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 during onboarding or from Settings › Skills.
• In-app helpThe 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 SSHCreate Remote projects from private SSH repos: accepted URL forms, agent requirement, auth failure fix, host key re-pinning.
• DelegationAn agent hands scoped work to subagents that run in parallel, then reasons over their results; you watch and control the tree.
• WorkflowsA workflow is a reusable, project-scoped DAG that turns a substantial job into inspectable nodes, runs independent work in parallel, and keeps every attempt linked to its session.

Reference

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