Quaker

Quaker is a macOS maintenance CLI that remembers what it did, respects your rules, and keeps automation suggest-only unless you explicitly apply a cleanup.

It is built for people who want local cleanup and diagnostics to feel inspectable: every useful run can leave a memory entry, protected paths stay protected across commands, profiles make repeatable maintenance boring, and scheduled jobs report before they remove.

Why Quaker

• Dry-run first: cleanup-style commands preview by default.
• Local memory: command history is stored under ~/.quaker/memory.jsonl.
• Rules before removal: protected paths are checked centrally before deletion is attempted.
• Profiles: save a useful run and repeat it later.
• Suggest-only schedules: launchd schedules run profiles with --dry-run.
• Hooks: attach local scripts to allowlisted lifecycle events.
• Scriptable output: JSON is available for status, analyze, and cleanup-style flows.

Install

From a checked-out source tree:

./install-quaker.sh

Default install layout:

~/.local/bin/qk
~/.local/bin/quaker
~/.local/share/quaker/
~/.quaker/

Build manually:

make build
./qk --version

If Go is missing on macOS:

brew install go@1.25

First Run

qk doctor
qk clean --dry-run
qk status --json

doctor gives a quick local health summary and starts the memory trail. Cleanup commands show what would be removed unless you pass --apply.

Command Map

Core maintenance:

qk clean [--dry-run|--apply]
qk installer [--dry-run|--apply]
qk purge [path] [--dry-run|--apply]
qk uninstall --list
qk uninstall [--dry-run|--apply] "App Name"
qk optimize [--dry-run|--apply]
qk analyze [--json] [path]
qk status [--json]
qk touchid status
qk completion <bash|zsh|fish>
qk update

Memory:

qk memory list
qk memory show <id>
qk memory export --format json
qk memory forget <id>
qk memory forget --before YYYY-MM-DD

Rules:

qk rules add protect ~/Projects/client-work
qk rules add ignore noisy-cache
qk rules list
qk rules check ~/Projects/client-work/cache/file.tmp
qk rules remove <rule-id>

Profiles:

qk clean --dry-run
qk profile create weekly-safe --from-last-run
qk profile list
qk profile run weekly-safe --dry-run

Automation:

qk schedule add weekly-scan --profile weekly-safe
qk schedule list
qk schedule remove weekly-scan-weekly-safe

Hooks:

qk hooks install after-doctor ./scripts/after-doctor.sh
qk hooks list

Accepted hook event names are before-clean, after-clean, after-uninstall, after-scan, and after-doctor. Hook scripts must be executable. They receive a small JSON payload on stdin and are time-limited. The current CLI emits after-doctor; the other event names are reserved for cleanup flows as they are wired in.

State Files

Quaker keeps local state in ~/.quaker/:

memory.jsonl       command memory
rules.json         protected paths and ignored suggestions
profiles.json      saved command profiles
hooks/             event hook symlinks
schedules/         generated schedule plists

No cloud account or remote service is required.

Safety Model

Quaker is a local maintenance tool, so its sharp edge is filesystem mutation. The current safety posture is:

• cleanup commands default to --dry-run
• scheduled jobs are generated with --dry-run
• protected rules override cleanup candidates before removal
• unsafe root paths are refused
• launchd profile names are constrained before plist generation
• hook events are allowlisted and hook scripts must be executable
• Touch ID sudo commands are guidance-only for now

Use --apply only after reviewing the dry-run output.

Development

Run the standard checks:

bash -n qk quaker scripts/check.sh install-quaker.sh
go test ./...
./scripts/check.sh

Build:

make build

The repo includes a project-local test-qk skill under .codex/ for private pre-push validation. It is intentionally not tracked.

Security

Please review SECURITY.md and SECURITY_AUDIT.md before changing cleanup, uninstall, hook, schedule, installer, or privilege-related code.

License

Quaker CLI is distributed under the MIT License.