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.

View as Markdown

Open Settings with Cmd+, or from the menu bar: Agentastic > Settings.

The sidebar groups its pages:

GroupPages
(top)General, Accounts, Sidebar
Agents & AutomationAgents, Tasks, Skills, Plugins, Code Review
EnvironmentsWorkspaces, Containers, Cloud
ToolsTerminal, Browser, Computer Use, Mobile App, Repomix
Editor & FilesText Editing, Fonts, Themes, Search, Source Control, Language Servers, Locations

General#

SettingDescriptionDefault
Pane StyleClassic tiles editor panes edge to edge with thin dividers; Modern draws each pane as a rounded card with space around itModern
Sidebar StyleClassic 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 laterModern
Show the jump barDisplay breadcrumb navigation in editorOn
Dim editors that don't have focusDim unfocused panesOff
Navigator PositionPlace the navigator sidebar on the Left or RightLeft
Keep the Mac awake while agents workStop 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 AppOn

Text Editing#

SettingDescriptionDefault
FontEditor and diff viewer font faceSF Mono
Font SizeEditor and diff viewer text size in points13
Line HeightLine spacing multiplier1.5
Tab WidthSpaces per tab4
Insert SpacesUse spaces instead of tabsOn
Word WrapWrap long linesOn
Markdown ViewRender Markdown as plain text, markdown, or splitMarkdown
Check spelling in MarkdownUnderline misspelled words in Markdown documents. Autocorrect only runs there while this is onOff

Terminal#

SettingDescriptionDefault
Terminal EmulatorGhostty or SwiftTermGhostty
ShellDefault shellSystem Default
FontTerminal font faceSF Mono
Font SizeTerminal text size13
Cursor StyleBlock, underline, or barBlock
Cursor BlinkAnimate cursorOn
Option as MetaUse Option as Meta keyOff
Auto-copy Selected TextCopy to the clipboard as soon as you selectOff
Open Links & Files on ClickClick URLs and file paths in the terminal to open themOn
Image PreviewsHover an image path in the terminal for an inline previewOn
Enable File PreviewHover a file:line reference for a syntax-highlighted code previewOn

Theme#

SettingDescriptionDefault
Editor ThemeSyntax highlighting themeDefault
Match SystemFollow system dark/light modeOn
Enable glass effectLet the desktop show through the window, sidebars, editor, chat, and terminals. Full screen and Reduce Transparency stay opaqueOff
Glass amountHow much of the desktop shows through, from 0% (a solid theme tint) to 100% (the desktop blur alone), in steps of 1020%
SettingDescriptionDefault
Ignore PatternsFiles/folders to excludenode_modules, .git
Search LimitMaximum results1000

Keybindings#

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

Locations#

SettingDescription
Default Save LocationWhere new files are saved
Recent ProjectsList of recently opened projects
SettingDescriptionDefault
Show Hidden FilesDisplay dotfilesOff
Sort Folders FirstFolders before filesOn

Source Control#

SettingDescriptionDefault
Auto FetchAutomatically fetch from remoteOff
Fetch IntervalTime between auto fetches5 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:

ElementMeaning
VersionThe version detected on your machine
Update chipA newer version is available; click it to update in place
Chat chipThe agent can run in structured Chat as well as a terminal
PinPins the agent to the top of the grid and of the Agent Home picker
InstallRuns 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.

SettingDescriptionDefault
Launch InterfaceWhether this agent opens in Terminal or ChatChat when the agent supports it, otherwise Terminal
Executable SourceAuto-detected path, or one you specifyAuto
Show Subscription UsageShow the agent's remaining subscription quota in the Inspector's Agents card (Claude Code and Codex)Off
Custom AgentsYour own definitions, with any CLI command-
Send ShortcutWhether Return or ⌘ Return submits a prompt; every other Return chord opens a new line. Applies to the Agent Home prompt and the chat composer alikeReturn
Follow-up BehaviorWhether 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 queueQueue
Suggested Next StepsAfter 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 requestOn
Agentastic PromptPrepend Agentastic IDE instructions to the Agent Home promptOn

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.

Control how workspaces appear and how you switch between them.

SettingDescriptionDefault
Group workspaces byRepository, server, project, or a flat listRepository
Sort workspaces byName, creation date, or recent activity; pinned workspaces stay firstCreation Date
Workspace tilesCompact uses one line; Detailed adds branch, commit, CI, and timeCompact
Switch workspaces withSingle or double clickSingle Click
Order the workspace switcher byVisits, notifications, or a blend of bothVisited + 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.

SettingDescriptionDefault
Create workspacesWhere new worktrees are stored: inside the repository (.worktree/), next to it (-worktrees/), or in one folder for all repositoriesNext to the Repository
Files to copyRepo-root files or folders copied into every new workspace before its setup script runs; per-repo setup belongs in .agentastic/setup.shNone
Archive scriptRuns before a workspace is archived; absolute, or relative to the workspace root. An archive list in the repository's .agentastic/config.json takes precedenceNone
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 appPer source app: picks up that app's new workspaces when repositories refreshOff

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 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 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.

SettingDescriptionDefault
Fast ModelProvider, model, and thinking effort used by Fast actionsAutomatic; Haiku for Claude Code, Terra + Medium for Codex
Thorough ModelProvider and optional model used by Thorough actionsAutomatic
Add TaskCreate a globally available custom Action-
ModelPer-action override of the selected tier's modelTier default
PromptPrompt template; all 15 Actions placeholders are available to every taskBuilt-in prompt or custom task prompt
Run InExecution destination; automatic result tasks offer Headless or Utility ChatPrimary 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.

ControlWhat it does
Skill MarketplaceBrowse and install skills from the Skillopedia catalog
Install from GitHubInstall a skill from any repository
Installed SkillsUpdate 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.

ControlWhat it does
Installed / SuggestedThe connected plugins, and the built-in catalog you haven't connected yet
ConnectOpens 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
UninstallRemoves the plugin and its stored credentials from this Mac

See Plugins & MCP.

Cloud#

Run agents on cloud VMs you provision yourself.

SettingDescriptionDefault
Add Provider...Connect a cloud backend and its credentials-
Default ProviderUsed when launching an agent with the Cloud targetAsk each time
Sync GitHub credentialsLets cloud VMs use this Mac's git login to clone your repository, fetch, and push. This will allow the agent to access your GitHubOff
Code TransferHow your code gets onto a freshly provisioned cloud VM: Git clone (needs Sync GitHub credentials) or RsyncGit clone once credentials sync; Rsync until then
EnabledWhether a configured provider is offered as a launch targetOn

See Cloud Agents.

Mobile App#

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

ControlWhat it does
1. DownloadThe TestFlight beta invitation, an install QR code, and real iPhone app previews. iOS 18 or later.
2. Enable → DirectConnect 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 ServersConnect 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 devicesConnected status and controls to revoke access or remove a paired phone.
Keep this Mac awake while your phone needs itWhile 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.

SettingDescriptionDefault
Container runtimeDocker or Apple Container; Set Up… installs or starts the selected runtimeDocker
Use containersOffers Container mode when creating a workspace; requires a reachable runtimeOn
Run new workspaces inWorktree Only (code isolation) or Worktree Inside a Container (full isolation)Worktree Only
ImagesImages available for containers; the first entry is the defaultSee defaults
Shell configurationCopy .zshrc, .bashrc, and .p10k.zsh and mount .oh-my-zsh into new containersOn
Git configurationShare ~/.gitconfig with containersOn
SSH keysShare ~/.ssh/ with containersOff
Network accessFull Access (bridge), API Only (restricted), or NoneFull Access
Setup scriptContainer setup script location~/.config/agentastic/container-setup.sh

See Docker Containers for the full reference.

Fonts#

SettingDescriptionDefault
CodeTypeface, size, and weight for the editor — also applies to the diff viewerSF Mono
MarkdownText and code typefaces used by Markdown documentsSystem
TerminalTerminal typeface, or Use the code font to follow the editorSF 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.

SettingDescription
FormatOutput format for the packed repository
Include File SummaryPrepend a per-file summary
Include Directory StructurePrepend the directory tree
Show Line NumbersNumber lines in the packed output
Remove Empty LinesStrip blank lines
Include Patterns / Ignore PatternsWhich files are packed
Respect .gitignoreHonor the repository's ignore rules
Use Default Ignore PatternsApply Repomix's built-in ignore list
Token LimitCap the size of the packed output

Code Review#

SettingDescriptionDefault
Review Diff ActionOpens its prompt and model configuration in Tasks-
Enabled AgentsAdditional reviewers that receive the Review Diff promptProvider defaults
Custom AgentsAdditional custom review commands-

Developer#

Advanced settings for development and debugging:

SettingDescription
Debug ModeEnable debug logging
Inspector ToolsShow internal development tools