vestige/docs/integrations/xcode.md

Xcode 26.3

Give Apple Intelligence a brain that remembers.

Xcode 26.3 supports agentic coding with full MCP (Model Context Protocol) integration. Vestige plugs directly into Xcode's Claude Agent, giving it persistent memory across every coding session.

Vestige is the first cognitive memory server for Xcode.

---

Prerequisites

• Xcode 26.3 or later (Release Candidate or stable)
• vestige-mcp binary installed (Installation guide)

Verify Vestige is installed:

which vestige-mcp
# Should output: /usr/local/bin/vestige-mcp

If you installed to a different location, note the absolute path — you'll need it below.

---

Setup

1. Open the config file

Xcode's Claude Agent reads MCP configuration from:

~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude

Create or edit this file:

mkdir -p ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig
open -e ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude

2. Add Vestige

Paste the following configuration:

{
  "projects": {
    "*": {
      "mcpServers": {
        "vestige": {
          "type": "stdio",
          "command": "/usr/local/bin/vestige-mcp",
          "args": [],
          "env": {
            "PATH": "/usr/local/bin:/usr/bin:/bin"
          }
        }
      },
      "hasTrustDialogAccepted": true
    }
  }
}

Important: Xcode runs agents in a sandboxed environment that does not inherit your shell configuration (.zshrc, .bashrc, etc.). You must use absolute paths for the command field and explicitly set PATH in the env block.

Project-specific memory

To give each project its own isolated memory, use --data-dir:

{
  "projects": {
    "/Users/you/Developer/MyApp": {
      "mcpServers": {
        "vestige": {
          "type": "stdio",
          "command": "/usr/local/bin/vestige-mcp",
          "args": ["--data-dir", "/Users/you/Developer/MyApp/.vestige"],
          "env": {
            "PATH": "/usr/local/bin:/usr/bin:/bin"
          }
        }
      },
      "hasTrustDialogAccepted": true
    }
  }
}

3. Restart Xcode

Quit and reopen Xcode. The Claude Agent will now load Vestige on startup.

4. Verify

In Xcode's Agent panel, type:

/context

You should see vestige listed as an available MCP server with its tools (search, smart_ingest, memory, etc.).

---

First Use

Open any project and ask the Claude Agent:

"Remember that this project uses SwiftUI with MVVM architecture and targets iOS 18+"

Start a new session, then ask:

"What architecture does this project use?"

It remembers.

---

What Vestige Does for Xcode

Without Vestige	With Vestige
Every session starts from zero	Agent recalls your architecture, patterns, and preferences
Re-explain SwiftUI conventions each time	Agent knows your conventions from day one
Bug fixes are forgotten	Agent remembers past fixes and avoids regressions
No context between Xcode and other IDEs	Shared memory across Xcode, Cursor, VS Code, and more

Example Workflows

Architecture decisions:

"Remember: we chose Observation framework over Combine for state management because it's simpler and Apple-recommended for iOS 17+."

Bug documentation:

The agent fixes a Core Data migration crash? Vestige automatically stores the fix. Next time it encounters a migration issue, it remembers the solution.

Cross-IDE memory:

Fix a backend bug in VS Code. Open the iOS app in Xcode. The agent already knows about the API change because Vestige shares memory across all your tools.

---

Tips

Use a CLAUDE.md for proactive memory

Place a CLAUDE.md in your project root to make the agent use Vestige automatically:

## Memory

At the start of every session:
1. Search Vestige for this project's context
2. Recall architecture decisions and coding patterns
3. Save important decisions and bug fixes without being asked

See CLAUDE.md templates for a full setup.

Embedding model cache

The first time Vestige runs, it downloads the Nomic embedding model (~130MB). In Xcode's sandboxed environment, the cache location is:

~/Library/Caches/com.vestige.core/fastembed

If the download fails behind a corporate proxy, pre-download by running vestige-mcp once from your terminal before using it in Xcode.

Skills integration

You can add Vestige-related skills to Xcode's skills directory:

~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/skills/

Drop a markdown file describing how the agent should use memory for your iOS/macOS projects.

---

Troubleshooting

"vestige" not showing in /context

1. Verify the binary path is correct and absolute:

   ls -la /usr/local/bin/vestige-mcp
   

2. Check that the config file is valid JSON:

   cat ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude | python3 -m json.tool
   

3. Ensure you fully quit and restarted Xcode (Cmd+Q, not just close window).

4. Check Xcode's agent logs for errors:

   log show --predicate 'subsystem == "com.apple.dt.Xcode"' --last 5m | grep -i mcp
   

Agent can't find vestige-mcp binary

Xcode's sandbox does not inherit your shell PATH. Use the full absolute path:

"command": "/usr/local/bin/vestige-mcp"

If you installed via cargo build, the binary is likely at:

/Users/you/.cargo/bin/vestige-mcp

Or wherever you copied it. Run which vestige-mcp in your terminal to find it.

Embedding model fails to download

The first run downloads ~130MB. If Xcode's sandbox blocks the download:

1. Run vestige-mcp once from your terminal to cache the model
2. The cache at ~/Library/Caches/com.vestige.core/fastembed will be available to the sandboxed instance

Behind a proxy:

HTTPS_PROXY=your-proxy:port vestige-mcp

---

Also Works With

Vestige uses the MCP standard — the same memory works across all your tools:

IDE	Guide
Claude Code	Setup
Claude Desktop	Setup
Cursor	Setup
VS Code (Copilot)	Setup
JetBrains	Setup
Windsurf	Setup

Your AI remembers everything, everywhere.

---

Back to README