*magenta-config.txt*     Configuration options for magenta.nvim

==============================================================================
CONTENTS                                              *magenta-config-contents*

    1. Setup ................................... |magenta-setup|
    2. Profiles ................................ |magenta-profiles|
    3. General Options ......................... |magenta-options|
    4. Sandbox .................................. |magenta-sandbox|
    5. Skills .................................. |magenta-skills|
    6. Project Settings ........................ |magenta-project-settings|
    7. Custom Commands ......................... |magenta-custom-commands|

==============================================================================
SETUP                                                        *magenta-setup*

Call `require('magenta').setup()` with a configuration table:
>lua
    require('magenta').setup({
      profiles = { ... },
      sidebarPosition = "left",
      picker = "fzf-lua",
      defaultKeymaps = true,
      -- see below for all options
    })
<

==============================================================================
PROFILES                                                   *magenta-profiles*

Profiles configure provider access. The first profile is the default.
Each profile specifies:

  - `name`: identifier for the profile
  - `provider`: "anthropic"
  - `model`: the specific model to use
  - `fastModel`: (optional) model for lightweight tasks
  - `authType`: (optional) "key" (default), "max" for Anthropic OAuth,
    or "keychain" to load a Claude Code Console API key from the macOS
    Keychain (see |magenta-claude-keychain|)
  - `apiKeyEnvVar`: environment variable containing the API key
  - `baseUrl`: (optional) custom API endpoint
  - `tokenRefreshCommand`: (optional, Bedrock-only) shell command to run
    when a request fails with an auth/credentials error. Used to refresh
    AWS SSO tokens. The command is re-run at most once per 30 seconds.
    Example: "aws sso login --profile myprofile"

Example:~
>lua
    profiles = {
      {
        name = "claude-sonnet",
        provider = "anthropic",
        model = "claude-sonnet-4-5",
        fastModel = "claude-haiku-4-5",
        apiKeyEnvVar = "ANTHROPIC_API_KEY"
      },

    }
<

With thinking/reasoning support:~

Opus 4.7 uses adaptive thinking (automatic budget allocation):
>lua
    {
      name = "claude-opus",
      provider = "anthropic",
      model = "claude-opus-4-7",
      apiKeyEnvVar = "ANTHROPIC_API_KEY",
      thinking = {
        enabled = true,
        displayThinking = false,  -- set true to stream thinking summaries
        effort = "max"            -- optional; see |magenta-providers|
      }
    }
<

See |magenta-providers| for provider-specific configuration and thinking
configuration details.

==============================================================================
GENERAL OPTIONS                                            *magenta-options*

                                                    *magenta-sidebarPosition*
sidebarPosition ~
    Type: `string`
    Default: `"left"`
    Values: `"left"` or `"right"`

    Position of the chat sidebar.

                                                          *magenta-picker*
picker ~
    Type: `string`
    Default: `"fzf-lua"`
    Values: `"fzf-lua"`, `"telescope"`, or `"snacks"`

    Fuzzy finder to use for file selection.

                                                    *magenta-defaultKeymaps*
defaultKeymaps ~
    Type: `boolean`
    Default: `true`

    Whether to enable default keymaps. See |magenta-default-keymaps|.

                                            *magenta-maxConcurrentSubagents*
maxConcurrentSubagents ~
    Type: `number`
    Default: `3`

    Maximum number of sub-agents that can run concurrently.

                                                      *magenta-chimeVolume*
chimeVolume ~
    Type: `number`
    Default: `0.3`
    Range: `0.0` to `1.0`

    Volume for notification chimes. Set to `0.0` to disable.
    Chimes play when the agent needs attention or tool approval.

                                               *magenta-bellOnNotify*
bellOnNotify ~
    Type: `boolean`
    Default: `true`

    Send a terminal bell when the agent finishes a response. When
    running inside tmux, this causes the window to be flagged in
    the status bar. Works through SSH tunnels and containers since
    the bell propagates as regular terminal output. Set to `false`
    to disable.

                                               *magenta-sandbox*
sandbox ~
    Type: `table`
    Default: See |magenta-permissions|

    Configure OS-level sandboxing for shell commands and file I/O.
    When the sandbox is ready, shell commands run in a restricted
    environment (seatbelt on macOS, bubblewrap on Linux). File I/O
    uses pre-flight checks against the same sandbox configuration.
    When the sandbox is unavailable (unsupported platform or missing
    dependencies), all shell commands and file writes prompt for
    approval.

    See |magenta-permissions| for the full configuration structure,
    fields, path matching rules, and merging behavior.
    See |magenta-security| for the overall security model.

                                                      *magenta-skillsPaths*
skillsPaths ~
    Type: `table`
    Default: `{ ".claude/skills" }`

    Directories containing skill subdirectories.

                                                     *magenta-scriptsPaths*
scriptsPaths ~
    Type: `table`
    Default: `{ "~/.magenta/scripts", ".magenta/scripts" }`

    Directories scanned for magenta scripts (`*.ts` files registering a
    script via the SDK). Both user-level and project-level directories are
    supported; later paths override earlier ones on name collisions.

                                            *magenta-suppressProjectSkills*
suppressProjectSkills ~
    Type: `table`
    Default: `{}`

    List of skill names to suppress when found in project-level skills
    directories. Useful when a project's shared `.magenta/` or `.claude/`
    config (e.g. via dotfiles or cloud sync) defines skills that conflict
    with your personal user-level skills. User-level skills with the same
    name are kept; project-level skills with these names are dropped.

    User-level only: this option is honored when set via lua `setup({...})`
    or in `~/.magenta/options.json`. It is ignored (with a warning) if set
    in a project's `.magenta/options.json`.

    See |magenta-skills-suppress| for details.

                                                    *magenta-sidebarKeymaps*
sidebarKeymaps ~
    Type: `table`

    Keymaps for the sidebar input buffer.
>lua
    sidebarKeymaps = {
      normal = {
        ["<CR>"] = ":Magenta send<CR>",
      }
    }
<

==============================================================================
SKILLS

Skills provide reusable context and instructions for specific tasks.
They are discovered automatically from configured directories.

See |magenta-skills| for the full guide on creating skills, including
file structure, frontmatter format, and TypeScript scripts.

==============================================================================
PROJECT SETTINGS                                   *magenta-project-settings*

Create `.magenta/options.json` in your project root for project-specific
configuration.

Merging behavior:~
  - `profiles`: Project profiles replace global profiles
  - `sandbox`: Project sandbox config arrays concatenate with global
    (e.g., `allowWrite` paths append to global `allowWrite` paths)
  - `autoContext`: Project patterns add to base auto context
  - `skillsPaths`: Project paths add to base skills paths
  - `suppressProjectSkills`: User-level only; ignored (with warning) when
    set in project options
  - `mcpServers`: Project servers merge (override same-name globals)
  - Other settings: Project overrides global

Example `.magenta/options.json`:~
>json
    {
      "profiles": [
        {
          "name": "project-claude",
          "provider": "anthropic",
          "model": "claude-opus-4-7",
          "apiKeyEnvVar": "PROJECT_ANTHROPIC_KEY"
        }
      ],
      "autoContext": ["README.md", "docs/*.md"],
      "skillsPaths": [".claude/skills", "team-skills"],
      "sandbox": {
        "filesystem": {
          "allowWrite": ["build/", "dist/"],
          "allowRead": [".env.local"]
        }
      },
      "mcpServers": {
        "postgres": {
          "command": "mcp-server-postgres",
          "args": ["--connection-string", "postgresql://localhost/mydb"]
        }
      }
    }
<

==============================================================================
CUSTOM COMMANDS                                     *magenta-custom-commands*

Define custom `@` commands that expand to predefined text.

Configuration:~
>lua
    customCommands = {
      {
        name = "@nedit",
        text = "DO NOT MAKE ANY EDITS TO CODE.",
        description = "Disable code editing"
      },
      {
        name = "@careful",
        text = "Be extra careful and double-check your work.",
        description = "Request extra caution"
      }
    }
<

Usage in input buffer:~
>
    @nedit Can you help me understand this algorithm?
<

Command names must start with `@` followed by a letter, then any
combination of letters, numbers, and underscores.

vim:tw=78:ts=8:noet:ft=help:norl:
