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 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 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 (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 |
| Suggested Next Steps | After a Chat turn finishes, show up to three likely next prompts 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 — 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 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 page. Layout and navigation live on the 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 for archive scripts and Import from Other Apps for following.
See 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 asksghfor its token whenever it needs one and never stores a copy, sogh auth login,gh auth switch, andgh auth logoutapply here too. If you aren't signed in, Sign In with GitHub CLI… runsgh auth login --webfor you: it copies the one-time code and opens GitHub. Ifghisn't installed, you can install it with Homebrew from the same place. Whenghis 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, andread:userscopes (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 asGH_TOKENso theirghcommands work too, unless a terminal already has a GitHub token of its own. Once you sign in togh, 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.
- GitHub CLI (recommended) — Uses the login you made with
-
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 |
| 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.
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.
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 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 | 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 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 |