Settings Reference
All Agentastic settings and configuration options
Open Settings with Cmd+, or from the menu bar: Agentastic > Settings.
General#
| Setting | Description | Default |
|---|---|---|
| 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 |
Text Editing#
| Setting | Description | Default |
|---|---|---|
| Font | Editor font face | SF Mono |
| Font Size | 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 |
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 — 52 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 | - |
| Agentastic Prompt | Prepend Agentastic IDE instructions to the Agent Home prompt | On |
Structured Chat requires an agent Agentastic can drive over a structured protocol: Claude Code and Codex through their native integrations, plus every agent that speaks Agent Client Protocol — 24 of the 52 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 Launch Interface for the full list.
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.
- Integrations — Connect GitHub for pull requests and private clones, and issue trackers such as Linear and Sentry for issue mentions in prompts. See Issue Tracking.
Tasks#
Configure built-in Actions and create reusable agent tasks that appear in every repository and worktree.
| Setting | Description | Default |
|---|---|---|
| Fast Model | Provider and optional model used by Fast actions | Automatic |
| 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 |
Branch/display naming and inline commit-message generation consume a captured agent response directly. Headless preserves the selected agent's preferred interface in a hidden session without revealing the Utility Area, switching worktrees, or changing the current session selection. Agentastic closes that terminal or Chat after a valid result and retains failed sessions for inspection. Local terminal-first Codex and Claude agents return the result through a provider-native semantic record or durable transcript; remote or container-backed terminal-first agents use Chat. 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.
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 |