darkmux_

Why darkmux exists

You don't have to rent every token — the AI workforce is already sitting in your Mac.

darkmux started as a lab for testing faster local AI on Apple Silicon. The belief that came out of it: a frontier model is a brilliant strategist you rent by the token. Burning those tokens on compaction, scaffolding, test runs, and structuring is paying rent for busy work, plus handing your data to someone else's cloud to do it. The Apple Silicon you already bought runs capable open-source models locally — no cloud account, no per-token meter, nothing leaving your disk. Many Mac owners don't make full use of the hardware they paid for; darkmux gives you the tools to use that silicon.

Every default in darkmux comes from a measured result, not a guess. The repo is the evidence locker; the writing is the narrative.

On-demand crews, not a pyramid

An AI workforce, not a bureaucracy of bots.

The obvious way to build a multi-agent tool was to copy the company: a boss model delegating to manager models delegating to workers, a pyramid of cloud agents renting tokens to talk to each other. But the org chart exists to route around human limits (span of control, careers, reporting lines), and none of those bind a model that spins up for one job and vanishes. So darkmux has no pyramid. One principal, you, leverages an orchestration harness (e.g. Claude Code) that assembles crews on demand for the mission and dissolves them when the work is done. The capable model shapes the work, the local crew does it, you decide what runs.

Swap the loadout

The right loaded model, context length, and compaction profile for each task: named, not remembered.

You shouldn't have to remember whether your fast bounded-task stack is loaded right now, or whether the deep-agentic profile got swapped out an hour ago when you ran a different test. darkmux makes the loadout an explicit, named thing.

• darkmux profiles — list named stacks (combinations of LMStudio models at specified context lengths)
• darkmux status — show what's loaded and which profile (if any) it matches
• darkmux swap deep — atomically transition the LMStudio loadout to a named profile
• darkmux scan — discover models in your LMStudio catalog not yet covered by any profile

Watch it work

A daemon + viewer for live observability of dispatches, sprints, and verdicts.

darkmux serve runs a small HTTP daemon (default 127.0.0.1:8765) that exposes the flow records written by every dispatch and mission/sprint transition. The observability viewer renders those records as one drillable view of your fleet: drill fleet → machine → subsystem, with the event stream as a log lens at any level. A live demo with sample data runs on this site. Wall-clock arcs on dispatch records; model field tells you which LMStudio model ran the work.

• darkmux serve — start the daemon in a separate terminal tab
• darkmux doctor — pre-flight checks including daemon: reachable
• darkmux.com/demo/ — interactive demo, sample fleet data (no install required)
• darkmux crew dispatch / sprint review — emit flow records as they run

Full walkthrough in the observability section of the user guide.

The lab

A measurement harness, not a config tool dressed up as one.

Every darkmux lab run writes a manifest, a trajectory, and per-turn timing under .darkmux/runs/<id>/, so wall-clock variance, compaction events, and per-profile behavior are inspectable after the fact. Not in your head. On disk.

• lab run quick-q — single-turn smoke prompt against the active profile
• lab run long-agentic — the workload that exercises compaction
• lab inspect <run> — turns, compactions, mode (fast/slow), notes
• lab tune long-agentic --runs 6 — bimodal cluster detection across N dispatches
• lab compare <A> <B> — diff two runs for variance / regression

Workloads are pluggable via a WorkloadProvider trait. Two ship out of the box (prompt, coding-task); add your own without forking the repo. Full walkthrough in the lab section of the user guide.

Advanced: missions, sprints, crew

Structured agentic work, for operators using darkmux as the local-AI tier of an orchestrator workflow.

Beyond the swap/lab CLI surface, darkmux ships a crew abstraction: named local-AI roles (coder, code-reviewer, scribe) with declared tool palettes and system prompts, plus a mission/sprint lifecycle that tracks multi-step plans as JSON files the operator owns. Optional — none of this is required to use darkmux as a CLI.

• darkmux crew dispatch coder --message "..." — invoke a named role; emits flow records
• darkmux sprint review — QA pass against the current branch's diff; dispatches code-reviewer, parses the SIGNOFF block
• darkmux mission start/close/pause/resume + sprint start/complete/abandon — drive lifecycle state
• darkmux mission add-sprint --after <s> — insert scope mid-mission without restructuring

Full walkthrough in the missions section of the user guide.

Get going

Prefer source? cargo install --git https://github.com/kstrat2001/darkmux works too. Then edit ~/.darkmux/profiles.json to point at your downloaded LMStudio models. The getting-started page of the user guide walks through this end-to-end, including verifying with doctor and running your first swap.