troubleshooting
Skill1 starsChanged 9 months agoMITView on GitHub
Diagnose and resolve errors with Ciana's host bridges, CLI tools, Claude Code mode, macOS permissions, and gateway connectivity.
- Reads credentials
- Installs packages
26 other projects use a version of this.
Adopted by
Most recently taken up by
- thistleknot/skillstheir own version, first seen Nov 8, 2026
- oivanfelipe/claude-skillstheir own version, first seen Nov 8, 2026
- onelastcommit/noctratheir own version, first seen Nov 8, 2026
- zakirkun/slayerclawtheir own version, first seen Nov 8, 2026
- snowfluke/tech-lead-skillstheir own version, first seen Nov 8, 2026
- jkitchin/knowhowtheir own version, first seen Nov 1, 2026
Used with
Projects with it also use task-breakdown and architecture.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
ttmouseSkilltask-breakdown
专业的任务拆解器，将复杂需求拆分成"独立可运行与可演示"的最小闭环任务卡。严格按照纵向切片、单一数据变化、单一入口原则，确保每张任务卡都能在单回合实现并验证。当用户说"帮我拆解一下任务"、"用任务拆解器分析"、"按规范拆分"或需要将一个大的开发需求拆分成可执行的小任务时使用。输出格式严格按照[src/renderer/TODO.md]标准存储。
Also in 3 projects that use this
AnthropicSkillarchitecture
Create or evaluate an architecture decision record (ADR). Use when choosing between technologies (e.g., Kafka vs SQS), documenting a design decision with trade-offs and consequences, reviewing a system design proposal, or designing a new component from requirements and constraints.
Also in 3 projects that use this
Other versions26 projects use a version of this.
Word for word · 1
- emanueleielo/ciana-parrot★ 77100% same
Edited · 0
None found.
Wrote their own version · 25
- ChromeDevTools/chrome-devtools-mcp★ 55ksame name
- cartography-cncf/cartography★ 4.2ksame name
- jasonkneen/kiro★ 753same name
- nanvix/nanvix★ 318same name
- duyet/clickhouse-monitoring★ 303same name
- davidYichengWei/agentic-engineering-framework★ 158same name
- projectbluefin/finpilot★ 131same name
- mycelium-io/mycelium★ 127same name
- NVIDIA/elements★ 115same name
- jkitchin/knowhow★ 42same name
15 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository26 other files it gives its agents.
- 1passwordSkill
- apple-remindersSkill
- bear-notesSkill
- blogwatcherSkill
- blucliSkill
- camsnapSkill
- elevenlabs-ttsSkill
- gemini-image-genSkill
- gifgrepSkill
- githubSkill
- google-placesSkill
- imessageSkill
- nano-pdfSkill
- notionSkill
- obsidianSkill
- openai-image-genSkill
- openhueSkill
- peekabooSkill
- skill-creationSkill
- sonosSkill
- spotifySkill
- thingsSkill
- trelloSkill
- video-framesSkill
- weatherSkill
- whatsappSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 3 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 22 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
Tell the user: Run make gateway on the host (outside Docker) to start it.
- Very specific: line 29
Tell the user: Verify that GATEWAY_TOKEN in .env matches on both sides, then restart both gateway and container.
- Very specific: line 41
Tell the user: Add the command to the bridge's allowed_commands in config.yaml and restart the gateway.
- Distinctive: line 87
If a CLI tries to access Chrome cookies or saved credentials, macOS shows a Keychain dialog.
- Very specific: line 119
Tell the user: Check that both tokens match in .env, restart both.
- Very specific: line 125
Tell the user: Run make gateway on the host.
- Very specific: line 131
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 …
- Distinctive: line 137
If it seems stuck, the user can exit CC mode and re-enter.
- Distinctive: line 149
Rule: Always do initial auth/setup directly on the host terminal, not through Ciana.
“Common” is measured: kept by at least 6 in 10 of the 22 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Troubleshooting
Reference guide for diagnosing errors. Read this when a command fails, a bridge is unreachable, or a user reports something isn't working.
When to Use
- A
host_executecall returns an error - Claude Code mode fails
- User says something "doesn't work" or asks how to set up a feature
- You get connection, auth, or permission errors
Gateway Errors
"Cannot connect to host gateway. Is the gateway server running?"
The gateway process is not running on the host machine.
Tell the user: Run make gateway on the host (outside Docker) to start it.
"Gateway auth failed. Check GATEWAY_TOKEN."
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.
"unknown bridge 'X'. Available: ..."
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.
"command 'X' not allowed for bridge 'Y'"
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.
CLI Not Found
"Command 'X' not found on host. Install it first."
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 |
CLI Authentication
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 |
macOS Permissions
Some CLIs need macOS privacy permissions. These are granted once in System Settings > Privacy & Security.
Keychain Access Popup
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.
Full Disk Access
Required by: imsg (reads Messages database)
Tell the user: System Settings > Privacy & Security > Full Disk Access > enable Terminal (or the app running the gateway).
Automation
Required by: imsg (controls Messages.app)
Tell the user: System Settings > Privacy & Security > Automation > allow Terminal to control Messages.
Reminders / Contacts / Calendar
CLIs that access these trigger a one-time permission prompt. Accept it when it appears.
Claude Code Mode
"Bridge returned HTTP 400"
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
"Bridge returned HTTP 401"
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.
"Cannot connect to Claude Code bridge"
Same as gateway connection error. The CC bridge uses the gateway.
Tell the user: Run make gateway on the host.
Project list is empty
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.
Session hangs or times out
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.
Edge Cases
Interactive commands don't work through the gateway
Any command that requires user input (stdin) will fail or hang. This includes:
- QR code scans (
wacli auth) - Password prompts
- Browser-based OAuth flows
- Confirmation dialogs
Rule: Always do initial auth/setup directly on the host terminal, not through Ciana.
Large output gets truncated
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.
Gateway runs on the host, not in Docker
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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.