Personal Development Environment

This repository contains the configuration files, automation scripts, and environment setups for my personal development machine.

It also embeds several Git submodules: agent-harness/, background-run/, docker/sandbox/, and models/.

Structure

• agent-harness/ (submodule): Canonical definitions for the AI agent harness — agents, commands, skills (.opencode/), runtime config (opencode.jsonc, tui.jsonc), build/sync scripts in bin/, and MCP gateway profiles in profiles/. The workspace-local copies .opencode/, opencode.jsonc, and tui.jsonc at the repository root are synchronized from this submodule via bin/harness-sync.sh (state tracked in .harness-sync).
• .sandbox/: Nono sandbox profile for running AI agents in the current repository. Contains start.sh (entry point), profile.template.json, optional defaults (defaults.sh), and hooks/ for pre/post-execution steps.
• dotfiles/: Standard configuration files for bash (.bash_profile, .bashrc, .bash_prompt), environment variables (.exports, .path, .aliases), git (.gitconfig, .gitconfig-work, .gitconfig-private, .gitconfig-agents, .gitignore), vim (.vimrc), tig (.tigrc), editorconfig (.editorconfig), and environment template (.env.example). Symlink those files to the user directory.
• ssh/: SSH configuration files (config, allowed_signers). Symlink to ~/.ssh/.
• macos/: macOS-specific setup and automation.
  • init.sh: Initial macOS system configuration script.
  • bin/: Build scripts for various tools.
    • cherri/: Builds Cherri CLI compiler (Go) for macOS Shortcuts.
  • brew/: Contains the Brewfile to install all necessary packages, casks, and Mac App Store apps (via mas). Use it with brew bundle.
  • terminal/: Contains macOS Terminal profile configurations (e.g., mk.terminal).
  • automation/
    • shortcuts/: macOS Shortcuts written in Cherri. Contains the source .cherri files (plus shared lib/). Use the cherri compiler to create the corresponding .shortcuts.
• opencode/: Configuration for OpenCode.
  • Includes custom providers setup (Google Gemini & local Ollama models).
  • Configures custom agents and permissions (agents/).
  • Configuration files (opencode.jsonc, dcp.jsonc, tui.json).
  • Custom commands (command/ - e.g., tokenscope.md).
  • The opencode/ directory is symlinked to ~/.config/opencode/ for global config, while .opencode/ serves as the project-local config directory (synced from agent-harness/).
• omlx/: OMLX configuration for running OpenMoE LLM models. Contains settings.json with server, model, memory, cache, and sampling parameters. Symlink to ~/.omlx/.
• mtplx/: MTPLX model serving configuration. Contains serve.sh for running MTPLX-optimized models (e.g., Qwen3.6-27B) with custom context and caching settings.
• mlx-lm/: MLX-LM model serving. Contains serve.sh for running an MLX-LM server with a local 4-bit model.
• llama.cpp/: Local LLM inference server setup using llama.cpp.
  • build.sh: Clones and builds llama.cpp with Metal acceleration, native optimizations, and LTO.
  • serve.sh: Starts the llama-server with GPU offloading, flash attention, and Jinja templating support.
• models/ (submodule): Model presets and Modelfiles for llama.cpp and ollama.
• llama-benchy/: Local LLM benchmark results (raw CSV/JSON), organized by date.
• manifest/: Manifest tool setup and starter/stopper.
  • setup.sh: Clones the manifest repository to ~/repos/manifest.
  • start.sh: Starts the Manifest docker environment using nerdctl compose.
  • stop.sh: Stops the Manifest docker environment.
  • backup.sh: Dumps the Manifest Postgres database to manifest/backup/.
• colima/: Configurations for Colima profiles (Docker, Containerd).
• direnv/: Configuration for direnv (direnv.toml).
• docker/sandbox/ (submodule): Sandbox definitions used by the containerized MCP gateway.
• background-run/ (submodule): backgrounded — a lightweight bash background service runner (start/stop/list/status via PID files).
• claude/: Configuration for the Claude Code CLI (e.g., code/statusline-command.sh).
• claude-copilot-proxy/: Proxy setup for using GitHub Copilot models with Claude-compatible clients (start.sh).
• lazydocker/: Configuration for lazydocker (config.yml).
• research/: Durable research artifacts written by the Librarian agent (research/results/).
• plans/: Plan documents, named YYYY-MM-DD_[Feature-Name].md. The active plan is tracked as PLAN.md at the repository root; finished plans are archived here.
• AGENTS.md: The agent harness protocol — role definitions (Orchestrator, Planner, Builder, reviewers, …) and workflow rules for AI-assisted development in this repository.

Setup Instructions

First setup

Execute macos/init.sh once to setup your mac.

Homebrew

To install all required system packages, CLI tools, and applications:

cd macos/brew
brew bundle

BREW_PREFIX=$(brew --prefix)
ln -s "${BREW_PREFIX}/bin/gsha256sum" "${BREW_PREFIX}/bin/sha256sum"

# Install brews installed bash as shell for current user
if ! fgrep -q "${BREW_PREFIX}/bin/bash" /etc/shells; then
  echo "${BREW_PREFIX}/bin/bash" | sudo tee -a /etc/shells;
  chsh -s "${BREW_PREFIX}/bin/bash";
fi;

# Add bash completion directory
mkdir -p ~/.config/bash_completion.d

# Start automatic updates every 12 hours, immediatelly and on system boot if on AC power.
# Passes --sudo as well to enable upgrading casks. The updater may ask for a password.
brew autoupdate start 43200 --immediate --upgrade --cleanup --ac-only --sudo

docker-buildx

The docker-buildx plugin is installed to enable extended build capabilities with BuildKit.

You have to add the following to your ~/.docker/config.json:

  "cliPluginsExtraDirs": [
      "/opt/homebrew/lib/docker/cli-plugins"
  ]

Dotfiles

Symlink the dotfiles to your home directory:

find "$(pwd)/dotfiles" -maxdepth 1 -name ".*" -exec ln -sf {} "$HOME" \;
ln -s $(pwd)/direnv ~/.config/
mkdir ~/.ssh
ln -s $(pwd)/ssh/config ~/.ssh/
ln -s $(pwd)/ssh/allowed_signers ~/.ssh/
ln -s $(pwd)/omlx/settings.json ~/.omlx/
ln -s $(pwd)/dotfiles/.startup.d ~/.startup.d

~/.startup executes the executable *.sh steps in ~/.startup.d/ in filename order. Use numeric prefixes when adding or reordering startup tasks.

OpenCode (AI Agent harness)

Symlink the opencode directory to the global configs:

ln -s $(pwd)/opencode ~/.config/opencode

Ensure your API keys (e.g., for Google Gemini) are securely configured in your local environment, as they are excluded from this repository.

The agent harness itself lives in the agent-harness/ submodule. Its agents, commands, skills, and runtime config are synchronized into this repository (.opencode/, opencode.jsonc, tui.jsonc) using agent-harness/bin/harness-sync.sh. The MCP web tool is configured as a remote endpoint (see opencode.jsonc).

Sandboxed execution

Run OpenCode in the current repository's sandbox with:

./run_harness.sh [OPENCODE_ARGS...]

For example:

./run_harness.sh
./run_harness.sh --help

run_harness.sh launches opencode through nono (via .sandbox/start.sh), providing a sandboxed OpenCode execution. It uses the Git root as the workspace (or the current directory outside a Git repository) and loads its sandbox command and default arguments from .sandbox/defaults.sh. That file is generated by nono-here.sh during provisioning (a template-provided one is preserved untouched); without it, run_harness.sh exits with an error. The sandbox profile is rendered from .sandbox/profile.template.json, and nono must be installed separately.

macOS Shortcuts

The macos/automation/shortcuts/ directory contains .cherri source code files that can be compiled and then imported into the macOS Shortcuts app. These are useful for context switching and automating your workflow. Shared helpers live in macos/automation/shortcuts/lib/.

Available Shortcuts:

• mail-start / mail-stop: Opens/hides communication applications (Microsoft Teams and Outlook).
• meeting-start / meeting-stop: Prepares the system for a meeting (hides unrelated apps, focuses Microsoft Teams).
• private-start / private-stop: Prepares the system for private time (hides work apps, opens Steam).
• env-open / env-close: Opens/closes the development environment (terminal, editor, services).
• text-transform: Text transformation helper.

These shortcuts are written in Cherri (*.cherri). You need to compile them using the Cherri CLI to generate .shortcut files, which can than be imported.

Compile and import all shortcuts (opens the Shortcuts app with multiple acknowledgement dialogs):

find macos/automation/shortcuts -name '*-*.cherri' -exec echo {} ';' -exec cherri {} --open ';'

How to retrieve Bundle ID of an app?

osascript -e 'id of app "APPNAME"'

Git Configuration

This repository includes custom git configurations (.gitconfig):

• User name and email, separate for work and private projects
• Git GPG signing enabled, using SSH for signing
• Autocorrect for mistyped commands
• File system monitor for faster status checks
• Default branch set to main
• Merge tool configured for opendiff
• Automatic pushing of relevant annotated tags

Ollama (local LLMs)

Brew starts the local Ollama service. You can pull required models, e.g. those configured in opencode.jsonc by calling ollama run <model>.

Or build the models from a Modelfile:

ollama create tiny -f ollama/models/Modelfile.tiny

OMLX (LLM Inference)

OMLX is an inference server for running LLM models on metal hardware locally.

Symlink the configuration to your home directory:

ln -s $(pwd)/omlx/settings.json ~/.omlx/

The configuration includes server settings, model directories, memory management, SSD caching, and sampling parameters.

MTPLX (Model Serving)

MTPLX provides optimized model serving for large language models (e.g., Qwen3.6-27B).

To start the MTPLX server:

mtplx/serve.sh

MLX-LM (Model Serving)

MLX-LM provides model serving on Apple silicon using the MLX framework.

To start the server:

mlx-lm/serve.sh

llama.cpp (Local LLM Inference)

llama.cpp provides local LLM inference with GPU acceleration (Metal on macOS).

To build llama.cpp from source:

bash llama.cpp/build.sh

To start the inference server:

bash llama.cpp/serve.sh

Manifest

Manifest provides local repo updater and starter/stopper for Docker compose.

To setup Manifest:

bash manifest/setup.sh

To start the Manifest environment:

bash manifest/start.sh

To stop the Manifest environment:

bash manifest/stop.sh

To dump the Manifest Postgres database (into manifest/backup/):

bash manifest/backup.sh

Ensure to create and edit ~/repos/manifest/docker/.env before running.

macOS Build Tools

The macos/bin/ directory contains build scripts for various tools:

• Cherri: CLI compiler for macOS Shortcuts

  bash macos/bin/cherri/build.sh

All tools are built from source and installed to ~/repos/.

Colima

Provides container environment for docker and nerdctl.

Configures the following virtual machines (profiles):

• docker: Machine for docker environment, accessible through docker, runs with apples vz virtualization framework for best performance, in theory, but file system failures in practice.
• docker-qemu: Machine for docker environment, accessible through docker, runs with qemu virtualization framework and sshfs for better stability, but worse performance.
• containerd: Bare containers, accessible through nerdctl

No VM is started by default. Start a profile with colima start <profile>.

Perform the following for installation:

ln -s $(pwd)/colima ~/.colima

colima completion bash > ~/.config/bash_completion.d/colima
colima -p containerd nerdctl install

lazydocker

For monitoring the docker environment, one can use lazydocker, which is running via docker in docker. Execute the lazydocker alias. The local configuration lives in lazydocker/config.yml.

If you're on an ARM device (which you probably are with Apple silicon), you need to build the image yourself. See the full instructions here:

docker build -t lazyteam/lazydocker \
  --build-arg BASE_IMAGE_BUILDER=arm64v8/golang \
  --build-arg GOARCH=arm64 \
  https://github.com/jesseduffield/lazydocker.git

Things others would have to adjust

• Full path containing my username mkuckert, e.g. in mtplx/serve.sh, llama.cpp/serve.sh, mlx-lm/serve.sh, omlx/settings.json, .sandbox/profile.template.json
• The dotfiles/.gitconfig* files (in particular .gitconfig-work)
• The ssh/* config files
• The environment paths in macos/automation/shortcuts/env-*.cherri

Source

Most is my own work.

Some of the dotfiles are inspired from Mathias Bynens but heavily modified to match my preferences.