# macOS Concierge

A harness-neutral Agent Plugin and terminal-agent workspace for inspecting and
operating the Mac itself.

The repository discovers the current machine instead of assuming hostnames,
Homebrew paths, or mounted disks. Its current portable skill provides a
read-only snapshot of macOS, Homebrew, disk usage, and volumes. When used as a
workspace, `AGENTS.md` also guides broader work with processes, launch agents,
package managers, disks, and similar system concerns.

## What this repository provides

This repository targets the
[Agent Plugins v1.0.0 specification](https://agent-plugins.org/specification).
The portable plugin consists of:

- `plugin.json` — the Agent Plugins manifest
- `skills/inspect-mac/` — an
  [Agent Skill](https://agentskills.io/specification) for read-only discovery

Agent Plugins v1 standardizes skills and MCP servers in fixed locations. This
plugin does not currently ship an `mcp.json` file or any MCP servers.

The repository also contains `AGENTS.md`. It provides workspace-level policy
for clients that support the `AGENTS.md` convention, including confirmation
requirements for privileged or destructive operations. `AGENTS.md` is not a
portable component of the Agent Plugins v1 specification and is not guaranteed
to load when a client installs only the plugin.

## Use the complete workspace

Clone the repository into your home directory and work from its root:

```sh
cd ~
git clone https://github.com/mvellandi/mac-concierge.git
cd mac-concierge
```

For the complete experience, keep the checkout as the agent's working
directory. A client that supports the `AGENTS.md` convention can then read the
workspace policy; if it supports Agent Plugins, install or enable this
repository using that client's normal workflow. Installation, enablement,
permissions, and skill activation are client-specific.

Ask the agent to inspect this Mac. A compatible plugin client can discover the
`inspect-mac` skill, which runs a read-only snapshot and summarizes the
computer name, OS, Homebrew installation, disk usage, and volumes.

## Pi

Pi supports the Agent Skills standard and its own Pi Package format. Its package
interface uses `package.json` metadata or conventional resource directories;
it does not document `plugin.json` as a Pi Package manifest.

After cloning the repository, run this from the repository root:

```sh
pi install .
pi
```

`pi install .` registers the existing checkout as a local Pi package and
discovers `skills/` by convention. Starting Pi from the repository root also
loads `AGENTS.md`, providing both the skill and the workspace policy. Keep the
checkout at the same path because Pi uses a local package directly rather than
copying it.

If Pi is already running from this directory when you install the package, run
`/reload` to reload packages, skills, and context files.

## Safety and privacy

The inspection script is read-only unless explicitly given `--write-cache`.
The workspace policy requires confirmation before sudo, software installation
or removal, file deletion or movement, permission or system-configuration
changes, killing processes, and network or remote changes.

Inspection output can contain identifying or sensitive machine details,
including computer and local host names, volume names, disk identifiers,
partition layouts, and storage usage. Review and redact the output before
posting it publicly or including it in a support report.

## Layout

```text
mac-concierge/                  # plugin root and workspace
├── AGENTS.md                   # non-portable workspace policy
├── LICENSE
├── plugin.json                 # Agent Plugins 1.0.0 manifest
└── skills/
    └── inspect-mac/
        ├── SKILL.md
        └── scripts/
            └── inspect.sh
```

## Local snapshot

With confirmation, `inspect.sh --write-cache` can save a local machine hint at:

```text
$XDG_CONFIG_HOME/mac-concierge/machine.md
```

If `XDG_CONFIG_HOME` is unset, it falls back to:

```text
~/.config/mac-concierge/machine.md
```

The snapshot is not source of truth. Do not commit it, publish it, or copy it
to another Mac as shared configuration. Rediscover the current state before
copying, unmounting, formatting, or making other system changes.

## License

MIT