mirror of
https://github.com/samvallad33/vestige.git
synced 2026-04-25 00:36:22 +02:00
feat: Xcode 26.3 integration — install script, updated docs, blog post
Discovered that Xcode's claudeai-mcp feature gate blocks custom MCP servers from the global .claude config. Project-level .mcp.json files bypass this gate entirely — this is now the documented method. - Add scripts/xcode-setup.sh: auto-installs vestige-mcp and configures .mcp.json for any Xcode project with checksum verification - Rewrite docs/integrations/xcode.md with .mcp.json method, gate bypass docs, and new troubleshooting for "Agent has been closed" error - Add docs/blog/xcode-memory.md: launch blog post for Vestige on Xcode
This commit is contained in:
Sam Valladares
parent
1bc4a762dc
commit
33d8b6b405
3 changed files with 527 additions and 110 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Xcode 26.3
|
||||
|
||||
> Give Apple Intelligence a brain that remembers.
|
||||
> Give Xcode's AI agent a brain that remembers.
|
||||
|
||||
Xcode 26.3 supports [agentic coding](https://developer.apple.com/documentation/xcode/giving-agentic-coding-tools-access-to-xcode) with full MCP (Model Context Protocol) integration. Vestige plugs directly into Xcode's Claude Agent, giving it persistent memory across every coding session.
|
||||
|
||||
|
|
@ -8,116 +8,60 @@ Xcode 26.3 supports [agentic coding](https://developer.apple.com/documentation/x
|
|||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
## Quick Start (30 seconds)
|
||||
|
||||
- **Xcode 26.3** or later (Release Candidate or stable)
|
||||
- **vestige-mcp** binary installed ([Installation guide](../../README.md#quick-start))
|
||||
|
||||
Verify Vestige is installed:
|
||||
### 1. Install Vestige
|
||||
|
||||
```bash
|
||||
which vestige-mcp
|
||||
# Should output: /usr/local/bin/vestige-mcp
|
||||
curl -L https://github.com/samvallad33/vestige/releases/latest/download/vestige-mcp-aarch64-apple-darwin.tar.gz | tar -xz
|
||||
sudo mv vestige-mcp vestige vestige-restore /usr/local/bin/
|
||||
```
|
||||
|
||||
If you installed to a different location, note the **absolute path** — you'll need it below.
|
||||
### 2. Add to your Xcode project
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
Create a `.mcp.json` file in your project root:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig
|
||||
open -e ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude
|
||||
```
|
||||
|
||||
### 2. Add Vestige
|
||||
|
||||
Paste the following configuration:
|
||||
|
||||
```json
|
||||
cat > /path/to/your/project/.mcp.json << 'EOF'
|
||||
{
|
||||
"projects": {
|
||||
"*": {
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"type": "stdio",
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": [],
|
||||
"env": {
|
||||
"PATH": "/usr/local/bin:/usr/bin:/bin"
|
||||
}
|
||||
}
|
||||
},
|
||||
"hasTrustDialogAccepted": true
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"type": "stdio",
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": [],
|
||||
"env": {
|
||||
"PATH": "/usr/local/bin:/usr/bin:/bin"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
> **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.
|
||||
Or use the setup script:
|
||||
|
||||
#### Project-specific memory
|
||||
|
||||
To give each project its own isolated memory, use `--data-dir`:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
}
|
||||
}
|
||||
}
|
||||
```bash
|
||||
curl -sSL https://raw.githubusercontent.com/samvallad33/vestige/main/scripts/xcode-setup.sh -o xcode-setup.sh
|
||||
bash xcode-setup.sh
|
||||
```
|
||||
|
||||
### 3. Restart Xcode
|
||||
|
||||
Quit and reopen Xcode. The Claude Agent will now load Vestige on startup.
|
||||
Quit Xcode completely (Cmd+Q) and reopen your project.
|
||||
|
||||
### 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.).
|
||||
Type `/context` in the Agent panel. You should see `vestige` listed with 23 tools.
|
||||
|
||||
---
|
||||
|
||||
## First Use
|
||||
## Why `.mcp.json` instead of the global config?
|
||||
|
||||
Open any project and ask the Claude Agent:
|
||||
Xcode 26.3's Claude Agent has a feature gate (`claudeai-mcp`) that blocks custom MCP servers configured in the global config at `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude`.
|
||||
|
||||
> "Remember that this project uses SwiftUI with MVVM architecture and targets iOS 18+"
|
||||
**Project-level `.mcp.json` files bypass this gate entirely.** This is the method that actually works. Drop the file in your project root and Xcode loads it on the next session.
|
||||
|
||||
Start a **new session**, then ask:
|
||||
|
||||
> "What architecture does this project use?"
|
||||
|
||||
It remembers.
|
||||
> **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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -129,6 +73,7 @@ It remembers.
|
|||
| 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 |
|
||||
| AI hallucinations persist forever | Agent detects and self-corrects bad memories |
|
||||
|
||||
### Example Workflows
|
||||
|
||||
|
|
@ -138,11 +83,67 @@ It remembers.
|
|||
**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.
|
||||
|
||||
**Proactive reminders:**
|
||||
> The agent surfaces your pending deadlines, hackathon dates, and concert tickets — right inside Xcode's Agent panel.
|
||||
|
||||
**Self-correcting memory:**
|
||||
> The agent traces a hallucinated detail back to a specific memory, identifies it as wrong, and deletes it autonomously.
|
||||
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
## Add Vestige to Every Project
|
||||
|
||||
Run the setup script with `a` to install into all detected projects:
|
||||
|
||||
```bash
|
||||
curl -sSL https://raw.githubusercontent.com/samvallad33/vestige/main/scripts/xcode-setup.sh -o xcode-setup.sh
|
||||
bash xcode-setup.sh
|
||||
```
|
||||
|
||||
Or manually drop `.mcp.json` into any project:
|
||||
|
||||
```bash
|
||||
# From inside your project directory
|
||||
cat > .mcp.json << 'EOF'
|
||||
{
|
||||
"mcpServers": {
|
||||
"vestige": {
|
||||
"type": "stdio",
|
||||
"command": "/usr/local/bin/vestige-mcp",
|
||||
"args": [],
|
||||
"env": {
|
||||
"PATH": "/usr/local/bin:/usr/bin:/bin"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
### Per-project isolated memory
|
||||
|
||||
To give each project its own memory database:
|
||||
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
### Use a CLAUDE.md for proactive memory
|
||||
|
|
@ -162,23 +163,13 @@ See [CLAUDE.md templates](../CLAUDE-SETUP.md) 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:
|
||||
The first time Vestige runs, it downloads the 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.
|
||||
If the download fails behind a corporate proxy, pre-download by running `vestige-mcp` once from your terminal.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -187,39 +178,51 @@ Drop a markdown file describing how the agent should use memory for your iOS/mac
|
|||
<details>
|
||||
<summary>"vestige" not showing in /context</summary>
|
||||
|
||||
1. Verify the binary path is correct and absolute:
|
||||
1. Make sure `.mcp.json` is in your **project root** (same directory as `.xcodeproj` or `Package.swift`):
|
||||
```bash
|
||||
ls -la /path/to/project/.mcp.json
|
||||
```
|
||||
|
||||
2. Verify the binary path is correct and absolute:
|
||||
```bash
|
||||
ls -la /usr/local/bin/vestige-mcp
|
||||
```
|
||||
|
||||
2. Check that the config file is valid JSON:
|
||||
3. Check that `.mcp.json` is valid JSON:
|
||||
```bash
|
||||
cat ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude | python3 -m json.tool
|
||||
cat /path/to/project/.mcp.json | python3 -m json.tool
|
||||
```
|
||||
|
||||
3. Ensure you fully quit and restarted Xcode (Cmd+Q, not just close window).
|
||||
4. Fully quit and restart Xcode (Cmd+Q, not just close window).
|
||||
|
||||
4. Check Xcode's agent logs for errors:
|
||||
5. Check debug logs:
|
||||
```bash
|
||||
log show --predicate 'subsystem == "com.apple.dt.Xcode"' --last 5m | grep -i mcp
|
||||
cat ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/debug/latest | grep -i vestige
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Agent can't find vestige-mcp binary</summary>
|
||||
<summary>"Agent has been closed" or "Your request couldn't be completed"</summary>
|
||||
|
||||
Xcode's sandbox does not inherit your shell PATH. Use the full absolute path:
|
||||
This is a known issue with Xcode 26.3's Claude Agent that can happen independently of MCP configuration.
|
||||
|
||||
```json
|
||||
"command": "/usr/local/bin/vestige-mcp"
|
||||
**Nuclear fix:** Delete the agent config and let Xcode recreate it:
|
||||
```bash
|
||||
mv ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig \
|
||||
~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig.bak
|
||||
```
|
||||
Then restart Xcode and sign back into Claude in Settings > Intelligence.
|
||||
|
||||
If you installed via `cargo build`, the binary is likely at:
|
||||
```
|
||||
/Users/you/.cargo/bin/vestige-mcp
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Global .claude config not loading MCP servers</summary>
|
||||
|
||||
Xcode 26.3 has a feature gate (`claudeai-mcp`) that may block custom MCP servers from the global config file at `~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude`.
|
||||
|
||||
**Solution:** Use project-level `.mcp.json` instead. This bypasses the gate. See the [Quick Start](#quick-start-30-seconds) above.
|
||||
|
||||
Or wherever you copied it. Run `which vestige-mcp` in your terminal to find it.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
|
@ -234,6 +237,7 @@ Behind a proxy:
|
|||
```bash
|
||||
HTTPS_PROXY=your-proxy:port vestige-mcp
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue