Menu
Diagnose and resolve errors with Ciana's host bridges, CLI tools, Claude Code mode, macOS permissions, and gateway connectivity.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Guide for creating, updating, and managing skills. Use when: you need to extend your capabilities with a new skill, or the user asks you to create one. Skills are persistent Markdown instruction modules auto-discovered at runtime.
Send and read WhatsApp messages via the wacli CLI. Search chats, view history, send text and files to contacts or groups.
Access 1Password secrets via the op CLI: read passwords, inject secrets into commands, manage vaults. Requires desktop app integration.
Manage Apple Reminders via remindctl CLI: list, add, edit, complete, delete. Supports lists, date filters, and JSON output. Syncs to iOS devices.
Create, search, and manage Bear notes via the grizzly CLI. Supports tags, x-callback-url, and JSON output.
Control Bluesound/NAD players: discovery, playback, volume, grouping, and TuneIn radio via blu CLI.
| name | troubleshooting |
| description | Diagnose and resolve errors with Ciana's host bridges, CLI tools, Claude Code mode, macOS permissions, and gateway connectivity. |
Reference guide for diagnosing errors. Read this when a command fails, a bridge is unreachable, or a user reports something isn't working.
host_execute call returns an errorThe gateway process is not running on the host machine.
Tell the user: Run make gateway on the host (outside Docker) to start it.
The token in the Docker container doesn't match the one on the host.
Tell the user: Verify that GATEWAY_TOKEN in .env matches on both sides, then restart both gateway and container.
The bridge name doesn't exist in config.yaml under gateway.bridges.
Check: Are you using the correct bridge name? Compare with the available list in the error.
The CLI command is not in the bridge's allowed_commands list. This is a security feature.
Tell the user: Add the command to the bridge's allowed_commands in config.yaml and restart the gateway.
The CLI binary is not installed on the host. Exit code 127.
Installation commands (Homebrew):
| CLI | Install command |
|---|---|
remindctl | brew install steipete/tap/remindctl |
imsg | brew install steipete/tap/imsg |
spogo | brew install steipete/tap/spogo |
wacli | brew install steipete/tap/wacli |
sonoscli | brew install steipete/tap/sonoscli |
bear | brew install steipete/tap/bear |
camsnap | brew install steipete/tap/camsnap |
peekaboo | brew install steipete/tap/peekaboo |
blucli | brew install steipete/tap/blucli |
obsidian-cli | brew install steipete/tap/obsidian-cli |
openhue | brew install openhue/cli/openhue |
things-cli | brew install thingsapi/things-cli/things-cli |
op | brew install 1password-cli |
Some CLIs require one-time interactive setup on the host before they can work through the gateway. The gateway cannot handle interactive prompts (QR codes, passwords, browser flows).
Tell the user to run these manually in their terminal:
| CLI | Setup command | Notes |
|---|---|---|
spogo | spogo auth import --browser chrome | Needs Spotify Premium. Keychain popup: click "Always Allow" |
wacli | wacli auth then wacli sync --follow | Scan QR code with WhatsApp on phone |
imsg | (automatic) | Grant Full Disk Access + Automation for Messages.app in System Settings |
op | op signin | Needs 1Password account |
openhue | openhue setup | Press Hue Bridge button when prompted |
Some CLIs need macOS privacy permissions. These are granted once in System Settings > Privacy & Security.
If a CLI tries to access Chrome cookies or saved credentials, macOS shows a Keychain dialog. This blocks the subprocess until the user responds.
Tell the user: Enter password and click "Always Allow" so it won't ask again.
Required by: imsg (reads Messages database)
Tell the user: System Settings > Privacy & Security > Full Disk Access > enable Terminal (or the app running the gateway).
Required by: imsg (controls Messages.app)
Tell the user: System Settings > Privacy & Security > Automation > allow Terminal to control Messages.
CLIs that access these trigger a one-time permission prompt. Accept it when it appears.
The request to the gateway is missing required fields. Make sure the container is running the latest code.
Tell the user: Rebuild and restart: make build && make restart
Auth token mismatch between the CC bridge config (CC_BRIDGE_TOKEN) and the gateway (GATEWAY_TOKEN).
Tell the user: Check that both tokens match in .env, restart both.
Same as gateway connection error. The CC bridge uses the gateway.
Tell the user: Run make gateway on the host.
Claude Code stores projects in ~/.claude/projects/. If this directory doesn't exist or is empty, there are no projects to show.
Tell the user: Use Claude Code from the terminal first to create at least one project, or check that projects_dir in config.yaml points to the right path.
Claude Code can take a long time for complex tasks. The default timeout is 0 (unlimited).
If it seems stuck, the user can exit CC mode and re-enter. The session state is persisted and can be resumed.
Any command that requires user input (stdin) will fail or hang. This includes:
wacli auth)Rule: Always do initial auth/setup directly on the host terminal, not through Ciana.
host_execute truncates output at 15,000 characters. For commands that produce very long output, use --limit, --json, or pagination flags to reduce output size.
The gateway process must run on the macOS host because it needs access to native apps (Messages, Reminders, Spotify, etc.). Docker containers can't access these.
The container reaches the host via http://host.docker.internal:9842.