---
title: Settings Reference
description: "Every Agentastic settings page, section by section — general, workspaces, agents, tasks, skills, plugins, cloud, mobile app, containers, code review, terminal, appearance, and more."
updated: "2026-11-14"
---

Open Settings with <kbd>Cmd</kbd>+<kbd>,</kbd> or from the menu bar: **Agentastic > Settings**.

The sidebar groups its pages:

| Group | Pages |
|-------|-------|
| (top) | General, Accounts, Sidebar |
| Agents & Automation | Agents, Tasks, Skills, Plugins, Code Review |
| Environments | Workspaces, Containers, Cloud |
| Tools | Terminal, Browser, Computer Use, Mobile App, Repomix |
| Editor & Files | Text Editing, Fonts, Themes, Search, Source Control, Language Servers, Locations |

## General

| Setting | Description | Default |
|---------|-------------|---------|
| Pane Style | **Classic** tiles editor panes edge to edge with thin dividers; **Modern** draws each pane as a rounded card with space around it | Modern |
| Sidebar Style | **Classic** keeps the sidebar flat and flush with the window edge; **Modern** uses the native macOS sidebar, which floats as a rounded card on macOS 26 and later | Modern |
| Show the jump bar | Display breadcrumb navigation in editor | On |
| Dim editors that don't have focus | Dim unfocused panes | Off |
| Navigator Position | Place the navigator sidebar on the Left or Right | Left |
| Keep the Mac awake while agents work | Stop the Mac idling to sleep while an agent is working, on battery too; the display can still sleep, and closing the lid still sleeps the Mac. Keeping it awake for your phone is under **Mobile App** | On |

## Text Editing

| Setting | Description | Default |
|---------|-------------|---------|
| Font | Editor and diff viewer font face | SF Mono |
| Font Size | Editor and diff viewer text size in points | 13 |
| Line Height | Line spacing multiplier | 1.5 |
| Tab Width | Spaces per tab | 4 |
| Insert Spaces | Use spaces instead of tabs | On |
| Word Wrap | Wrap long lines | On |
| Markdown View | Render Markdown as plain text, markdown, or split | Markdown |
| Check spelling in Markdown | Underline misspelled words in Markdown documents. Autocorrect only runs there while this is on | Off |

## Terminal

| Setting | Description | Default |
|---------|-------------|---------|
| Terminal Emulator | Ghostty or SwiftTerm | Ghostty |
| Shell | Default shell | System Default |
| Font | Terminal font face | SF Mono |
| Font Size | Terminal text size | 13 |
| Cursor Style | Block, underline, or bar | Block |
| Cursor Blink | Animate cursor | On |
| Option as Meta | Use Option as Meta key | Off |
| Auto-copy Selected Text | Copy to the clipboard as soon as you select | Off |
| Open Links & Files on Click | Click URLs and file paths in the terminal to open them | On |
| Image Previews | Hover an image path in the terminal for an inline preview | On |
| Enable File Preview | Hover a `file:line` reference for a syntax-highlighted code preview | On |

## Theme

| Setting | Description | Default |
|---------|-------------|---------|
| Editor Theme | Syntax highlighting theme | Default |
| Match System | Follow system dark/light mode | On |
| Enable glass effect | Let the desktop show through the window, sidebars, editor, chat, and terminals. Full screen and **Reduce Transparency** stay opaque | Off |
| Glass amount | How much of the desktop shows through, from 0% (a solid theme tint) to 100% (the desktop blur alone), in steps of 10 | 20% |

## Search

| Setting | Description | Default |
|---------|-------------|---------|
| Ignore Patterns | Files/folders to exclude | node_modules, .git |
| Search Limit | Maximum results | 1000 |

## Keybindings

Customize keyboard shortcuts. Each command can have a custom key combination assigned.

## Locations

| Setting | Description |
|---------|-------------|
| Default Save Location | Where new files are saved |
| Recent Projects | List of recently opened projects |

## Navigation

| Setting | Description | Default |
|---------|-------------|---------|
| Show Hidden Files | Display dotfiles | Off |
| Sort Folders First | Folders before files | On |

## Source Control

| Setting | Description | Default |
|---------|-------------|---------|
| Auto Fetch | Automatically fetch from remote | Off |
| Fetch Interval | Time between auto fetches | 5 min |

## Agents

The catalog of every agent Agentastic can launch — 55 built-in definitions plus
any custom connections you add. Agents are shown as a grid of tiles.

Each tile carries the agent's icon and name, its installed version, its
detection status, and a row of chips:

| Element | Meaning |
|---------|---------|
| Version | The version detected on your machine |
| Update chip | A newer version is available; click it to update in place |
| Chat chip | The agent can run in structured [Chat](/docs/features/chat) as well as a terminal |
| Pin | Pins the agent to the top of the grid and of the Agent Home picker |
| Install | Runs the agent's documented install command, then re-verifies the executable |

Tiles are grouped **Pinned → Installed → Not installed → Disabled**. The
segmented control filters by installation status, the search field filters by
name or command, and the refresh button re-runs detection and re-checks for
newer versions.

| Setting | Description | Default |
|---------|-------------|---------|
| Launch Interface | Whether this agent opens in Terminal or Chat | Chat when the agent supports it, otherwise Terminal |
| Executable Source | Auto-detected path, or one you specify | Auto |
| Show Subscription Usage | Show the agent's remaining subscription quota in the Inspector's [Agents card](/docs/features/ide#inspector) (Claude Code and Codex) | Off |
| Custom Agents | Your own definitions, with any CLI command | - |
| Send Shortcut | Whether <kbd>Return</kbd> or <kbd>⌘ Return</kbd> submits a prompt; every other Return chord opens a new line. Applies to the Agent Home prompt and the chat composer alike | Return |
| Follow-up Behavior | Whether sending while an agent works queues the message or [steers](/docs/features/chat) the current turn. Holding <kbd>⌥</kbd> while sending does the opposite for that one message; agents that cannot steer always queue | Queue |
| Suggested Next Steps | After a Chat turn finishes, show up to three likely [next prompts](/docs/features/chat#suggested-next-steps) above the composer. Clicking one fills in the prompt for you to edit or send. Each set costs the agent one short extra request | On |
| Agentastic Prompt | Prepend Agentastic IDE instructions to the Agent Home prompt | On |

Structured Chat requires an agent Agentastic can drive over a structured
protocol: Agentastic, Claude Code, and Codex through their native integrations,
plus every agent that speaks [Agent Client Protocol](https://agentclientprotocol.com)
— 31 of the 55 catalog definitions today, marked with a **Chat** chip on their tile.
Every other agent runs in a terminal, and you can still convert a running pane
to Chat afterwards. Overriding an agent's command turns Chat off for it, because
Agentastic can no longer tell what it launched. See [Chat](/docs/features/chat)
for the full list and for the transcript, plan, and sub-agent surfaces.

Each worktree can designate one live sidebar session as its **Primary Agent**.
Actions and feedback routed to Primary Agent try that canonical session first;
the designation is managed from the agent's sidebar context menu.

## Sidebar

Control how workspaces appear and how you switch between them.

| Setting | Description | Default |
|---------|-------------|---------|
| Group workspaces by | Repository, server, project, or a flat list | Repository |
| Sort workspaces by | Name, creation date, or recent activity; pinned workspaces stay first | Creation Date |
| Workspace tiles | Compact uses one line; Detailed adds branch, commit, CI, and time | Compact |
| Switch workspaces with | Single or double click | Single Click |
| Order the workspace switcher by | Visits, notifications, or a blend of both | Visited + Notified |

## Workspaces

Where new worktrees are created and how they behave. Container runtime, images, and
mounts live on the [Containers](#containers) page. Layout and navigation live on
the [Sidebar](#sidebar) page. Workspace options are grouped into Location, Branches,
Setup, Cleanup, and Import, with Import at the bottom.

| Setting | Description | Default |
|---------|-------------|---------|
| Create workspaces | Where new worktrees are stored: inside the repository (`.worktree/`), next to it (`-worktrees/`), or in one folder for all repositories | Next to the Repository |
| Files to copy | Repo-root files or folders copied into every new workspace before its setup script runs; per-repo setup belongs in `.agentastic/setup.sh` | None |
| Archive script | Runs before a workspace is archived; absolute, or relative to the workspace root. An `archive` list in the repository's `.agentastic/config.json` takes precedence | None |
| Import from Other Apps… | Opens the review for bringing over repositories, workspaces, skills, MCP servers, and scripts from other coding apps | — |
| Follow new workspaces from *app* | Per source app: picks up that app's new workspaces when repositories refresh | Off |

See [Setup & Teardown Scripts](/docs/guides/setup-teardown-scripts#archive-scripts) for archive scripts and [Import from Other Apps](/docs/how-to/import-from-other-apps) for following.

See [Git Worktrees](/docs/how-to/git-worktrees) for detailed documentation.

## Accounts

Connect the accounts Agentastic uses on your behalf.

- **Agentastic account** — Sign in to (or create) your Agentastic account to share one identity across Agentastic.dev, Agentastic.com, and the Agentastic settings app. A session you're already signed into on your Mac is picked up automatically; you can manage the account on Agentastic.com, and signing out applies across Agentastic products.
- **GitHub** — Pull request panels, status badges, reviews and comments, and CI checks use your GitHub account. Choose how it signs in:
  - **GitHub CLI** (recommended) — Uses the login you made with `gh auth login`. Agentastic asks `gh` for its token whenever it needs one and never stores a copy, so `gh auth login`, `gh auth switch`, and `gh auth logout` apply here too. If you aren't signed in, **Sign In with GitHub CLI…** runs `gh auth login --web` for you: it copies the one-time code and opens GitHub. If `gh` isn't installed, you can install it with Homebrew from the same place. When `gh` is already signed in to github.com and no GitHub account is set up, Agentastic connects through it automatically and says so in the notification inbox; removing the account turns that off.
  - **Personal access token** — Paste a classic token with the `repo`, `read:org`, `workflow`, and `read:user` scopes (**Create Token** opens GitHub with them selected), or a fine-grained token with access to your repositories. It's stored in your Keychain, and the account page shows when it expires. While the GitHub CLI isn't signed in, new agent terminals receive it as `GH_TOKEN` so their `gh` commands work too, unless a terminal already has a GitHub token of its own. Once you sign in to `gh`, new terminals use that login instead.

  GitHub Enterprise works the same way: enter the server address first. You can switch an account between the two methods on its page; a token you saved before is kept for switching back.
- **Plugins** — Connect GitHub for pull requests and private clones, issue trackers such as Linear and Sentry for issue mentions, and Slack for incoming tasks and outgoing updates. Credentials and MCP delivery are managed on the [Plugins](#plugins) page. See [Plugins & MCP](/docs/features/plugins), [Issue Tracking](/docs/features/issue-tracking), and [Slack](/docs/features/slack).

## Tasks

Configure built-in Actions and create reusable agent tasks that appear in every repository and worktree.

| Setting | Description | Default |
|---------|-------------|---------|
| Fast Model | Provider, model, and thinking effort used by Fast actions | Automatic; Haiku for Claude Code, Terra + Medium for Codex |
| Thorough Model | Provider and optional model used by Thorough actions | Automatic |
| Add Task | Create a globally available custom Action | - |
| Model | Per-action override of the selected tier's model | Tier default |
| Prompt | Prompt template; all 15 Actions placeholders are available to every task | Built-in prompt or custom task prompt |
| Run In | Execution destination; automatic result tasks offer Headless or Utility Chat | Primary Agent → Utility Chat for interactive built-ins; Headless for automatic result tasks |

Workspace display naming and inline commit-message generation consume a captured agent response directly. **Headless** uses noninteractive CLI output for local Codex and Claude tasks, including custom definitions. It runs in an isolated temporary directory and uses schema-constrained output for JSON tasks. Other providers and remote or container-backed tasks use hidden structured Chat. Headless tasks preserve the active worktree and session selection; hidden Chat sessions close after a valid result. **Utility Chat** explicitly uses, reveals, and retains the Chat interface. **Primary Agent** continues the canonical live agent in the exact target worktree and tries a user-designated Primary Agent first. If that designation is stale, Agentastic can use another eligible live agent in the same worktree. If none is available, it starts a Utility Chat instead; it never redirects the Action to a bare shell, another worktree, or another workspace. The existing session keeps its provider and model; model overrides apply to automatic captured tasks, newly created agent sessions, and the Utility Chat fallback.

Interactive Actions support connected remote worktrees on all five surfaces. The selected provider's command must be installed on the remote host, and a target worktree must be active before an Action can use its Utility Terminal. Repository shell tasks remain local-workspace only; remote workspace settings do not load them from `.agentastic/settings.json`.

Custom Actions can be edited, duplicated, or deleted from their row menu. They are stored globally rather than in a repository's workspace settings. See [Actions](/docs/features/actions) for the built-in catalog, custom task workflow, and complete placeholder reference.

## Skills

Install a skill once and Agentastic delivers it to whichever agent you launch, translated into
that agent's own convention.

| Control | What it does |
|---------|--------------|
| Skill Marketplace | Browse and install skills from the [Skillopedia](https://www.skillopedia.ai) catalog |
| Install from GitHub | Install a skill from any repository |
| Installed Skills | Update to Latest, Open in Editor, or Remove an installed skill |

See [Skills](/docs/features/skills).

## Plugins

Connect a tool once — every agent you launch gets it automatically, as an MCP server where the
agent supports one, and as skills, instructions, or attachments where it doesn't.

| Control | What it does |
|---------|--------------|
| Installed / Suggested | The connected plugins, and the built-in catalog you haven't connected yet |
| Connect | Opens the plugin's detail pane, where you enter credentials (stored in the macOS Keychain) and see exactly what its MCP server runs |
| Add MCP Server… | Add a personal MCP server — stdio command or HTTP endpoint — available to every workspace |
| Install Plugin from Folder… | Load a plugin from a local `plugin.json` manifest |
| Uninstall | Removes the plugin and its stored credentials from this Mac |

See [Plugins & MCP](/docs/features/plugins).

## Cloud

Run agents on cloud VMs you provision yourself.

| Setting | Description | Default |
|---------|-------------|---------|
| Add Provider... | Connect a cloud backend and its credentials | - |
| Default Provider | Used when launching an agent with the Cloud target | Ask each time |
| Sync GitHub credentials | Lets cloud VMs use this Mac's git login to clone your repository, fetch, and push. This will allow the agent to access your GitHub | Off |
| Code Transfer | How your code gets onto a freshly provisioned cloud VM: **Git clone** (needs Sync GitHub credentials) or **Rsync** | Git clone once credentials sync; Rsync until then |
| Enabled | Whether a configured provider is offered as a launch target | On |

See [Cloud Agents](/docs/guides/cloud-agents).

## Mobile App

Pair an iPhone and watch, answer, and steer your agents from it.

| Control | What it does |
|---------|--------------|
| **1. Download** | The TestFlight beta invitation, an install QR code, and real iPhone app previews. iOS 18 or later. |
| **2. Enable → Direct** | Connect on your local network or through a VPN like Tailscale. Off by default; no Agentastic account needed. Shows the listening port when active. |
| **2. Enable → Through Agentastic Servers** | Connect from anywhere on the internet through an encrypted relay. Off by default; requires an Agentastic account. Works independently of Direct. |
| Reset Relay Access… | Revokes server credentials in existing pairing codes. Directly connected phones pick up the new credential; phones using only the server route must pair again. |
| **3. Pair → Pair Phone…** | Shows a pairing QR code to scan in **Agentastic → Settings → Pair a Mac** on your phone. Available when a connection is ready. |
| Paired devices | Connected status and controls to revoke access or remove a paired phone. |
| Keep this Mac awake while your phone needs it | While the Mac is plugged in, stops it idling to sleep while a paired phone is connected, and for 30 minutes after an agent needs you when a paired phone has notifications on. The display can still sleep, and closing the lid still sleeps the Mac. On by default. |

Enable Direct, Through Agentastic Servers, or both. The diagrams turn gray when their option is off. Both options are end-to-end encrypted. Keep Agentastic open; when the Mac goes to sleep anyway with agents working or waiting on you, your phone gets a notification first.

See [Companion for iPhone](/docs/features/companion).

## Containers

Runtime, images, and mounts for container-isolated agents.

| Setting | Description | Default |
|---------|-------------|---------|
| Container runtime | Docker or Apple Container; **Set Up…** installs or starts the selected runtime | Docker |
| Use containers | Offers Container mode when creating a workspace; requires a reachable runtime | On |
| Run new workspaces in | **Worktree Only** (code isolation) or **Worktree Inside a Container** (full isolation) | Worktree Only |
| Images | Images available for containers; the first entry is the default | See defaults |
| Shell configuration | Copy `.zshrc`, `.bashrc`, and `.p10k.zsh` and mount `.oh-my-zsh` into new containers | On |
| Git configuration | Share `~/.gitconfig` with containers | On |
| SSH keys | Share `~/.ssh/` with containers | Off |
| Network access | Full Access (`bridge`), API Only (`restricted`), or None | Full Access |
| Setup script | Container setup script location | `~/.config/agentastic/container-setup.sh` |

See [Docker Containers](/docs/how-to/containers) for the full reference.

## Fonts

| Setting | Description | Default |
|---------|-------------|---------|
| Code | Typeface, size, and weight for the editor — also applies to the diff viewer | SF Mono |
| Markdown | Text and code typefaces used by [Markdown documents](/docs/features/markdown) | System |
| Terminal | Terminal typeface, or **Use the code font** to follow the editor | SF Mono |

## Language Servers

Install, enable, and configure the language servers Agentastic runs for code intelligence.
See [Set Up LSP](/docs/how-to/setup-lsp) and [Language Servers](/docs/features/lsp).

## Repomix

Defaults for packing a repository into a single file an agent can read.

| Setting | Description |
|---------|-------------|
| Format | Output format for the packed repository |
| Include File Summary | Prepend a per-file summary |
| Include Directory Structure | Prepend the directory tree |
| Show Line Numbers | Number lines in the packed output |
| Remove Empty Lines | Strip blank lines |
| Include Patterns / Ignore Patterns | Which files are packed |
| Respect .gitignore | Honor the repository's ignore rules |
| Use Default Ignore Patterns | Apply Repomix's built-in ignore list |
| Token Limit | Cap the size of the packed output |

## Code Review

| Setting | Description | Default |
|---------|-------------|---------|
| Review Diff Action | Opens its prompt and model configuration in Tasks | - |
| Enabled Agents | Additional reviewers that receive the Review Diff prompt | Provider defaults |
| Custom Agents | Additional custom review commands | - |

## Developer

Advanced settings for development and debugging:

| Setting | Description |
|---------|-------------|
| Debug Mode | Enable debug logging |
| Inspector Tools | Show internal development tools |
