Build on it

The reason this is MIT and not a download is that most of what is in here is plumbing, and plumbing is the part nobody wants to write twice. If you are building a Mac agent, the four modules below are usable without the app around them.

Rendered unchanged from the Grux README at commit 86963f2, fetched 2026-11-01. If this page and the repository disagree, the repository is right.

The pieces. GruxShellCore is a PTY, the safety gates and the snapshot store. GruxAgentCore is orchestration. GruxSetupCore is the capability and permission model. GruxMCPCore is the read only MCP server. None of the four imports AppKit or SwiftUI, so they build and test without the UI stack, and all four are .library products in Grux-Mac/Package.swift. You can depend on one without taking the other three or the app.

To add a tool, which is the most common thing anyone will want. Tools are declared in ChatService.allTools() in Grux-Mac/Sources/Grux/ChatService.swift and handled in the switch further down the same file. Copy add_task: the declaration is at the top of allTools() and its handler is the first case. Two edits, same file, and the model can call it. ToolCatalogueTests pins the count at 116, so adding one turns the suite red until you move the pin on purpose.

To add a surface, meaning a place to open with its own screen. Add a FeatureRow to FeatureRegistry.rows in Grux-Mac/Sources/Grux/Onboarding/FeatureRegistry.swift, naming what it requires and what is merely optional. The setup dot, the setup sheet, the permission table in this README and the BETA badge are all read from that one entry, so getting the row right is the whole job.

What you must not break. Four guards, and each one exists because the thing it catches already happened here:

cd Grux-Mac
swift test                          # 4902 tests
python3 scripts/check-contract.py   # the setup contract is frozen

The setup contract will not let a capability change meaning without a dated amendment in Grux-Mac/docs/. PermissionTableTests fails if the permission table above stops matching the registry. NoPersonalIdentityTests fails on a personal name anywhere in the shipping tree. The dash guard fails on an em dash or en dash, comments included. Several of them plant the fault they detect and assert they catch it, because a guard that cannot fail is not a guard.

What is unfinished, and where contributions help most. Stated plainly, because it matters if you are deciding whether to contribute:

• A second model backend. Chat talks to Anthropic or to Ollama. The seam is real but it has only ever had two implementations, so it is shaped by both of them rather than by the general case. A third would tell you where it is wrong.
• The MCP server is read only. Writes go over a Unix socket instead. Making it a full bidirectional surface is a contained piece of work and it would let any agent drive the whole app.
• The 12 features behind the Labs door. Every one of them is real and none of them is finished. Agents and Self-Upgrade are the two with the most left in them.
• Nothing here runs on an Intel Mac. One arm64 slice, and no reason beyond nobody having needed it.

If you build something on Grux, open an issue and tell us. We want to know.

On this site

Grux AI is a Mac app you can customize with Claude Code, or any coding agent: the whole tree is MIT licensed, npx @dotcomjack/grux puts the command line and its MCP bridge in front of the agent already in your terminal, and Optimize Grux turns what you say you want different into a work order that agent builds. The walkthrough is How do I customize a Mac app with Claude Code?.

Related

• First run
• Permissions, and what each one buys
• The command line
• Privacy posture

Free, MIT licensed. macOS 14 or later, Apple silicon. 28.4 MB, signed and notarized by Apple. No account, no server, no subscription.