Skip to content

Commit addade7

Browse files
kochj23claude
kochj23
and
claude
committed
docs: Add detailed INSTALLATION.md — full setup guide
Covers system requirements, DMG install, model downloads, first chat, enabling the Xcode Source Editor Extension, project directory setup, building from source, troubleshooting, and storage locations. README Installation section now links to INSTALLATION.md with a quick-start summary above the fold. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
1 parent ffa932f commit addade7

2 files changed

Lines changed: 296 additions & 11 deletions

File tree

‎INSTALLATION.md‎

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
# MLX Code — Installation & Setup Guide
2+
3+
Everything you need to go from zero to using MLX Code as a standalone app and as an Xcode extension.
4+
5+
---
6+
7+
## Table of Contents
8+
9+
1. [System Requirements](#1-system-requirements)
10+
2. [Install the App](#2-install-the-app)
11+
3. [Download Your First Model](#3-download-your-first-model)
12+
4. [Load a Model and Start Chatting](#4-load-a-model-and-start-chatting)
13+
5. [Enable the Xcode Extension](#5-enable-the-xcode-extension)
14+
6. [Using the Xcode Extension](#6-using-the-xcode-extension)
15+
7. [Set a Project Directory](#7-set-a-project-directory)
16+
8. [Build from Source](#8-build-from-source)
17+
9. [Troubleshooting](#9-troubleshooting)
18+
19+
---
20+
21+
## 1. System Requirements
22+
23+
| Requirement | Minimum | Recommended |
24+
|-------------|---------|-------------|
25+
| macOS | 14.0 Sonoma | 15.0 Sequoia |
26+
| Chip | Apple Silicon (M1) | M2 Pro / M3 / M4 |
27+
| RAM | 8 GB | 16 GB |
28+
| Storage | 5 GB free | 20 GB free (for models) |
29+
| Xcode | Not required for chat | 15.0+ for Xcode Extension |
30+
| Python | **Not required** | — |
31+
32+
No Python, no pip, no conda. MLX Code is fully self-contained.
33+
34+
---
35+
36+
## 2. Install the App
37+
38+
### Option A — DMG (Recommended)
39+
40+
1. Download `MLXCode-vX.Y.Z-buildN.dmg` from [Releases](https://github.com/kochj23/MLXCode/releases)
41+
2. Double-click the DMG to mount it
42+
3. Drag **MLX Code** to your **Applications** folder
43+
4. Eject the DMG
44+
5. Open **MLX Code** from Applications or Spotlight
45+
46+
> **First launch:** macOS may show a warning that the app is from an unidentified developer. Go to **System Settings → Privacy & Security**, scroll down to the security section, and click **Open Anyway**.
47+
48+
### Option B — Build from Source
49+
50+
See [Section 8 — Build from Source](#8-build-from-source).
51+
52+
---
53+
54+
## 3. Download Your First Model
55+
56+
MLX Code runs models locally on your Mac. You need to download at least one model before you can start chatting. Models are stored in `~/Documents/MLXCode/models` by default.
57+
58+
### Recommended Models
59+
60+
| Model | Size | RAM Needed | Best For |
61+
|-------|------|-----------|----------|
62+
| **Qwen 2.5 7B Instruct 4-bit** ⭐ | ~4 GB | 8 GB | Best overall — fast, good at coding and tool calling |
63+
| Qwen 2.5 14B Instruct 4-bit | ~8 GB | 16 GB | Better quality, needs more RAM |
64+
| Mistral 7B Instruct v0.3 4-bit | ~4 GB | 8 GB | Good general purpose |
65+
| DeepSeek Coder 6.7B 4-bit | ~4 GB | 8 GB | Specialised for code |
66+
| Phi-3.5 Mini 4-bit | ~2 GB | 8 GB | Fastest, lightest, weaker reasoning |
67+
68+
### How to Download
69+
70+
1. Open **MLX Code**
71+
2. Click the **Settings** icon (gear) in the toolbar
72+
3. Go to the **Models** tab
73+
4. Find the model you want and click **Download**
74+
5. Wait for the download to complete — progress is shown inline
75+
76+
Models are downloaded from [Hugging Face mlx-community](https://huggingface.co/mlx-community) using the native Hub API. No browser or terminal needed.
77+
78+
### Custom Models
79+
80+
To add any model from mlx-community:
81+
82+
1. Settings → Models → **Add Custom Model**
83+
2. Enter the Hugging Face repo ID, e.g. `mlx-community/Qwen2.5-Coder-7B-Instruct-4bit`
84+
3. Click Download
85+
86+
### Change the Models Directory
87+
88+
By default models are saved to `~/Documents/MLXCode/models`. To use a different location:
89+
90+
1. Settings → **General**
91+
2. Change **Models Path** to your preferred directory
92+
3. Move any existing models to the new path
93+
94+
---
95+
96+
## 4. Load a Model and Start Chatting
97+
98+
1. Open **MLX Code**
99+
2. In the sidebar or toolbar, open the **model picker**
100+
3. Select the model you downloaded
101+
4. Click **Load Model** — first load takes 10–30 seconds as weights are loaded into GPU memory
102+
5. The status bar shows **Model loaded: [name]** when ready
103+
6. Type a message and press **Return** or click Send
104+
105+
### Tips
106+
107+
- **First message is slow** — the model warms up on the first inference. Subsequent messages are faster.
108+
- **Context window** — the model remembers everything in the current conversation up to its context limit (shown in the status bar). Start a new conversation with **Cmd+N** to clear context.
109+
- **Stop generation** — press the Stop button in the toolbar to interrupt a response mid-stream.
110+
- **Regenerate** — click the regenerate button on any assistant message to try again.
111+
112+
---
113+
114+
## 5. Enable the Xcode Extension
115+
116+
The Xcode Source Editor Extension lets you invoke MLX Code commands directly from the **Editor** menu inside Xcode without leaving your code.
117+
118+
### Step 1 — Open MLX Code at least once
119+
120+
The extension will not appear in System Settings until the parent app (MLX Code) has been launched at least once.
121+
122+
### Step 2 — Enable in System Settings
123+
124+
1. Open **System Settings**
125+
2. Go to **Privacy & Security**
126+
3. Scroll down and click **Extensions**
127+
4. Click **Xcode Source Editor**
128+
5. Check the box next to **MLX Code**
129+
130+
> If **MLX Code** does not appear in the list, make sure the app is in `/Applications` (not just your Downloads folder or Desktop) and has been launched at least once.
131+
132+
### Step 3 — Restart Xcode
133+
134+
Quit Xcode completely and reopen it. The extension loads at startup.
135+
136+
### Verify It's Working
137+
138+
Open any Swift file in Xcode. Click the **Editor** menu at the top of the screen. You should see a **MLX Code** submenu with 5 commands.
139+
140+
---
141+
142+
## 6. Using the Xcode Extension
143+
144+
### The 5 Commands
145+
146+
| Command | What it does |
147+
|---------|-------------|
148+
| **Explain Selection** | Explains what the selected code does in plain English |
149+
| **Refactor Selection** | Rewrites the selected code for clarity and performance |
150+
| **Generate Tests** | Writes XCTest unit tests for the selected code |
151+
| **Fix Issues** | Finds and fixes bugs in the selected code |
152+
| **Ask MLX Code** | Opens MLX Code with the selected code pre-loaded — you type the question |
153+
154+
### How to Use
155+
156+
1. Select code in Xcode (one line, a function, or an entire file)
157+
2. Click **Editor** in the menu bar → **MLX Code** → choose a command
158+
3. **MLX Code** opens (or comes to the foreground) with the code already loaded
159+
4. The model processes the request — for "Ask MLX Code", type your question first
160+
161+
### What Gets Sent
162+
163+
- The **selected text** (or the full file if nothing is selected)
164+
- The **file type** (Swift, Objective-C, Python, etc.) for syntax-aware responses
165+
- Nothing is sent to any server — everything stays on your Mac
166+
167+
### Keyboard Shortcut (Optional)
168+
169+
You can assign a keyboard shortcut to any extension command in **System Settings → Keyboard → Keyboard Shortcuts → App Shortcuts**.
170+
171+
---
172+
173+
## 7. Set a Project Directory
174+
175+
MLX Code works better when it knows where your project lives. With a project directory set, it can:
176+
- Read files directly when you ask about them
177+
- Run builds, tests, and git commands in the right context
178+
- Include relevant file context automatically
179+
180+
### How to Set
181+
182+
1. Settings → **General**
183+
2. Set **Working Directory** to your project folder (e.g. `/Users/you/Developer/MyApp`)
184+
3. Optionally set **Xcode Project** to your `.xcodeproj` or `.xcworkspace` file
185+
186+
### Or, Tell the Chat
187+
188+
You can also just say: `"Set working directory to ~/Developer/MyApp"` and the assistant will configure it.
189+
190+
---
191+
192+
## 8. Build from Source
193+
194+
### Requirements
195+
196+
- Xcode 15.0 or later
197+
- macOS 14.0 SDK
198+
199+
### Steps
200+
201+
```bash
202+
# Clone the repo
203+
git clone https://github.com/kochj23/MLXCode.git
204+
cd MLXCode
205+
206+
# Open in Xcode
207+
open "MLX Code.xcodeproj"
208+
```
209+
210+
In Xcode:
211+
212+
1. Select the **MLX Code** scheme in the toolbar
213+
2. Set destination to **My Mac**
214+
3. Press **Cmd+R** to build and run
215+
216+
Swift Package Manager will automatically resolve and download:
217+
- `mlx-swift` — Apple's MLX tensor library for Swift
218+
- `mlx-swift-lm` — LLM loading and inference
219+
- `swift-transformers` — tokenizer support
220+
- `swift-collections` — collection utilities
221+
222+
> First build takes several minutes while Xcode compiles mlx-swift's Metal shaders.
223+
224+
### Building the Xcode Extension
225+
226+
The extension is a separate target. To build it:
227+
228+
1. Select the **MLX Code Extension** scheme
229+
2. Press **Cmd+B**
230+
231+
To use it locally, build and run the main **MLX Code** target first (this installs both the app and embedded extension), then enable it in System Settings as described in [Section 5](#5-enable-the-xcode-extension).
232+
233+
---
234+
235+
## 9. Troubleshooting
236+
237+
### App won't open — "unidentified developer"
238+
239+
Go to **System Settings → Privacy & Security** → scroll to the blocked app → click **Open Anyway**.
240+
241+
### Model download fails
242+
243+
- Check you have enough free disk space (models are 2–8 GB each)
244+
- Check your internet connection
245+
- The models directory must be writable — go to Settings → General and verify the **Models Path** exists
246+
247+
### Model loads but responses are very slow
248+
249+
- Ensure you're on Apple Silicon (M1/M2/M3/M4), not Intel — MLX only accelerates on Apple Silicon
250+
- Close other GPU-intensive apps (games, video editors)
251+
- Try a smaller model (Phi-3.5 Mini at ~2 GB is the fastest option)
252+
253+
### Xcode extension not appearing in System Settings
254+
255+
1. Make sure MLX Code is in `/Applications` — not in Downloads or on the Desktop
256+
2. Launch MLX Code at least once
257+
3. Wait 30 seconds, then check System Settings again
258+
4. If still missing: quit Xcode, open Terminal, run `pluginkit -e use -i com.local.mlxcode.xcodeeditor`, relaunch Xcode
259+
260+
### Xcode extension appears but commands do nothing
261+
262+
- Make sure a model is loaded in MLX Code before invoking an extension command
263+
- Check that the App Group entitlement is granted — both the main app and extension must share `group.com.jkoch.mlxcode`
264+
265+
### Tool calls not executing
266+
267+
- Tool mode must be enabled (Settings → Tools → Enable Tools)
268+
- Ensure a project directory is set — some tools (Xcode build, git) require it
269+
- If a tool call keeps failing, the model may be producing malformed JSON — MLX Code will retry automatically up to 2 times, then report the error
270+
271+
### Conversations not saving
272+
273+
Check that `~/Library/Application Support/MLX Code/Conversations/` exists and is writable.
274+
275+
---
276+
277+
## Storage Locations
278+
279+
| Item | Location |
280+
|------|----------|
281+
| Models | `~/Documents/MLXCode/models/` (default, configurable) |
282+
| Conversations | `~/Library/Application Support/MLX Code/Conversations/` |
283+
| User memories | `~/.mlxcode/memories.json` |
284+
| App Group container | `~/Library/Group Containers/group.com.jkoch.mlxcode/` |
285+
| Logs | `~/Library/Logs/MLX Code/` |
286+
287+
---
288+
289+
*MLX Code — Copyright 2026 Jordan Koch. MIT License.*

‎README.md‎

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -116,20 +116,16 @@ Models download automatically on first use. You can also add custom models from
116116

117117
## Installation
118118

119-
### From DMG
119+
See **[INSTALLATION.md](INSTALLATION.md)** for the full setup guide, including model downloads, enabling the Xcode extension, and troubleshooting.
120120

121-
Download the latest release from [Releases](https://github.com/kochj23/MLXCode/releases), open the DMG, and drag to Applications.
121+
### Quick Start
122122

123-
### From Source
123+
1. Download `MLXCode-vX.Y.Z.dmg` from [Releases](https://github.com/kochj23/MLXCode/releases)
124+
2. Drag **MLX Code** to `/Applications`
125+
3. Launch the app → Settings → Models → download a model
126+
4. Load the model and start chatting
124127

125-
```bash
126-
git clone https://github.com/kochj23/MLXCode.git
127-
cd MLXCode
128-
open "MLX Code.xcodeproj"
129-
# Build and run (Cmd+R)
130-
```
131-
132-
No Python setup required. MLX Code is fully self-contained.
128+
No Python required. MLX Code is fully self-contained.
133129

134130
---
135131

0 commit comments

Comments
 (0)