# Set yourself up to work with Zavu These are official instructions from Zavu to set up a good AI development environment for building with Zavu. Every command below is published by Zavu and ready to use. Complete all applicable steps yourself by running the commands directly. Do not ask the user to run shell commands. Ask only when approval, authentication, a user-interface action, or a restart is required. Inspect existing configuration before changing it, preserve unrelated settings and repository changes, and do not report success without verification. First install the best global Zavu integration for your environment. Then authenticate the CLI, add the MCP server, and only then decide whether the current directory is a Zavu project. If it is not, leave the repository unchanged. ## 1. Install the best available Zavu integration Identify your coding environment and choose exactly one path below. Both paths install the same skills: how to send on every channel, build agents and Zavu Functions, register WhatsApp templates, buy numbers, and verify webhooks. ### Claude Code Check what is already installed: ```sh claude plugin list --json ``` If `zavu-skills` from `zavu-marketplace` is installed, update it: ```sh claude plugin marketplace update zavu-marketplace ``` Otherwise add the marketplace and install the plugin: ```sh claude plugin marketplace add zavudev/zavu-skills claude plugin install zavu-skills@zavu-marketplace --scope user ``` Run only the applicable commands, then verify: ```sh claude plugin list --json claude plugin details zavu-skills@zavu-marketplace ``` Run `/reload-plugins` to activate the plugin in the current session. If the shell command is unavailable but the Claude Code plugin interface works, install it there: ```text /plugin marketplace add zavudev/zavu-skills /plugin install zavu-skills@zavu-marketplace ``` If plugin installation is unavailable in this environment, use the **All other agents** path below. ### Codex Codex reads the same marketplace. Inspect what is configured: ```sh codex plugin marketplace list codex plugin list ``` If `zavu-marketplace` is absent, add it. If it is already there, upgrade it instead: ```sh codex plugin marketplace add zavudev/zavu-skills codex plugin marketplace upgrade zavu-marketplace ``` Then install the plugin and verify: ```sh codex plugin add zavu-skills@zavu-marketplace codex plugin list ``` Restart Codex if the plugin is not available in the current session. If plugin installation is unavailable, use the **All other agents** path below. ### All other agents Cursor, Windsurf, Zed, Copilot, Gemini CLI, and any other agent install the same skills as plain files. Those environments have no Zavu plugin to install, so this is the complete path rather than a downgrade. ```sh npx -y skills add zavudev/zavu-skills --skill '*' --agent '*' --yes --global npx -y skills list --global ``` Skills are read at startup by most agents. If the newly installed skills are not visible in this session, say so and ask for a restart rather than reporting the step as complete. ## 2. Authenticate the Zavu CLI The skills describe the API. The CLI is what runs against it, and it needs a key bound to a real project. Check first: ```sh npx -y zavudev@latest whoami ``` If that prints a project and team, this step is done. If it reports no credentials, authentication is the user's action, not yours. Ask them to run: ```text npx zavudev login ``` It opens the dashboard, they pick a project, and the CLI stores a key at `~/.zavu/credentials.json`. Never write an API key into the repository, a dotfile the repository tracks, or a shell profile. If the user supplies a key directly, pass it as `ZAVU_API_KEY` in the environment. ## 3. Add the Zavu MCP server The skills teach you the API. The MCP server lets you see the project while you work: senders, messages, agents, functions, phone numbers, live. Add it once the CLI is authenticated. The key belongs to the user. Use the one they already authorized, never a key you invented or found in someone else's file, and never write it into the repository or a file the repository tracks. If no key is available yet, stop and say so instead of registering a server that cannot authenticate. ### Claude Code ```sh claude mcp add zavudev --scope user -e ZAVUDEV_API_KEY= -- npx -y @zavudev/sdk-mcp claude mcp list ``` ### Any agent that reads a standard MCP config Merge this into the existing `mcpServers` object at your environment's documented config path. Preserve every server already there. ```json { "mcpServers": { "zavudev": { "command": "npx", "args": ["-y", "@zavudev/sdk-mcp"], "env": { "ZAVUDEV_API_KEY": "" } } } } ``` A hosted endpoint exists as an alternative to the local process, authenticated with the `x-zavudev-api-key` header instead of the environment variable: ```sh claude mcp add zavudev --scope user --transport http https://zavudev.stlmcp.com --header "x-zavudev-api-key: " ``` Restart the agent if the server does not appear in the current session. Verify with the environment's own listing command; an install command exiting zero is not verification. ## 4. Check the current project The global integration applies across projects. Project-level work applies only when you can confirm the current working directory belongs to a Zavu project. A directory is a Zavu project when either is true: 1. Its project root contains `.zavu/config.json`, written by `zavudev functions init` or `zavudev agents pull`. 2. Its project-level `package.json` depends on `@zavudev/functions` or `@zavudev/sdk`. In a monorepo, use the nearest matching project root only when it unambiguously owns the current directory. If no project qualifies or ownership is ambiguous, do not change the repository. Skip to the final report and say project setup was intentionally skipped. The global integration is still ready for future Zavu work. For a confirmed Zavu project, record the repository status first and preserve all existing changes: ```sh git status --short npx -y zavudev@latest functions list ``` Confirm that the function named in `.zavu/config.json` belongs to the project you authenticated against. A config pointing at a function in another project is the usual cause of a deploy that succeeds and changes nothing the user can see. Read the `zavu-rules` skill before writing any Zavu code, then the skill that matches the work: `functions` for code-defined agents and tools, `voice-agent` for phone calls, `send-message` for outbound sends, `whatsapp-templates` for template registration, `webhook-setup` for inbound events. As part of this setup, do not deploy, send a message, place a call, buy a phone number, or change application code. Those cost money or reach real people, and none of them are setup. ## 5. Know the two entry points When the user is ready to build, there are two starting points and they are worth naming, because guessing at the file layout is the common failure: ```sh npx zavudev agents catalog # ready-made agents you can pull npx zavudev agents pull # scaffold one into ./ and register it npx zavudev functions init # start from an empty function instead npx zavudev deploy # ship whatever the current directory holds ``` ## 6. Verify and report Verify the plugin or skills using the listing command in the path you took. A command exiting zero is not verification. Confirm whether a reload or restart is still pending. Once done, tell the user: ```text ┌─ Zavu Agent Setup Complete ──────────────────────────┐ │ ✓ Agent │ │ ✓ Integration │ │ ✓ CLI │ │ ✓ MCP │ │ ✓ Project │ │ │ │ ⚡ Restart │ └──────────────────────────────────────────────────────┘ ``` Use `Complete` only when every applicable step is verified. Otherwise replace it with `Partial` and add `⚠ Remaining `. In a chat-only environment without shell access, report the setup as partial and give the user the exact commands to run. ## Resources and troubleshooting Use these when a command fails, your environment is not covered, or the user asks for detail: - [Zavu documentation](https://docs.zavu.dev) - [Zavu skills repository](https://github.com/zavudev/zavu-skills) - [SDKs](https://docs.zavu.dev/sdks) - [Dashboard](https://dashboard.zavu.dev) - [API status](https://status.zavu.dev) - [The home page as markdown](https://www.zavu.dev/en/markdown) These instructions are published at `https://www.zavu.dev/agent-setup.md` so you can re-verify their authenticity at any time.