Documentation

Overview

your-local-agent puts a full AI coding assistant — model, inference engine, and agent loop — entirely on your Mac. One command to install. One command to start. Nothing leaves your machine. Ever.

Every AI assistant you've used lives somewhere else. Your prompts travel over the internet, get logged, filtered, and processed on hardware you'll never see. That's fine for most things.

But when you're debugging at 2am. Writing scripts you'd rather not explain. Asking the same question for the fifteenth time. Working offline. Asking about anything that would get you flagged on a cloud provider — you want it on your machine.

Requirements

Hard requirements

Software prerequisites

The setup script installs most things automatically, but these must exist first:

1. Xcode Command Line Tools — needed to build llama.cpp

copyxcode-select --install

If you see "command line tools are already installed", you're good.

2. Python 3 — used to parse models and state files

copypython3 --version

macOS ships with Python 3 since Monterey. If missing: brew install python3

3. curl — needed to fetch the setup script

copycurl --version

Comes pre-installed on macOS. If somehow missing: brew install curl

4. A supported shell — zsh or bash

copyecho $SHELL

Zsh is the default on macOS Catalina and later. Both are fully supported.

Install

One-liner (recommended)

Paste this in your terminal and press Enter:

copycurl -fsSL https://raw.githubusercontent.com/noelps-git/your-local-agent/main/setup.sh | bash

That's it. The script:

1. Detects your RAM, chip, and disk space
2. Installs Homebrew, llama.cpp, Node.js, and Aider (skips anything already installed)
3. Downloads the right AI model for your exact hardware
4. Configures everything and wires up your shell aliases
5. Runs a live test to confirm the agent is working

From source

copygit clone https://github.com/noelps-git/your-local-agent.git
cd your-local-agent
bash setup.sh

First launch

After setup finishes, restart your terminal, then:

copylocal-ai-start

Your local AI is now running. Open a project folder and start talking to it.

Commands

All commands are shell aliases installed into your ~/.zshrc (or ~/.bash_profile) by the setup script.

Models

Setup reads your RAM and picks automatically. No config files, no manual decisions.

You can override the auto-selection if you know what you're doing — it'll warn you, then let you proceed.

Use cases

Coding

• Reads your actual project files — not just what you paste in
• Writes, explains, refactors, and fixes bugs
• No token limit anxiety. No per-message cost.

Security research

• No content filters on exploit analysis, shellcode, payload breakdowns
• Nothing logged anywhere — your CTF notes stay yours
• Perfect for TryHackMe, HackTheBox, and offline lab environments
• Ask it to decode Burp output, analyse Nmap scans, write custom fuzzers

Learning

• Ask the same question ten ways at zero cost
• "Explain this Metasploit module. Now simpler. Now with an example."
• No judgment. No throttling. No "I can't help with that."

How it works

The stack is three components, all running locally:

Your Mac
│
├── llama-server          ← runs the AI model using your M-series GPU
│     └── Qwen3 (4B–32B)  ← automatically chosen for your RAM
│
└── Aider                 ← reads your files, talks to the model,
      └── your terminal     answers in your project context

No Docker. No Python environment hell. No .env file you'll accidentally push to GitHub.

Files on disk

~/models/
  └── Qwen3-*.gguf           the model (3–20 GB depending on RAM)

~/.local-ai/
  ├── setup.log              full timestamped log of every setup step
  ├── server.log             llama-server runtime output
  ├── state.json             what's installed (used by local-ai-update)
  └── bin/
      └── llama-server       the inference binary

~/.aider/
  └── config.json            Aider pointed at localhost:8080

Troubleshooting

Setup failed — where do I look?

copycat ~/.local-ai/setup.log

Every step is logged with a timestamp. Scroll to the last error.

command not found: local-ai-start

Your shell aliases weren't loaded yet. Run:

copysource ~/.zshrc   # or source ~/.bash_profile

Then try local-ai-start again.

xcode-select: error: command line tools are already installed

Not actually an error — this message means the tools are present. Setup will continue normally.

Homebrew install fails or hangs

If you're behind a corporate proxy or a VPN is active, Homebrew's CDN can be blocked. Try:

copy# Disable proxy temporarily
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

# Then re-run setup
bash setup.sh

Model download stops or times out

Downloads are resumable. Just re-run:

copybash setup.sh

Setup detects what's already done and skips it — only the download resumes.

llama-server: Bad CPU type in executable

You're on an Intel Mac. This build targets Apple Silicon only. Intel support is on the roadmap.

llama-server won't start / port 8080 in use

Something else is already using port 8080. Find and kill it:

copylsof -i :8080
kill -9 <PID>

Then run local-ai-start again.

Aider can't connect to the model

Check the server is actually running:

copylocal-ai-status
curl http://localhost:8080/health

If the server is down, start it: local-ai-start

permission denied running setup.sh

copychmod +x setup.sh
bash setup.sh

Out of disk space mid-download

copydf -h ~          # check how much free space you have
bash setup.sh    # resumes the download

Security

The setup script was written with the following in mind:

• Command injection via user input — sanitised to [a-zA-Z0-9-] only
• Unsafe rm — path-guarded to ~/models/* only, never outside
• eval of Homebrew path — validated against two known trusted paths
• Temp file race conditions — chmod 600 immediately on creation
• Downloaded script permissions — 750 for scripts, 640 for config
• set -euo pipefail — in every script, fails fast and loud
• No hardcoded secrets — anywhere

Updating

copylocal-ai-update

Pulls the latest scripts, updates llama.cpp and Aider, and checks whether a better model is available for your RAM. If one is, it asks before downloading and removes the old one after to free up space.

Roadmap

• Linux + NVIDIA CUDA support
• Intel Mac support
• Fish shell alias setup
• Open WebUI browser interface (chat UI on localhost:3000)
• Community benchmark table (model × chip × speed)

Contributing

Most useful PRs:

• New models in models.json — add an entry with the right fields
• Bug reports for specific macOS versions or RAM configs
• Roadmap items — Linux, Intel, Fish shell

Test on your own machine before submitting.

View repository on GitHub →