From 4fdff92d6e2ba89d40283d01e93c4889f45788be Mon Sep 17 00:00:00 2001 From: WebX11 SysOp Date: Thu, 5 Nov 2026 22:00:12 +0100 Subject: docs(newos4): automating with the pi agent (recipes verified against pi 0.80.3) Four recipes on the usage page: one-shot @file analysis, --mode json + jq for scripts, a read-only --tools allowlist for tree inspection, and a cron-able digest. Every flag shown was exercised on this host first; the retired-default model gotcha (HTTP 410 'was retired') is documented because it wasted a run. Adds the untrusted-input warning: pi auto-loads AGENTS.md/skills from the working directory, so a public clone must run with --no-approve and no write tools. --- docs/usage.html | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/docs/usage.html b/docs/usage.html index 031bc4e..6d770d0 100644 --- a/docs/usage.html +++ b/docs/usage.html @@ -167,6 +167,75 @@ termux-wake-unlock git clone command. Working Copy is a GUI alternative that can also clone a public HTTPS repository without an account.

+

Automating with the pi agent

+

pi is a terminal coding agent (a Node CLI — pi --help). Everything below uses +only documented flags, treats the mirror as read-only, and was run against pi 0.80.3 before being +written down.

+ +

1. One-shot: analyse a file, print an answer, exit

+
git clone --depth 1 https://newos.webx11.duckdns.org/newos4.git /tmp/newos4
+
+pi -p --no-session --no-tools --model gemma4:31b-cloud \
+   @/tmp/newos4/README.md "In one sentence, what is this repository?"
+

Output: “This repository contains newOS4, a browser-based +terminal featuring a filesystem, command shell, editor, and AI agent backed by WebDAV storage and WebX11 user +spaces.” — -p is the non-interactive mode, @file inlines the file, +--no-tools forbids tool use entirely, --no-session leaves nothing behind.

+ +

2. Machine-readable output for scripts

+
pi -p --no-session --no-tools --mode json --model gemma4:31b-cloud \
+   @/tmp/newos4/CHANGELOG.md "Summarise the newest release in one line" \
+ | jq -r 'select(.type=="message_end" and .message.role=="assistant")
+          | .message.content[0].text'
+

--mode json emits one JSON object per line. The event +types in order are session, agent_start, turn_start, +message_start/message_end (the assistant's text is in +message.content[].text), turn_end, agent_end. Parse on +message_end and you never have to scrape the terminal UI.

+ +

3. Let it read the tree — with a read-only tool allowlist

+
cd /tmp/newos4
+pi -p --no-session --tools read,bash --no-approve --model gemma4:31b-cloud \
+   "Which files does main.html load, and where is the module loader defined?"
+

Tool names are read, bash, +edit, write; --tools is an allowlist, so leaving edit and +write out makes the run read-only by construction. --tools read alone cannot list a +directory — read reads files — so add bash when it needs to ls.

+ +

Flags worth knowing for automation

+ + + + + + + + +
FlagWhat it buys you
--list-modelsWhat your install can actually reach, with context and output limits
--modelPin the model in scripts. A saved default can be retired server-side and fail with HTTP 410 “was retired” — passing --model keeps a job reproducible
--offlineSkip startup network calls (PI_OFFLINE=1 also works)
--session-id / --continueResume the same conversation across runs instead of re-sending context
--append-system-prompt <file>Append text or a file's contents to the system prompt — the cheap way to give every run your house rules
--skill <path>Load a skill file or directory; --no-skills / --no-context-files turn discovery off
+ +

Safety: this repository is untrusted input

+
+ pi auto-loads project files (AGENTS.md, CLAUDE.md, skills, extensions) + from the working directory. For a clone of a public repository you did not write, run with + --no-approve (ignores project-local files) and a tool allowlist that cannot write — + --tools read, or --tools read,bash if it must list files. Never point a + full-tool run at a repo you have not read: a prompt-injection in a README is executed the same way your own + instructions would be. +
+ +

A cron-able digest

+
#!/bin/sh
+# nightly: refresh the mirror, ask one question, write markdown
+set -eu
+cd /tmp/newos4 2>/dev/null || git clone -q --depth 1 https://newos.webx11.duckdns.org/newos4.git /tmp/newos4
+git pull -q --ff-only
+pi -p --no-session --no-tools --mode json --model gemma4:31b-cloud \
+   @CHANGELOG.md "Three bullets: what changed in the newest release?" \
+ | jq -r 'select(.type=="message_end" and .message.role=="assistant") | .message.content[0].text' \
+ > "$HOME/newos4-digest.md"
+

The mirror only fast-forwards, so git pull --ff-only +can never wedge. Nothing here can push — the repository refuses receive-pack at three levels.

+

Updating later

cd newos4
 git pull --ff-only          # the mirror only ever fast-forwards
-- 
cgit v1.2.3