Get started
Install MACAW
Before you start
Press ⌘ Space, type Terminal, and press Return. Then check your versions: Node should be v18 or later. Missing Node? Get it from nodejs.org, or run brew install node.
node -vWhat to install
Where
Workspace
- Install
npm install -g macaw-ai &&macaw-ai install --coding-agents --system When it asks about a workspace, press Return. It prints a link and a code: open the link, sign in with Google or GitHub, and approve. You’re now the admin of a new workspace. A permission error? Put sudo in front of npm.
- Test it
macaw-sidecar--status The status runs one real decision through the control plane. Then use claude or codex as usual. Approve in the tray app or the console.
As a coding agent plugin (Claude Code or OpenAI Codex)
Add it in Claude Code
/plugin marketplace add macawsecurity/macaw-plugin/plugin install macaw-cc@macawAdd it in OpenAI Codex
codex plugin marketplace add macawsecurity/macaw-plugincodex plugin add macaw-cx@macaw- Observe
/macaw-cc:observe· in Codex, the macaw-observe skill- No account. Hooks record your sessions, prompts and tool calls to a local log in
~/.macaw/logs/, and it reports on them. It blocks nothing and can’t see model calls. - Protect
/macaw-cc:protect· in Codex, the macaw-protect skill- Installs the MACAW sidecar and creates your workspace with a sign-in link, or reuses the one you have. From then on every call is checked, and risky ones wait for your approval.
- MAPL
/macaw-cc:mapl· in Codex, the mapl skill- Describe a control in plain words, and it writes the MAPL policy, functions and approvals. More on the MAPL skill
Codex has no plugin slash commands: ask it to use a skill by name.
What gets installed
- Coding agents
- Sidecar and hooks for Claude Code and Codex. secCC and secCodex, which route model calls through MACAW too. The MACAW tray app (macOS and Windows).
- Client
- The Python client SDK, with an identity helper for your IdP’s users. SecureAI adapters: OpenAI, Anthropic, LangChain, LiteLLM, Pydantic AI, MCP, MCP proxy. Examples and demos, ready to run.
- Your workspace
- In the MACAW control plane: policies, approvals, the signed record, your team and API keys. Manage it in the console.
Platforms
| macOS | Linux | Windows | |
|---|---|---|---|
| Coding agents (sidecar) | Apple silicon | x64 | x64 |
| Client SDK (Python) | 3.12, 3.14 | 3.12, 3.14 | 3.14 |
| Tray app | Yes | No: approve in the console | Yes |
- Intel Macs and Linux on Arm are not supported yet.
- On macOS and Linux the coding-agent install needs python3 on your PATH.
- The console is on the web: any modern browser.
Flags, environment and files
--coding-agents·--client- what to install
--system·--local- every directory, or this project
--activate- always create a new workspace
- Adapters in another project
python3 -m pip install "macaw-adapters[openai]"with the extras you need. Needs the client installed on that machine.MACAW_API_KEY- Join a workspace without the prompt: MACAW_API_KEY=mw_… macaw-ai install
MACAW_HOME- Where the client looks for .macaw/config.json (otherwise ~/.macaw). Set it in each shell that runs MACAW code.
MACAW_PYTHON- The interpreter the client installs into, e.g. python3.14
MACAW_LOG_LEVEL- Client logging; WARNING by default, DEBUG to troubleshoot
- Your key
- .macaw/config.json, in your home directory (every directory) or the project (this project). Treat it like a password; a .gitignore keeps it out of commits.
- Claude Code hooks
- .claude/settings.json and .claude/hooks, in the same place
- Codex hooks
- .codex/config.toml, in the same place
- The service (every directory)
- macOS: a LaunchAgent; Linux: a systemd user service; Windows: the Startup folder
- What your agent did
- ~/.macaw/logs/, one file a day
- Binary cache
- ~/.cache/macaw/<version>/, about 50 MB a version
Update and remove
- Check it
- macaw-sidecar --status: running, reaching the control plane, and one real decision round-trip. macaw-client check for the client.
- See what your agent did
- macaw-sidecar --view
- Update
- npm install -g @macaw-ai/coding-agents, then macaw-sidecar install --system again. Your workspace is kept.
- Switch workspace
- Run the install with --activate for a new one, or with MACAW_API_KEY=mw_… to join another.
- Remove coding agents
- macaw-sidecar uninstall --system (or --local). Your key stays in .macaw until you delete it; remove the workspace in the console.
- Remove the client
- macaw-client uninstall
Upgrading from an early install? Early versions wrote root-owned managed-settings files. Delete them before removing MACAW, or every tool call fails closed: /Library/Application Support/ClaudeCode/managed-settings.json (macOS), /etc/claude-code/managed-settings.json (Linux), /etc/codex/managed_config.toml.
The original way: download from the console
- Create a workspace in the console, signing in with Google or GitHub.
- Open Dev Hub and choose Download MACAW Client SDK, then your platform and Python version. Each download includes a key for your workspace.
- Unzip it, set MACAW_HOME to that folder, and pip install the wheel with the adapters: pip install macaw_client-*.whl "./secureAI[all]"
- Run python secureAI/test_harness.py, then the examples.