Settings & Configuration

Lanes is configurable out of the box. The Settings dialog gives you control over appearance, project directories, workflow behavior, labels, quick commands, CLI flags, environment variables, notifications, and permissions, all in one place.

Opening Settings

• Press Cmd+, (the standard macOS shortcut), or
• Click the gear icon in the sidebar.

Settings are organized into a sidebar down the left, in four groups:

• Workspace -- Workspaces, Members, and Projects.
• User -- General, Appearance, Notifications, Workflows, and Permissions.
• Agentic Coding -- Terminal, Harness, Local LLMs, and Gateway. Everything about how a session runs and where its requests go.
• Integrations -- Lanes MCP, GitHub, and Linear.

Per-Project Configuration (.lanes/)

Quick commands, labels, CLI flags, and the base branch are per-project. They live in plain JSON files inside a .lanes/ directory at the root of each repo:

.lanes/
  quick-actions.json   # Quick commands for this repo
  labels.json          # Labels for this repo
  cli-flags.json       # CLI flags + environment prefix variables
  general.json         # Base branch and other project settings

These four are edited in the Project Settings dialog, which has a tab each for General, Quick Actions, CLI Flags, and Labels. Open it from Settings > Workspace > Projects, or right-click a project in the sidebar and choose Project Settings. Editing there writes to the same files. You can also hand-edit them, review changes in PRs, and version them like any other config.

Commit it or gitignore it

You get to choose how .lanes/ is shared:

• Commit it (default). Treat it like .vscode/ or .editorconfig. Your team gets the same quick commands, labels, and CLI flags out of the box, and changes flow through normal code review.
• Gitignore it. Add .lanes/ to your .gitignore if you want personal, per-user config that does not bleed into the repo. Each developer keeps their own setup locally.

Mix and match if you like: commit .lanes/labels.json for a shared taxonomy while gitignoring .lanes/cli-flags.json for personal model preferences.

Migrating from earlier versions

If you upgraded from a pre-v0.37 build, open Settings > Project Settings the first time. It walks you through the new layout, keeps your existing global settings as defaults, and lets you push them down into individual repos at your own pace.

General

User > General. Covers the basics:

Working Folder

Add or remove project directories that appear in the sidebar file browser. Click the add button to pick a folder from your file system. Each directory you add becomes a browsable project in the sidebar.

Default Worktree Strategy

Controls what happens when you start a new session from an issue:

• None -- No worktree is created. The session runs in the project root.
• Create -- Lanes automatically creates a new Git worktree for the issue.
• Select -- Lanes prompts you to choose an existing worktree or create one.

Default Start Mode

Sets the initial mode for new agent sessions:

• Plan -- The agent starts in planning mode, where it outlines an approach before making changes.
• Implement -- The agent starts in implementation mode and begins working immediately.

Auto-Update

Toggle automatic updates on or off. When enabled, Lanes checks for new versions and installs them in the background.

Appearance

User > Appearance controls how Lanes looks across the app and the embedded terminal.

Theme

Choose between Light, Dark, or System. The System option follows your operating system preference and switches automatically.

App Font Size

Scales the size of text across the Lanes interface (sidebar, board, panels, dialogs). Bump it up if you want larger UI text, dial it down to fit more content on screen.

Terminal Font

The font family used inside the embedded session terminal. Pick any monospaced font installed on your system. This is independent of the app font, so you can run a tighter UI font alongside a roomier terminal font (or vice versa).

Terminal Font Size

Sets the font size for the session terminal only. Useful when you want larger code while keeping the surrounding UI compact.

Danger Zone

At the bottom of the Appearance page there is a Reset Preferences action. This wipes your local appearance settings back to defaults. It does not touch project directories, .lanes/ config, or your issues.

Notifications

User > Notifications controls the sounds Lanes plays for workflow events.

Done Sound

When an issue moves into the Done column, Lanes plays a sound. The default is a gong. If that does not fit your environment, the page ships a small library of alternatives:

Chime, Success, Tada, Fanfare, Victory, Level Up, Happy Bells, Long Pop, and Sci-fi.

You can also upload your own audio file. Supported formats: .wav, .mp3, .ogg, .m4a, .aac, .flac.

Volume and Preview

A volume slider sets how loud the sound plays, and a preview button lets you hear the current selection before unleashing it on your standup. Tune both before committing to a custom sound.

You can reach the same controls from Configure > Notifications > Sound.

Workflows

User > Workflows displays the current workflow steps that your issues move through:

Planning -- Implementation -- Review -- Done

The step sequence defines the columns on your board and the lifecycle stages for every issue.

Labels

Project Settings > Labels. Manage the labels you use to categorize issues:

• Create a new label by clicking the add button, giving it a name, and picking a color.
• Edit an existing label by clicking on it to change the name or color.
• Delete a label you no longer need.

Lanes offers 13 colors to choose from, giving you enough variety to create a meaningful color-coding system.

You can also manage labels from the board itself, right-click any issue and use the Add Label option in the context menu. This page is the place for bulk management: renaming, recoloring, and cleaning up old labels.

Labels are per-repository and stored in .lanes/labels.json. Renames cascade atomically across every issue in that project.

Quick Actions

Project Settings > Quick Actions is where you create, edit, and organize your quick commands:

• Create a new command by clicking the add button.
• Set its properties: name, prompt or shell command, type (Claude or Terminal), and category (General or Worktree).
• Edit an existing command by clicking on it.
• Reorder commands by dragging them up or down. The order here determines the menu order and which keyboard shortcut (Cmd+Alt+1-9) maps to each command.
• Delete commands you no longer use.

Quick commands are per-repository and stored in .lanes/quick-actions.json.

CLI Flags

Project Settings > CLI Flags has two sections: environment prefix variables and CLI flags. Together they control the full command that Lanes builds for every session.

These are per-repository and stored in .lanes/cli-flags.json, so a monorepo that needs --dangerously-skip-permissions can have it without forcing the same on a side project.

Environment Prefix Variables

Set environment variables that are injected before the CLI command. When a session starts, Lanes prepends these variables so the resulting command looks like:

CLAUDE_CODE_NO_FLICKER=1 claude --flag1 --flag2

Each entry is a KEY=VALUE pair. Lanes includes one default entry:

• CLAUDE_CODE_NO_FLICKER=1 -- Enables Claude Code's fullscreen rendering mode. This is pre-filled and enabled by default. Toggle it off if you prefer the standard rendering behavior. Fullscreen rendering eliminates terminal flicker, keeps memory usage flat in long conversations, and adds mouse support (click to expand tool output, click URLs, drag to select text). It draws the interface on the terminal's alternate screen buffer, similar to vim or htop, and only renders messages that are currently visible. The difference is most noticeable in the VS Code integrated terminal, tmux, and iTerm2.

You can add your own entries with the add button. A few useful Claude Code environment variables:

• CLAUDE_CODE_DISABLE_MOUSE=1 -- Keeps the flicker-free rendering but disables mouse capture, so your terminal's native text selection works normally. Useful over SSH or inside tmux.
• CLAUDE_CODE_SCROLL_SPEED=3 -- Multiplies the mouse wheel scroll distance (1-20). Helpful when your terminal sends one scroll event per notch.

See the full list in the Claude Code fullscreen docs. Remove or toggle entries as needed.

Environment prefix variables apply to every session in this repository, just like CLI flags. They do not leak across repos.

Note that these are typed into the terminal as a command prefix, so the values land in scrollback and in ps, and .lanes/cli-flags.json lives inside your repo. Do not put credentials here. To route a session at your own model provider, use the Gateway page instead: it stores the credential outside the repo and injects it as real process environment.

CLI Flags

Add persistent flags that are appended after the CLI command. Each flag is a key-value pair in the format flag=value.

For example, if you want every Claude Code session in this repo to run with permissions bypassed, you could add:

--dangerously-skip-permissions

Flags set here apply to every session in the current repository. Use this for settings you always want active in that project, rather than typing them each time.

Lanes captures the active CLI flag set at session launch, so the side panel keeps showing what an issue actually ran with even after you change your selections later.

Agentic Coding

Four pages govern how a session runs. Each of the last three has a reference page of its own:

• Terminal sets which terminal Lanes identifies as to the CLIs running inside its embedded terminal, by way of the reported TERM_PROGRAM. It does not open an external terminal. The default is iTerm, because iTerm, Ghostty, and WezTerm use a silent bell while Apple Terminal answers a bell by pulling the real Terminal.app to the foreground. Applies to sessions started after you change it.
• Harness shows the coding CLIs Lanes drives, whether each one is installed and current, and installs or updates them.
• Local LLMs manages Ollama and the models on this machine.
• Gateway points sessions at a model provider you host or buy instead of the CLI's own.

Permissions

User > Permissions helps you verify that Lanes has the system access it needs:

Folder Access Verification

Confirms that Lanes can read and write to your configured project directories. If a folder is inaccessible (moved, deleted, or permission-restricted), this tab flags the issue.

Per-Project Base Branch

Each project has a base branch used for Git diff comparisons. Lanes auto-detects this from your repository (typically main or master), but you can override it manually if your project uses a different convention (e.g., develop or trunk).

The base branch setting affects:

• What the Git Changes view compares against.
• How worktree branches are diffed.

You can set this from the project settings or it will be picked up automatically the first time you add a project directory. The value is stored in .lanes/general.json. As of v0.37, base-branch detection prefers your local refs over origin, so a local main that is ahead of remote no longer distorts your worktree sync count.

Tips

• Set your theme to System so Lanes follows your OS dark/light preference automatically.
• Add all your active project directories upfront, switching between projects is faster when they are already in the sidebar.
• Commit .lanes/ for shared team setup, or add it to .gitignore if you want per-developer personal config.
• Use the CLI Flags tab sparingly. Both flags and environment variables apply to every session in the repo, so only add ones you truly want there.
• Leave CLAUDE_CODE_NO_FLICKER=1 enabled unless you have a specific reason to disable it. It smooths out terminal rendering for most setups.
• Review the Permissions tab if sessions fail to start or files are unreadable.