mirror of
https://github.com/samvallad33/vestige.git
synced 2026-04-26 01:06:21 +02:00
3fce1f0b70
- Add integration guides for Xcode 26.3, Cursor, VS Code, JetBrains, Windsurf - First cognitive memory server with documented Xcode 26.3 MCP support - Add npx @vestige/init — zero-config CLI that auto-detects IDEs and injects config - Overhaul README: "The open-source cognitive engine for AI" - Add "Why Not Just Use RAG?" comparison and cognitive science stack docs - Update license badge to AGPL-3.0
260 lines
6.6 KiB
Markdown
260 lines
6.6 KiB
Markdown
# Xcode 26.3
|
|
|
|
> Give Apple Intelligence 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.
|
|
|
|
**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](../../README.md#quick-start))
|
|
|
|
Verify Vestige is installed:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
mkdir -p ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig
|
|
open -e ~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/.claude
|
|
```
|
|
|
|
### 2. Add Vestige
|
|
|
|
Paste the following configuration:
|
|
|
|
```json
|
|
{
|
|
"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`:
|
|
|
|
```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
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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:
|
|
|
|
```markdown
|
|
## 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](../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:
|
|
|
|
```
|
|
~/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
|
|
|
|
<details>
|
|
<summary>"vestige" not showing in /context</summary>
|
|
|
|
1. 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
log show --predicate 'subsystem == "com.apple.dt.Xcode"' --last 5m | grep -i mcp
|
|
```
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Agent can't find vestige-mcp binary</summary>
|
|
|
|
Xcode's sandbox does not inherit your shell PATH. Use the full absolute path:
|
|
|
|
```json
|
|
"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.
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Embedding model fails to download</summary>
|
|
|
|
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:
|
|
```bash
|
|
HTTPS_PROXY=your-proxy:port vestige-mcp
|
|
```
|
|
</details>
|
|
|
|
---
|
|
|
|
## Also Works With
|
|
|
|
Vestige uses the MCP standard — the same memory works across all your tools:
|
|
|
|
| IDE | Guide |
|
|
|-----|-------|
|
|
| Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
|
|
| Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |
|
|
| Cursor | [Setup](./cursor.md) |
|
|
| VS Code (Copilot) | [Setup](./vscode.md) |
|
|
| JetBrains | [Setup](./jetbrains.md) |
|
|
| Windsurf | [Setup](./windsurf.md) |
|
|
|
|
Your AI remembers everything, everywhere.
|
|
|
|
---
|
|
|
|
<p align="center">
|
|
<a href="../../README.md">Back to README</a>
|
|
</p>
|