Imported from y3owk1n/mimi (
AGENTS.md). Install upstream withnpx skills add y3owk1n/mimi. Copyright stays with the author.
AGENTS.md — mimi Agent Guide
This file is the shared source of truth for any AI agent working on this repo (Claude Code, Codex, Copilot, Cursor, etc.). CLAUDE.md is a symlink to this file — edit here, never the symlink. Personal overrides go in gitignored AGENTS.local.md / CLAUDE.local.md.
mimi is a macOS window and space utility written in Go, with native bridges into Accessibility, CGEvent, and private SkyLight APIs via CGO/Objective-C. It ships a CLI (mimi action …) and a hook daemon that fires shell hooks on app, window, and space events. macOS only — there is no cross-platform story.
Shape
Three execution paths: a direct CLI action, the same action routed over the daemon's Unix socket when it is running, and the hook daemon itself. The CLI silently falls back to direct execution when the socket at settings.socket_file is unavailable — a behaviour difference worth remembering when a bug reproduces one way and not the other. docs/ARCHITECTURE.md has the full picture.
Space switching and window-to-space moves ride undocumented private APIs and synthetic dock swipes. They are timing-sensitive and may break on macOS updates; treat changes there as user-visible even when the Go surface is unchanged.
Commands
just is the build system; devbox shell provisions the toolchain.
just build # build bin/mimi
just fmt # format Go (golangci-lint) + Objective-C (clang-format)
just lint # golangci-lint run
just vet # go vet, untagged and integration builds
just test # unit + integration, one pass, each test once
just test-unit # unit tier only
just bundle # build build/Mimi.app
just genman # generate man pages
Pre-commit gate: just fmt && just lint && just test && just build. CI runs just lint, just fmt-check, just vet, just build, and just test-all on macOS.
Conventions
- All Objective-C and CGO lives in
internal/native/,internal/systray/, andinternal/permissions/. Go packages elsewhere must not open CGO of their own. - Errors go through
derrors(internal/errors) with a code —derrors.New(derrors.CodeInvalidInput, …)/derrors.Wrapf(err, …). Never return a bareerrors.Newacross a package boundary. - Logging is
*zap.SugaredLogger; constructors tolerate anillogger by falling back tozap.NewNop(). Never log window titles, hook command contents, or other user payloads — log counts, IDs, durations, booleans. just fmt-checkgates Objective-C formatting separately from Go. Both must pass.- Tabs for indentation, LF endings, final newline (
.editorconfig). - Conventional commits;
release-please-config.jsondecides which types reach the changelog. The repo squash-merges with the PR title as the commit subject, so the title is the line that ships.
Full detail: docs/CODING_STANDARDS.md, plus docs/go/CONVENTIONS.md, docs/go/OBJECTIVE_C.md, and docs/testing/TESTING_PATTERNS.md.
Agent Resources
.agents/skills/is the canonical home for project skills (create-pr,file-issue);.claude/skillsis a directory symlink to it — never add skill bodies there. Each skill may carry anagents/openai.yamloverlay for Codex..claude/settings.jsonwires a non-blocking format-on-edit hook (.claude/hooks/format-on-edit.sh)..cursor/rules/mimi.mdccarries the same hard rules for Cursor..claude/worktrees/is gitignored; the rest of.claude/is tracked.
Documentation
Start here, then navigate: docs/ARCHITECTURE.md (shape) · docs/DEVELOPMENT.md · docs/CLI.md · docs/CONFIGURATION.md · docs/TROUBLESHOOTING.md · docs/INSTALLATION.md. Docs drift in places; when they disagree with code, read the code.
Keep this file lean — it loads into every agent session. Add only contracts an agent cannot infer from the code; workflow depth goes in a skill.
