Repository navigation
docs: A README demo of agents working in several projects at once - #10
Conversation
acb6166 to
8ba147e
Compare
The new GIF shows what HomeShell is for: agents at work across several projects and worktrees, with every running and past session in view. A new worktree gets an Enclave session with Playwright, briefed in a real terminal opened from HomeShell; another agent's question is answered; the finished feature is reviewed in its folder; and an old conversation is continued. scripts/demo-video records it with real Claude Code agents on a virtual desktop, in a throwaway demo home outside $HOME, and speeds up the waits. An MP4 of the same cut sits next to the GIF. How to run it is in DEV.md.
336c715 to
2eff942
Compare
EclipseSourceAI
left a comment
There was a problem hiding this comment.
Note
Autonomous AI review. May contain mistakes.
Useful comment? React 👍. Disagree? React 👎 to reject it for follow-up reviews. A reply explaining why helps too.
This agent never approves PRs. A maintainer must sign off.
Only a maintainer can re-request a review from this agent.
Powered by Eclipse Enclave via review-guard-mcp
This PR replaces the README GIF with a new demo: agents working across four projects, with a new worktree, an Enclave session briefed in a terminal, a question answered, the result reviewed and an old conversation continued. It also adds scripts/demo-video/ so the demo can be recorded again. setup.sh builds a throwaway HOME and git projects, xsession.sh starts Xvfb, metacity and gnome-terminal, seed.mjs and story.mjs drive a real daemon and real Claude Code agents over the public API plus the X pointer, and encode.sh cuts the take or speeds it up according to a timeline. Product code is unchanged, and docs/DEV.md gets a "Demo GIF" section.
I checked the scripts against the daemon. The API routes, settings fields (notifications.style/sound, terminal.emulator: custom with {command}, workstreams.location), the -home-dir flag, the hs_api_token cookie and the creating- placeholder prefix all match the current code. Bridge sockets land under the demo's XDG_RUNTIME_DIR, so the kill-by-exact-match in cleanup catches them too. Docs lint passes.
What a maintainer should look at:
- Wipe safety: setup.sh
rm -rfsDEMO_ROOTandDEMO_PROJECTS. The.homeshell-demomarker guard is sound, but relative paths get past the outside-$HOMEcheck (inline comment). - Key handling: the last 20 characters of
ANTHROPIC_API_KEYare written to the demo home and Enclave's auth store, and cleanup deletes them. If setup.sh itself fails, they stay behind, because the trap is only installed after setup. - Repo weight: the GIF grows by about 0.8 MB, and a 2.4 MB MP4 with no consumer is added.
No UI behavior changes, so I didn't run a browser check. I did look at the GIF's first frame, which shows a dev version string in the header (inline comment).
| for dir in "$projects"/*/; do | ||
| [ -d "$dir/.git" ] || continue | ||
| git -C "$dir" worktree list --porcelain | sed -n "s/^worktree //p" | tail -n +2 | | ||
| while IFS= read -r tree; do | ||
| case "$tree" in "$projects"/*) rm -rf "$tree" ;; esac | ||
| done | ||
| done |
There was a problem hiding this comment.
This loop only deletes worktrees under $projects, and line 41 rm -rfs $projects anyway, so it never does anything the next line doesn't. Drop it.
| real_runtime=${XDG_RUNTIME_DIR:-/run/user/$(id -u)} | ||
| home=$root/home | ||
|
|
||
| case "$projects" in "$real_home"/*) echo "projects dir must be outside $real_home" >&2; exit 1 ;; esac |
There was a problem hiding this comment.
A relative DEMO_PROJECTS (or DEMO_ROOT) gets past this guard even when it resolves inside $HOME. It also breaks the run later: the trusted folders in .claude.json and run.sh's index($2, p) == 1 container match both expect an absolute path. Resolve both to absolute paths first (realpath -m) in run.sh or here.
|
|
||
| display=${1:?display number} | ||
| shift | ||
| screen=${DEMO_SCREEN:-1280x800} |
There was a problem hiding this comment.
DEMO_SCREEN doesn't actually work: desktop.mjs hardcodes SCREEN = 1280x800 for the Chromium window size, the pointer start and ffmpeg's -video_size, so any other value records the wrong area. Either drop the variable or pass it through to desktop.mjs. It's also missing from the env list in DEV.md.
| // and real Claude Code sessions, some finished or ended, some still at work when it returns. | ||
| // | ||
| // Usage: node scripts/demo-video/seed.mjs <base-url> <projects-dir> | ||
| // Env: DEMO_TERMINAL, the gnome-terminal line Open runs (see run.sh). |
There was a problem hiding this comment.
DEMO_TERMINAL is set in take.sh, not run.sh.
There was a problem hiding this comment.
Nothing references this MP4, and the description says it's only there in case we want it some day. That puts 2.4 MB into git history for good. Leave it out until something embeds it (encode.sh can still write it locally).
There was a problem hiding this comment.
Thanks, but I'd rather keep it. We'll likely use the MP4 elsewhere soon (it's the same cut at full size), and recording it again later would mean another full run with real agents.
There was a problem hiding this comment.
Fair, that's a size vs. re-record cost call. Leaving it to the maintainers whether 2.4MB of unreferenced binary in git history for good is worth avoiding another full run.
There was a problem hiding this comment.
The header in the GIF reads daemon 0.0.0-g772bb2a, a dev build version, and that's the first thing visitors see in the README. Re-record with a release-like VERSION (e.g. make build VERSION=...), or have the DEV.md steps set one.
There was a problem hiding this comment.
Good catch, but I'll leave it as is for now. It's a small detail in the header, and a re-take costs a full run with real agents. Next time we re-record, we can do it on a release build.
There was a problem hiding this comment.
Makes sense given what a re-take costs. Leaving it to the maintainers whether a dev version string in the README's first-impression GIF is fine until the next recording.
It only removed worktrees under the projects dir, which the next line deletes anyway. Review: #10 (comment)
A relative projects dir got past the outside-$HOME guard even when it resolved inside it, and broke the trusted folders in .claude.json and the cleanup's container match, which both expect absolute paths. The guard now also refuses $HOME itself. Review: #10 (comment)
The demo home holds the API key's tail from early in setup, but run.sh arms its cleanup only after setup.sh succeeds. Review: #10 (review)
desktop.mjs sizes Chromium, the pointer and the recording to its fixed SCREEN, so any other value recorded the wrong area. Review: #10 (comment)
EclipseSourceAI
left a comment
There was a problem hiding this comment.
Note
Autonomous AI review. May contain mistakes.
Useful comment? React 👍. Disagree? React 👎 to reject it for follow-up reviews. A reply explaining why helps too.
This agent never approves PRs. A maintainer must sign off.
Only a maintainer can re-request a review from this agent.
Powered by Eclipse Enclave via review-guard-mcp
Follow-up review. Since my last pass (at 2eff942), five commits landed (7a1320b, 51d4d53, 0bac6d9, 3dc036a, 957981b, 987df2c) that touch only scripts/demo-video/{setup,run,xsession}.sh, seed.mjs and docs/DEV.md. I checked each against my earlier findings:
- The redundant worktree-deletion loop in
setup.shis dropped. DEMO_ROOT/DEMO_PROJECTSare now resolved withrealpath -min bothsetup.shandrun.sh, and the outside-$HOMEguard now also rejects$HOMEitself. I tested the updatedcaseguard directly and it behaves correctly for the exact-match, subdir, and non-matching-prefix cases.DEMO_SCREENis dropped fromxsession.sh(and no longer mentioned inDEV.md), sincedesktop.mjshardcoded the screen size anyway.- The
DEMO_TERMINALdoc comment inseed.mjsnow points attake.sh. - As a bonus,
setup.shnow traps its own failure to delete the demo home (and the key tail in it) even whenrun.sh's cleanup was never armed, andDEV.mddocuments it.
All four of my open threads are genuinely fixed, listed below. On the two threads where the author pushed back (keeping the MP4, keeping the dev-version GIF), those are cost/benefit calls, not factual disputes, so I replied in both threads to leave the final call to the maintainers rather than re-litigate it. No other changes landed since my last review, so I have no new findings.
These previous comments can be resolved as they are now handled:
- redundant worktree-deletion loop in setup.sh, since the wipe deletes it anyway
- relative DEMO_ROOT/DEMO_PROJECTS bypassing the outside-$HOME guard and breaking trusted-folder/cleanup matching
- DEMO_SCREEN env var that desktop.mjs silently ignored
- DEMO_TERMINAL doc comment pointing at the wrong script
I can't resolve them myself as I would need write permission on this repository.
There was a problem hiding this comment.
Fair, that's a size vs. re-record cost call. Leaving it to the maintainers whether 2.4MB of unreferenced binary in git history for good is worth avoiding another full run.
There was a problem hiding this comment.
Makes sense given what a re-take costs. Leaving it to the maintainers whether a dev version string in the README's first-impression GIF is fine until the next recording.
fismif
left a comment
There was a problem hiding this comment.
LGTM, the new GIF looks richer and the titlebar adds to the identity imo. Also very good that we now have a script for the GIF. Thanks!
What and why
Replaces the README GIF with one that shows how you keep track of agents across several projects
and worktrees. In the video, we create a new worktree in
acme-webshopwith an Enclave sessionthat also gets Playwright, brief the agent in a terminal opened from HomeShell and close the
terminal while the agent keeps working. Meanwhile an agent in
payments-apiasks a question,which we answer in its terminal. Then we look at the finished feature in its worktree folder and
continue an older conversation about gift cards.
scripts/demo-video/run.shrecords it with real Claude Code agents in a throwaway demo home on avirtual desktop, so we can redo the GIF after UI changes. The agents run on
ANTHROPIC_API_KEY.Next to the GIF there is an MP4 of the same cut, in case we want to embed it as a video somewhere.
How to run it is in
docs/DEV.md(Demo GIF).Changelog
Checklist
AGENTS.md)(none: no product code changes)
AGENTS.md