Brisal 🌬️

Agent work you can inspect, annotate, and keep.

Brisal is an early desktop client for coding agents. It keeps sessions visible, saves the full transcript, and lets you respond to specific lines instead of re-explaining the whole task.

Visit the website

Built with Tauri + SvelteKit + Rust. Inspired by T3 and Sidecar.

Overview

Brisal is an inspectable desktop client for coding agents: sessions stay visible, tool calls and full transcripts are kept, and work is organized by workspace instead of piling up as loose chats.

The core workflow is: workspace → provider → model → agent → project → session — create a workspace, connect an LLM provider, add a model, clone an agent, create a project, and start chatting.

Under the hood, a Tauri desktop shell wraps a SvelteKit frontend over pure-Rust domain crates that hold all the business logic (see Architecture).

⚠️ Active development. Brisal is under heavy, active development. Interfaces, data formats, and behavior may change without notice, and breaking changes are expected in upcoming releases. No backwards-compatibility guarantees are made at this stage.

A French breeze 🇫🇷. Brisal and its agents are named after French winds — brise, Mistral, Tramontane. The theme is a wink, nothing more: Brisal is an independent project, not affiliated with, endorsed by, or connected to Mistral AI.

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│  Applications                                                       │
│  ├─ Tauri (src-tauri/)      │  Future: Server (server/)             │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Domain Crates (crates/) - Pure Rust, zero framework deps           │
│  persistence  workspaces  projects  sessions  messages  models      │
│  providers    agents      skills    tools     hooks     config      │
│  git          worktrees   agent_loop           test-support         │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Interface Layer (src-tauri/src/domains/)                           │
│  Adapts domain crates to Tauri commands                             │
└─────────────────────────────────────────────────────────────────────┘

Data flow: Tauri command → interface layer → domain crate → persistence

Setup

Prerequisites

1. Clone with submodules (plans + roadmap live in brisal-process):

   git clone --recurse-submodules git@codeberg.org:arkanoryn/brisal.git
   

   Or, if you forgot:

   git submodule update --init
   

2. Install dependencies:

   yarn install
   

   This also wires up the project's git hooks (core.hooksPath → scripts/git-hooks/)

Development

Running the application

For development with NVIDIA + Wayland:

__NV_DISABLE_EXPLICIT_SYNC=1 GDK_BACKEND=wayland yarn tauri dev

For all other environment:

yarn tauri dev

Enabling E2E testing feature

For development with E2E testing support:

cargo tauri dev --features e2e-testing

Verifying builds

cargo check --workspace
cargo test --workspace

Production build

yarn tauri build

Build locally

Build a local desktop bundle from a repo checkout:

scripts/build-local.sh

Debug bundle:

scripts/build-local.sh --debug

What the script does:

• checks required tools (cargo, rustc, node, yarn)
• installs JavaScript dependencies with yarn install --frozen-lockfile
• runs yarn run check
• runs cargo check --workspace
• builds the Tauri bundle with yarn tauri build

Artifacts land under src-tauri/target/{release|debug}/bundle/.

Platform notes:

• Linux bundling may require extra system packages from the Tauri prerequisites guide: https://tauri.app/start/prerequisites/

First-run friction (unsigned builds)

Brisal ships no code-signing certificates. Apps you build yourself run without warnings — the OS only distrusts binaries it received from elsewhere (macOS applies its quarantine flag at download time, not at build time). The notes below apply to prebuilt bundles you downloaded.

• macOS — Gatekeeper blocks downloaded unsigned/unnotarized apps. Right-click > Open no longer bypasses this (Apple removed it in macOS 15 Sequoia). Clear the quarantine flag once:

  xattr -dr com.apple.quarantine /Applications/Brisal.app
  

  Or open System Settings → Privacy & Security, scroll to Security, and click Open Anyway for the last blocked app.

• Windows — SmartScreen shows an "unrecognized app" prompt. Click More info → Run anyway.

• Auto-updates — none are configured. The only update path is re-pull + rebuild (git pull --recurse-submodules, then rebuild).

Signing (optional)

To remove the warnings above you would need real certificates:

• macOS — zero-friction requires a Developer ID certificate + notarization via the Apple Developer Program (~$99/yr). There is no free tier; self-signed certificates do not satisfy Gatekeeper.
• Windows — SignPath Foundation issues free certificates to open-source projects. Otherwise Azure Artifact Signing (~$10/mo, individuals in the US/Canada eligible) is trusted by SmartScreen. Self-signed certificates do not clear SmartScreen (it is reputation-based).

Git hooks

Two version-controlled hooks live in scripts/git-hooks/ and are installed automatically by yarn install:

• pre-commit — yarn check (fast type gate on every commit — no e2e)
• pre-push — yarn check + the full yarn test:e2e:browser suite (the regression net, run once at the merge/push boundary)

Bypass in a genuine emergency with git push --no-verify or BRISAL_SKIP_E2E=1.

See AGENTS.md for the full testing workflow.

Testing

E2E Testing with Playwright

Brisal uses Playwright for end-to-end testing with three available modes:

Mode	Platform	Use Case
browser-only	All	Fast, headless Chromium with mocked Tauri IPC (CI-friendly)
tauri	All	Socket bridge to real Tauri webview (true E2E)
cdp	Windows	Direct CDP to WebView2 (full native Playwright)

Requirements:

• All new features must have corresponding Playwright tests
• Tests must pass in the browser-only project before merging

Running tests

List available spec directories:

yarn test:e2e:browser:list

Run specific tests (recommended during development):

npx playwright test --project=browser-only e2e/tests/<dir>

Run multiple test directories:

npx playwright test --project=browser-only e2e/tests/agents e2e/tests/models

Run full browser-only suite (merge/push gate only):

yarn test:e2e:browser

Visible headed testing (requires xorg-server-xvfb on Wayland):

yarn test:e2e:headed:xvfb

Documentation

Brisal's docs split by audience and purpose.

Audience	Where	What
Domain glossary	CONTEXT.md + CONTEXT-MAP.md	Ubiquitous language for the product and each code area. Start with the map, then read the local CONTEXT.md files it points to.
Public docs	brisal.dev · docs/content/	User-facing documentation. Rendered by the Astro site (website/) and shipped as the in-app brisal-docs skill.
Decisions	.agents/DECISIONS.md	ADR index linking to one file per architectural decision in .agents/decisions/.
Project conventions	AGENTS.md	Coding guidelines, testing workflow, and public-docs authoring rules.

Public docs & website

The user-facing docs live in docs/content/ and are dual-audience: they render as the public website (website/, built with Astro) and ship as an in-app LLM skill. Because there is no build-time transclusion, the raw Markdown must read cleanly on its own. Keep docs/content/ up to date — see the authoring rules in AGENTS.md § Public documentation.

The website is a Yarn workspace (@brisal/website). Run it from the repo root:

# Development server (hot reload)
yarn workspace @brisal/website dev

# Production build + local preview
yarn workspace @brisal/website build
yarn workspace @brisal/website preview

Project Structure

brisal/
├── .agents/                     # Project configuration and documentation
│   ├── AGENTS.md                # Primary project documentation
│   ├── DECISIONS.md             # Architectural Decision Records index
│   ├── decisions/               # Individual ADR files (NNNN-slug.md)
│   ├── docs/                    # Architecture and technical documentation
│   ├── instructions/            # Technical standards and guidelines
│   ├── feedbacks/               # Session learnings and retrospectives
│   └── process/                 # Git submodule: brisal-process (plans/roadmap)
├── crates/                      # Domain crates (pure Rust, zero framework deps)
│   ├── persistence/             # File system operations and helpers
│   ├── workspaces/              # Workspace CRUD and config resolution
│   ├── projects/                # Project CRUD and source handling
│   ├── sessions/                # Chat session lifecycle
│   ├── messages/                # Chat messages
│   ├── models/                  # Model management (system/workspace/clone)
│   ├── providers/               # LLM provider management
│   ├── agents/                  # Agent definitions and cloning
│   ├── agent_loop/              # Agent execution loop
│   ├── skills/                  # Agent skills
│   ├── tools/                   # Tool definitions and execution
│   ├── hooks/                   # Lifecycle hooks
│   ├── config/                  # Config override/resolution
│   ├── git/                     # Git operations
│   ├── worktrees/               # Git worktree management
│   └── test-support/            # Shared test helpers
├── src-tauri/                   # Tauri application
│   └── src/
│       ├── commands/            # Tauri command handlers
│       ├── domains/             # Interface adapters to domain crates
│       └── lib.rs               # Entry point
├── src/                         # SvelteKit frontend (routes, components, services, stores)
├── docs/content/                # User-facing docs (public site + in-app LLM skill)
├── website/                     # Astro site rendering docs/content/
├── scripts/git-hooks/           # Version-controlled git hooks
└── e2e/                         # Playwright E2E tests
    └── tests/                   # Test specifications

Debugging

Context	Method
Frontend	console.log() + browser dev tools (port 1420)
Backend	tracing macros: debug!, info!, warn!, error!
Verbose	RUST_LOG=debug yarn tauri dev
Log files	Dev builds: <repo>/logs/dev/. Production builds: the OS application log directory (e.g. macOS ~/Library/Logs/dev.brisal.desktop/).

Key Principles

Principle	Details
FP > OOP	Functional patterns in Rust; see instructions/rust.md
No inline comments	Production code uses self-documenting patterns; /// Rustdoc only; see ADR-007
Errors in services	Error handling lives in services layer, not UI; see error-handling.md
Test coverage	≥80% for critical paths; use tempfile for filesystem isolation
tracing > println!	Backend logging via tracing macros; never println!(); see ADR-008

Versioning

Run version bumps from the repo root:

yarn version --new-version 0.2.0 --no-git-tag-version

The version lifecycle runs scripts/bump-version.sh and updates package.json, website/package.json, src-tauri/tauri.conf.json, and src-tauri/Cargo.toml. The website footer reads website/package.json, so it updates with the same bump.

Contributing

1. Read AGENTS.md for comprehensive coding guidelines
2. Check existing plans in .agents/process/plans/ (submodule)
3. Review architectural decisions in DECISIONS.md
4. Follow the testing requirements outlined above
5. Ensure all tests pass before submitting changes

License

To be determined.