ciao-dev-install
Skill11 starsChanged 10 days agoApache-2.0View on GitHub
Build the current develop checkout into an installed engine (wheel + PWA) and run it on this machine for testing, then watch logs for issues. Trigger on "install develop", "test the develop build", "install the current dev version", "build and install ciaobot", "install dev build", or asking to test new changes locally instead of via the release installer.
- Pipes a download into a shell
- Reads credentials
- Installs packages
In this repository63 other files it gives its agents.
- AGENTS.mdAGENTS.md
- ciao-release-notesSkill
- ciao-releaseSkill
- ciao-upkeepSkill
- gws-sharedSkill
- gws-workflow-email-to-taskSkill
- gws-workflow-file-announceSkill
- gws-workflow-meeting-prepSkill
- gws-workflowSkill
- gws-workflow-standup-reportSkill
- gws-workflow-weekly-digestSkill
- persona-content-creatorSkill
- persona-customer-supportSkill
- persona-event-coordinatorSkill
- persona-exec-assistantSkill
- persona-hr-coordinatorSkill
- persona-it-adminSkill
- persona-project-managerSkill
- persona-researcherSkill
- persona-sales-opsSkill
- persona-team-leadSkill
- prSkill
- recipe-backup-sheet-as-csvSkill
- recipe-batch-invite-to-eventSkill
- recipe-block-focus-timeSkill
- recipe-bulk-download-folderSkill
- recipe-collect-form-responsesSkill
- recipe-compare-sheet-tabsSkill
- recipe-copy-sheet-for-new-monthSkill
- recipe-create-classroom-courseSkill
- recipe-create-doc-from-templateSkill
- recipe-create-events-from-sheetSkill
- recipe-create-expense-trackerSkill
- recipe-create-feedback-formSkill
- recipe-create-gmail-filterSkill
- recipe-create-meet-spaceSkill
- recipe-create-presentationSkill
- recipe-create-shared-driveSkill
- recipe-create-task-listSkill
- recipe-create-vacation-responderSkill
- recipe-draft-email-from-docSkill
- recipe-email-drive-linkSkill
- recipe-find-free-timeSkill
- recipe-find-large-filesSkill
- recipe-forward-labeled-emailsSkill
- recipe-generate-report-from-sheetSkill
- recipe-label-and-archive-emailsSkill
- recipe-log-deal-updateSkill
- recipe-organize-drive-folderSkill
- recipe-plan-weekly-scheduleSkill
- recipe-post-mortem-setupSkill
- recipe-reschedule-meetingSkill
- recipe-review-meet-participantsSkill
- recipe-review-overdue-tasksSkill
- recipe-save-email-attachmentsSkill
- recipe-save-email-to-docSkill
- recipe-schedule-recurring-eventSkill
- recipe-send-team-announcementSkill
- recipe-share-doc-and-notifySkill
- recipe-share-event-materialsSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 81
If .venv/bin/ciao dies with bad interpreter: …/some-other-repo/.venv/bin/python, the console script was generated before this checkout was …
- Very specific: line 143
Hosted service (
Ciaobot Server.app): When the plist's ProgramArguments start with …/Ciaobot Server.app/Contents/MacOS/Ciaobot Server … - Very specific: line 191
Never pass --force silently.
- Very specific: line 252
If the install succeeded but a backend error appears, create a GitHub issue for it (gh issue create --repo raffaelefarinaro/ciaobot ...) — …
- Distinctive: line 286
Two log lines are by design, not defects: Do not file a GitHub issue for either without first reading its source:
- Distinctive: line 301
If a step fails, leave the machine in a known state: say which step failed and what is still running, rather than reporting a half-finished …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ciaobot develop install
Contributor/project skill — lives in the repo's workspace
skills/folder, notciao/stock/skills/. It is for people working on Ciaobot and is deliberately not packaged or shipped to end-user installs.ciao sync-skillsmirrors it into the runtime-discovered.claude/skills/catalog. Don't move it intociao/stock/.
Replaces the end-user one-liner (curl -fsSL .../install.sh | sh) with the same
outcome built from the local develop checkout: the current ciao/ engine
plus the current PWA, installed into this machine's own Python environment,
serving the existing workspace and password. Then watch the engine logs and
report anything broken.
There is no app bundle to assemble any more (#656) — the release is the
engine, so this skill's whole job is: build the PWA, install the Python package,
restart the service, watch the log. Expect a few minutes, dominated by the
npm ci dependency install.
Before you start
- The checkout must be on
develop, clean, and up to date. - Toolchain must be present: Node 22 (
.nvmrc),uv, Python 3.12+, and a repo.venvwithpip install -e '.[test]'already run. If any is missing, install it before building. - The installed engine is the one
com.ciao.server.plistmanages, and the workspace and password live in that plist's workspace.env; both are preserved. Ask the user before installing if the steps would overwrite something unexpected, and always confirm the restart because it cuts off whatever the running engine is doing.
Steps
1. Preflight
cd <path to your ciaobot checkout>
git switch develop
git pull --ff-only
git status --short # must be clean, or stop and askVerify the toolchain:
command -v uv node
nvm use # reads .nvmrc -> Node 22
ls .venv/bin/python1b. Check the running engine and active chats
The install restarts the engine, which cuts off anything running in it. Check before building:
.venv/bin/ciao service status --jsonFrom the JSON, note:
reachable— is the currently installed engine serving? This says nothing about whether your code is being served — seepython_path.python_path— the interpreter the plist actually runs. If this is not your checkout's.venv(a~/.local/bin/ciaouv-tool release install is the usual culprit), the service is running a copy, so none of your edits are live andreachable: truetells you nothing useful. Say so before installing: this skill repoints the plist, which switches the daily-driver service over todevelop. Back the old plist up (cp …/com.ciao.server.plist …plist.bak.devinstall) so the release install is one command away.restart_blockers— a list of{chat_id, reasons}. Non-empty means a restart would interrupt chats (working, or waiting on an open question/approval card);nullmeans the engine could not be asked, which should be treated as blocked. Ask the user to let them finish (or confirm explicitly) before proceeding; the restart happens underneath them.ciao service restartandciao service stopenforce the same gate with a--forceescape hatch — never pass--forcesilently.loaded/installed— sanity check that the engine you are about to replace is the onecom.ciao.server.plistmanages.
If .venv/bin/ciao dies with bad interpreter: …/some-other-repo/.venv/bin/python,
the console script was generated before this checkout was renamed or moved. Step
3's pip install -e regenerates it, but step 1b needs the CLI now, so fall
back to the module entry point (python -m ciao does not work — ciao has
no __main__):
.venv/bin/python -c "from ciao.cli import main; main()" service status --jsonRe-check right before the restart in step 4 too: a chat started during the long build is just as interruptible.
2. Build the PWA
cd web && npm ci && npm run buildOutput goes to ciao/web/static/, which ships as package data inside the
wheel. Build the PWA before the install, or the installed engine serves the
previous build's assets.
3. Install the current checkout
cd <path to your ciaobot checkout>
.venv/bin/python -m pip install -e '.[test]'A plain editable install of the checkout is the whole point: it is what makes
ciao run the code you are editing. Confirm the import resolves to the
checkout, not to some other copy on the machine — and run it from outside the
checkout:
(cd ~ && /path/to/ciaobot/.venv/bin/python \
-c "import ciao, pathlib; print(ciao.__version__, pathlib.Path(ciao.__file__).resolve())")The cd is not optional. Run from the repo and a broken editable install still
prints the right answer: '' is on sys.path, so the local ciao/ package
shadows whatever the __editable__ finder points at. A finder left mapping to a
renamed-away checkout (…/ciaobot-rel/ciao) imports clean from inside the repo
and raises ModuleNotFoundError from everywhere else. Only the neutral-cwd run
tells you whether the install is real.
On macOS, re-render the LaunchAgent against the existing workspace so it names the current interpreter and code (read the workspace from the installed plist):
workspace=$(/usr/libexec/PlistBuddy -c 'Print :WorkingDirectory' \
"$HOME/Library/LaunchAgents/com.ciao.server.plist" 2>/dev/null || true)
[ -n "$workspace" ] && [ -d "$workspace" ] && [ -f "$workspace/.env" ] \
|| { echo "could not recover the workspace from the existing plist" >&2; exit 1; }
.venv/bin/ciao setup --workspace "$workspace" --python "$(pwd)/.venv/bin/python" --yes --load-launchd >/dev/nullciao setup preserves the existing .env (its variables win over setup
arguments), so the password and vault root survive the re-render.
Hosted service (Ciaobot Server.app). When the plist's ProgramArguments
start with …/Ciaobot Server.app/Contents/MacOS/Ciaobot Server serve --python
<interpreter>, ciao setup deliberately keeps that live hosted definition
byte-for-byte (_existing_hosted_definition_serves in ciao/cli.py), so the
command above exits 0 and changes nothing: the service keeps running the old
interpreter. Point the hosted definition at this checkout instead; the restart in step 4
reloads it:
plist="$HOME/Library/LaunchAgents/com.ciao.server.plist"
if [ "$(/usr/libexec/PlistBuddy -c 'Print :ProgramArguments:1' "$plist")" = "serve" ]; then
cp "$plist" "$plist.bak.devinstall"
/usr/libexec/PlistBuddy -c "Set :ProgramArguments:3 $(pwd)/.venv/bin/python" "$plist"
plutil -lint "$plist"
fi4. Restart the service
Gate on restart blockers first, then restart:
tmp=$(mktemp)
.venv/bin/ciao service status --json > "$tmp"
python3 - "$tmp" <<'EOF'
import json, sys
data = json.loads(open(sys.argv[1]).read())["details"]
blockers = data.get("restart_blockers")
if blockers is None or blockers:
raise SystemExit(f"Restart would interrupt: {blockers}")
print("no restart blockers - clear to restart")
EOF
[ $? -eq 0 ] && .venv/bin/ciao service restartciao service restart reloads an edited plist (bootout and bootstrap) when the
loaded definition differs from the one on disk, and kickstarts otherwise. Confirm
the switch took with ciao service status --json: loaded_python_path is the
interpreter launchd is actually running and plist_matches_loaded must be
true. (python_path is read from the plist file, so on its own it reports the
new interpreter even while the old process is still serving.)
Two things bite here. status=$(…) is a zsh read-only variable and aborts the
whole snippet, so use a neutral name; and backslash-escaping quotes inside a
python3 -c '…' f-string does not survive the shell, so feed the script on
stdin instead. raise SystemExit(msg) prints to stderr and exits non-zero, which
is the gate you want.
Never pass --force silently; if the user explicitly asked to cut through, say
so out loud in the report.
5. Watch for issues
The engine logs live in the workspace:
tail -f "$workspace/.runtime/ciao.stdout.log" "$workspace/.runtime/ciao.stderr.log"Watch for at least a minute. Issues to flag to the user:
Engine crash loop — the engine exits shortly after starting, repeatedly (launchd
KeepAliverestarts it). Look for tracebacks inciao.stderr.log, and count boots rather than trusting a single healthy-looking process:grep -c "Starting Ciaobot server" "$workspace/.runtime/server_debug.log"One boot for this restart is the pass; the count climbing across a minute is the loop.
ciao setup --load-launchd(step 3) bootstraps the plist, so the restart in step 4 legitimately produces two boots a few seconds apart — that is not a loop.- Import errors at startup (
ModuleNotFoundError,ImportError) — usually apip installthat ran before the PWA build, or an import resolving to a differentciaoon the machine'ssys.path. - Port already in use / startup refused because another Ciaobot backend owns the runtime root.
PWA not reachable:
curl -s http://127.0.0.1:8443/should return HTML. If the engine answers but the PWA shows the recovery page, the static bundle behind the running process is stale — re-run step 2 and restart again. Confirm you are serving this build by diffing the asset hash the servedindex.htmlnames against the one on disk:grep -oE 'assets/index-[A-Za-z0-9_-]+\.js' ciao/web/static/index.html curl -s http://127.0.0.1:8443/ | grep -oE 'assets/index-[A-Za-z0-9_-]+\.js'- Version mismatch — the served version should match the checkout:
.venv/bin/ciao --versionvs Settings → General.
Sanity probes:
launchctl print "gui/$(id -u)/com.ciao.server" | grep -E "state|pid" | head
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8443/
(cd ~ && /path/to/ciaobot/.venv/bin/python -c "import ciao; print(ciao.__file__)")6. Report
Summarize: built commit (git rev-parse --short HEAD), install type (editable
checkout), workspace preserved, engine and PWA status, and any log findings with
their source line numbers.
Also report what changed underneath the user: if the plist was pointing at
something other than this checkout, say plainly that the service moved from a
release install to develop, and where the old plist backup is.
If the install succeeded but a backend error appears, create a GitHub issue for
it (gh issue create --repo raffaelefarinaro/ciaobot ...) — but only for
genuine defects. Check the by-design log lines in the traps above first, and
prefer telling the user a finding is a workspace-config concern over filing
noise against a working engine.
Notes and traps
- A running process is not a working engine. Confirm the PWA answers and
that the boot count in
server_debug.logis not climbing. An auth-required install returnsunauthorizedfrom/api/startup— that is a pass, not a failure. - Don't diff this boot's log by line offset. Startup runs
startup_triage: Capped oversized service logs, which truncates and rewritesciao.stderr.logduring the very boot you are trying to measure, so an offset you captured in preflight silently points at the wrong region. Filterserver_debug.logby timestamp instead — it is not capped. Uvicorn running ongoes to stderr, not stdout. Grepping onlyciao.stdout.logfor it returns 0 and reads like a failed boot. The app's own markers areStarting Ciaobot server on 0.0.0.0:8443andStarted server process [pid].- Build the PWA last-to-ship, not last overall. The editable install copies
package data (
ciao/web/static/) at install time, so an install that ran beforenpm run buildbakes in the previous build's assets. When in doubt, repeat step 2 thenpip install -e .then restart. - The editable install is the source of truth, not
PATH. Twociaoon one machine is normal in a contributor setup; always drive this skill with.venv/bin/…so you are talking to the checkout you just built. - Never trust
import ciaorun from inside the checkout.''is onsys.pathwhen cwd is the repo, so the localciao/package shadows the__editable__finder and a totally broken install still prints a healthy version and path. Every import check here must run from a neutral directory ((cd ~ && …)), and the answer to give is the path — not the version, which will look right either way. - Two log lines are by design, not defects. Do not file a GitHub issue for
either without first reading its source:
startup_triage: Startup found runtime errors but a triage chat ran at …; waiting out the cooldown—TRIAGE_COOLDOWN_Sis 12h (ciao/startup_triage.py). The suppression is working.backup_service: Memory backup failed: … N tracked path(s) outside the backup scope would not be backed up— by design; its own docstring says "a developer checkout reports its whole application source" (ciao/backup_service.py). The backup still commits and pushes. A workspace that is itself a git repo will always trip this.
- Never restart from inside a PWA chat. Apply the change and ask the operator to hit Deploy or Restart in Settings.
pytest tests/is not a smoke test. The suite mocks the provider, the launchd surface and the clock. This skill is what proves the engine boots against a real workspace.- If a step fails, leave the machine in a known state: say which step failed and what is still running, rather than reporting a half-finished install as done.
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.

