Skip to main content

Set up with an AI agent

Use this playbook in a terminal-capable Codex or Claude Code session on the agent computer. It covers installation through the first useful reply. It can also be read as a setup skill; installing a skill is optional.

Execution rules​

  • Use catalex commands for setup and management. Read <command> --help before using an unfamiliar flag. Use --json for structured results; finite results use catalex.result.v1.
  • Keep the existing folder, AI tool, model, instructions, MCP tools and permission guards. Do not rewrite application configuration, databases or service files, call private APIs, or kill processes to bypass an error.
  • Ask the person for sign-in, folder trust, credentials and choices you cannot infer. Never accept trust or sign in for them. Never ask for secrets in chat: use private file paths or the app’s secret inputs.
  • Preserve a working setup. Inspect state before retrying a mutation with an uncertain outcome. Use its original operation ID where supported.
  • Do not delete data, replace a server identity or expand tool access without the person’s authorization. A request to set up a folder does authorize its reviewed onboarding repairs.

1. Inspect and install​

Run catalex version if available. If missing, follow Install CatalEx, then catalex install status. Verify the platform: the agent runtime requires Apple Silicon macOS. On other platforms, explain the limitation rather than claiming a CLI installation can run agents.

If catalex status reports an existing setup, reuse it. Otherwise choose native chats for a prompt that requests them; for a general setup, offer Everything on this computer and ask whether messaging should be WhatsApp, Slack, Google Chat or later. Install only the components for that choice from the setup table.

2. Prepare the provider and start​

Run catalex providers. The current agent’s provider must be installed, a supported version and signed in. If it is signed out, run catalex providers login PROVIDER and wait for the person. If the setup exists but the tool is not connected, use catalex providers connect PROVIDER.

For a new setup, run the matching command from the install guide with --native-providers PROVIDER --start. A remote service requires its actual URL and private connector-token file. Never send a token to an example URL. Check catalex status; for native chats the agent and native-chat components must be ready. Messaging additionally needs the service connection.

3. Onboard this folder​

Use the absolute folder where this agent’s instructions live. Do not copy a packaged agent into an empty folder. For multiple roles, onboard each role’s folder separately.

catalex agents onboard --folder /absolute/agent-folder --name Helper --agent claude --json

Use codex for Codex. Without --apply, the command only inspects. Review findings and follow the onboarding remedies. For Claude packages that require folder isolation, use --isolation folder. For Codex, do not remove a package’s isolation requirements to make it register.

Then repeat with the same choices and --apply. Record the changed files and agent ID. Preserve everything outside CatalEx’s marked integration block and retain the package’s native guards. An agent whose tool serves one fixed person needs per-person routing before it can safely serve separate chats.

4. Prove a reply​

catalex channels list --json
catalex chats create --channel NATIVE_CHAT_CHANNEL_ID --name "Setup check" --json
printf 'Reply with exactly: CATALEX READY\n' | catalex chats send CHAT_ID --wait
catalex chats history CHAT_ID

Read the agent’s native_chat channel ID from the list and the chat ID from the create result. Older versions call this channel browser. Do not substitute an account ID. The response must contain CATALEX READY.

Next ask a question whose answer requires a known folder file or native tool, and compare the result with that source. Test a restriction if the package has one. A greeting alone does not prove tools or instructions loaded. Keep the chat for inspection, run catalex open if the app is installed, and tell the person where it is.

5. Connect requested messaging​

Follow WhatsApp, Slack or Google Chat. For terminal setup, use the checkpoint workflow. A service on this computer needs a public HTTPS address. Ask before provisioning a tunnel service the person has not selected.

Assign the account to the intended agent, review its access rules and limits, then send a real message from the receiving app. Do not claim WhatsApp, Slack or Google Chat works from a native-chat test.

6. Finish with observed state​

Report the version, setup choice, agent name and folder, onboarding file changes, native reply evidence and messaging delivery evidence separately. Name remaining work with its next command: provider sign-in, trust prompt, account credentials, public address or delivery check.

If a step fails, read the code and next action, repair through supported commands and retry. Do not silently switch providers or recreate accounts. See Troubleshooting.

Last updated on