Settings
The CLI, the VS Code extension and the Desktop app read the same settings files, so a change you make in one applies in the others. This page covers where settings live, how they combine, and what each one does.
Models, API keys and subscriptions have their own page. See Providers.
Where settings live
| Scope | Location | Applies to | Good for |
|---|---|---|---|
| User | ~/.abacusai/config.json | You, in every project on your machine | Your defaults: model, notifications, updates |
| Workspace | <project>/.abacusai/config.json | Everyone who opens that project | Team rules: permissions, timeouts, project providers. Commit it to share. |
| Settings file | Any JSON file passed with abacusai --settings <file> | One CLI session | CI jobs and scripts |
| Environment | ABACUS_* variables | The current shell or container | Quick overrides, CI |
| VS Code | abacusAgent.* in the VS Code settings editor | The extension only | Editor options such as panel position and inline diffs |
Both config.json files use the same keys. A key that is missing from one file inherits its value from the layer below.
Precedence
When the same setting is defined in more than one place, the higher layer wins:
- Environment variables
- CLI flags such as
--model - Files passed with
--settings - Workspace
config.json - User
config.json - Built-in defaults
Objects merge key by key. Lists replace the lower layer whole. That matters for permission rules: a workspace allow list replaces your user allow list instead of adding to it. The /permissions view tells you when a list is being replaced this way.
Change a setting
In the CLI
Run /settings inside a session. Use Tab to switch between your user settings and the workspace settings.
| Key | Action |
|---|---|
↑ ↓ | Move between settings |
← → | Change a toggle or a choice |
Enter | Edit a number, or open a picker |
Tab | Switch between the user and workspace scope |
r | Reset the setting in this scope so it inherits again |
Esc | Close |
Each row shows where its value comes from: user, workspace, env, override (a --settings file or a CLI flag) or default. A value that comes from env or override cannot be edited here, because the file would not win. Each row also says when a change takes effect: immediately, on your next conversation, or after a restart.
In VS Code
Click the gear icon at the top of the Abacus AI panel. The settings page opens as an editor tab.
| Section | What you find there |
|---|---|
| Account | Who you are signed in as, your organization, this month's credit usage |
| General | Notifications, panel position |
| Agent | AGENTS.md loading, default model, default permission mode, use my own API keys, local only mode, and the link to Local LLM providers |
| MCP Servers | Add, edit and remove servers. See MCP configuration. |
| Skills | Installed skills and the marketplace. See Skills. |
Settings that the CLI shares are written to your user config.json, so the CLI picks them up too.
By hand
Open either config.json in an editor. It is plain JSON.
{
"permissionMode": "ACCEPTEDITS",
"notifications": "sound",
"autoLoadAgentsMd": true,
"permissions": {
"allow": ["Bash(npm test *)", "Bash(git log *)"],
"deny": ["Read(.env)"]
}
}
To set a default model, pick it in /settings or in the extension rather than typing an id. The picker writes the right value for you.
Settings reference
All keys go in config.json. The CLI column is the label you see in /settings, and the VS Code column is the id in VS Code's settings editor. A blank cell means that surface does not show the setting.
| Key | CLI | VS Code | Default | What it does |
|---|---|---|---|---|
model | Default model | abacusAgent.defaultModel | Abacus.AI default | Model that new conversations start on |
smallModel | Aux model | unset | Model used for chat titles and summaries | |
permissionMode | Default mode | abacusAgent.defaultPermissionMode | Normal | Mode a session starts in. See Permission modes. Restart to apply. |
permissions | /permissions | unset | Allow, ask and deny rules. See Permission rules. | |
autoLoadAgentsMd | Load AGENTS.md | abacusAgent.autoLoadAgentsMd | on | Send your project's AGENTS.md at the start of each conversation |
notifications | Notifications | abacusAgent.notifications | full | How you are told a task finished while the window is unfocused: full, sound or off |
useOwnApiKeys | Use my own API keys | abacusAgent.useOwnApiKeys | off | Bill supported Abacus.AI models to your own API key instead of credits. See Providers. |
localOnly | Local only mode | abacusAgent.localOnly | off | Show local models and local chats only. See Providers. |
compressToolOutput | Compress tool output | off | Shrink command output and file reads before they reach the model | |
loadExternalMcpConfigs | External MCP configs | abacusAgent.loadExternalMcpConfigs | off | Also read MCP servers from Cursor, VS Code, Claude Desktop and Windsurf. Restart to apply. |
toolTimeoutMs | Tool timeout | 120 s | How long any single tool may run, from 1 to 600 seconds | |
bashToolTimeoutMs | Bash timeout | 120 s | Default timeout for shell commands | |
autoUpdate | Updates | auto | auto installs and relaunches, prompt asks first, off only tells you an update exists. User scope only. | |
updateChannel | Update channel | stable | latest for stable releases or canary for the newest build. User scope only. | |
providers | /providers | Local LLM providers | unset | Your own model providers. See Providers. |
Permission modes
The agent asks before it runs tools that change things. The mode decides how much it asks.
| Mode | What happens | permissionMode value |
|---|---|---|
| Normal | Asks before every edit and command | DEFAULT |
| Accept edits | Applies file edits without asking, still asks for commands | ACCEPTEDITS |
| Plan | Explores and writes a plan, then asks you to approve it before making changes | PLAN |
| Yolo | Approves everything except questions it asks you | YOLO |
Press Shift+Tab in the CLI to cycle modes for the current session. Press it twice quickly for Yolo. In VS Code, use the mode dropdown next to the send button.
To start in a mode every time, set permissionMode, or pass --permission-mode normal|accept-edits|plan|yolo to the CLI. --auto-accept-edits and --dangerously-skip-permissions are shorthands for Accept edits and Yolo.
Permission rules
Rules decide specific tools before the mode gets a say. They live under permissions in either config.json. Edit them with /permissions in the CLI, or answer "always allow" when the agent asks.
{
"permissions": {
"allow": ["Bash(git log *)", "Bash(npm test *)", "Read"],
"ask": ["Edit(src/generated/**)"],
"deny": ["Read(.env)", "Bash(rm -rf *)"]
}
}
| Pattern | Matches |
|---|---|
Bash or Bash(*) | Every use of the tool |
Bash(git log *) | Commands that start with git log |
Read(.env), Edit(src/**) | File paths, with gitignore-style wildcards |
mcp__github__create_issue | One MCP tool, written as mcp__<server>__<tool> |
Deny rules are checked first, then ask, then allow. The first match wins. With no match, the mode decides. For one session, --allowed-tools and --disallowed-tools add to the allow and deny lists.
"Always allow" answers are saved to the workspace config.json. Because lists replace rather than merge, keep your shared rules in one scope.
Environment variables
Environment variables override every file. They are handy in CI and containers.
| Variable | What it sets |
|---|---|
ABACUS_API_KEY | Signs you in without a stored login |
ABACUS_MODEL | The model, same as model |
ABACUS_PERMISSION_MODE | normal, accept-edits, plan or yolo |
ABACUS_AUTO_LOAD_AGENTS_MD | true or false |
ABACUS_AUTO_UPDATE | auto, prompt or off |
ABACUS_TOOL_TIMEOUT_MS | Tool timeout in milliseconds |
ABACUS_BASH_TIMEOUT_MS | Shell command timeout in milliseconds |
API keys for your own providers, such as OPENAI_API_KEY, are covered on the Providers page.
CLI flags
Run abacusai --help for the full list. These flags change settings for one session:
| Flag | Effect |
|---|---|
--model <id> | Model for this session |
--permission-mode <mode> | normal, accept-edits, plan or yolo |
--allowed-tools <pattern> | Add an allow rule. Repeat for more. |
--disallowed-tools <pattern> | Add a deny rule. Repeat for more. |
--add-dir <path> | Let the agent work in another directory too |
--no-agents-md | Skip AGENTS.md |
--settings <file> | Merge a JSON settings file |
--mcp-config <file> | Add an MCP config file |
--print, -p | Print the answer and exit, without the interactive interface |
VS Code settings
A few options only make sense in the editor. Find them in VS Code's settings editor under "Abacus", or click "Open settings" at the bottom of the Abacus Settings page.
| Setting | What it does |
|---|---|
abacus.viewKind | Where the panel opens: primary sidebar, secondary sidebar, an editor tab, or an editor tab to the side |
abacusAgent.inlineDiffEditor | Show the agent's edits inline in your file with accept and reject buttons, instead of a two-pane diff |
abacusAgent.notifications | Sound and popup, sound only, or off |
abacusAgent.defaultModel | Model for new conversations |
abacusAgent.defaultPermissionMode | Mode new conversations start in |
Troubleshooting
A setting does not apply
Open /settings and look at the tag on the row. env or override means an environment variable, a --settings file or a flag is winning. workspace while you edited the user file means the workspace file wins. For lists such as permission rules, remember that the workspace list replaces the user list.
The CLI ignores config.json
A missing comma or bracket makes the whole file unreadable, and the CLI falls back to defaults. Paste the file into any JSON validator to find the spot.
A change did not take effect
permissionMode and loadExternalMcpConfigs apply the next time you start. The model and the timeouts apply to your next conversation. To change the current session, use /model or Shift+Tab.
For further help, reach out at support@abacus.ai.