Settings Reference
Every Agentastic settings page, section by section — general, workspaces, agents, tasks, skills, plugins, cloud, mobile app, containers, code review, terminal, appearance, and more.
Open Settings with Cmd+, or from the menu bar: Agentastic > Settings.
The sidebar lists these pages in order: General, Accounts, Workspaces, Agents, Tasks, Skills, Plugins, Cloud, Mobile App, Containers, Code Review, Terminal, Themes, Appearance (Font), Text Editing, Search, Source Control, Locations, Language Servers, Repomix, Developer.
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 |
| Show Jump Bar | Display breadcrumb navigation in editor | On |
| Focus Dimming | Dim unfocused panes | Off |
| Navigator Position | Place the navigator sidebar on the Left or Right | Left |
| Keep Mac awake while agents work | Stop the Mac idling to sleep while an agent is working; the display can still sleep, and closing the lid still sleeps the Mac | 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 |
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 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 | 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 (Claude Code and Codex) | Off |
| Custom Agents | Your own definitions, with any CLI command | - |
| Send Shortcut | Whether Return or ⌘ Return 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 the current turn. Holding ⌥ while sending does the opposite for that one message; agents that cannot steer always queue | Queue |
| 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 — 30 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 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.
Workspaces#
Worktree Settings#
| Setting | Description | Default |
|---|---|---|
| Worktree Location | Where new worktrees are stored | Adjacent |
| Worktree Setup Script | Path to setup script for new worktrees | .agentastic/setup.sh |
Container Settings#
| Setting | Description | Default |
|---|---|---|
| Container Images | Docker images available for containers | See defaults |
| Setup Script Path | Custom container setup script location | ~/.config/agentastic/container-setup.sh |
| Mount Git Config | Share ~/.gitconfig with containers | On |
| Mount SSH Keys | Share ~/.ssh/ with containers | Off |
| Copy Shell Config | Copy shell configs to container home | On |
| Network Mode | Container network access (Bridge/Restricted/None) | Bridge |
See Docker Containers 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.
- 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 page. See Plugins & MCP, Issue Tracking, and 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 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 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.
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.
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 |
| Code Transfer | How your code gets onto a freshly provisioned cloud VM | Provider default |
| Enabled | Whether a configured provider is offered as a launch target | On |
See Cloud Agents.
Mobile App#
Pair an iPhone and watch, answer, and steer your agents from it.
| Control | What it does |
|---|---|
| Enable connections from your phone | Starts the local companion host; off by default |
| Port | The port the host bound to, shown once it is running |
| Reach this Mac from anywhere | Lets the phone reach this Mac off your network through Agentastic's relay, which cannot read the session; off by default, needs an Agentastic account |
| Reset Relay Access… | Revokes the relay credential in every pairing code this Mac has shown; phones on your network pick up the new one automatically, relay-only phones pair again |
| iPhone App | Get It on TestFlight, plus a QR code to install the app with your iPhone's camera |
| Pair a Device… | Shows a pairing QR code to scan with the Agentastic app on your phone |
| Devices | Paired devices, with Remove for each |
See Companion for iPhone.
Containers#
Docker images and mounts for container-isolated agents. These are also reachable from the Workspaces page above; see Docker Containers for the full reference.
Appearance (Font)#
| Setting | Description | Default |
|---|---|---|
| Editor | Font, size, and weight for the editor — also applies to the diff viewer | SF Mono |
| Markdown | Font used by Markdown documents | System |
| Terminal | Terminal font, or Use text editor 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 and Language Servers.
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 |