Skip to content

docs: A README demo of agents working in several projects at once - #10

Merged
planger merged 7 commits into
mainfrom
homeshell-readme-demo
Nov 16, 2026
Merged

planger merged 7 commits into
mainfrom
homeshell-readme-demo

Conversation

@planger

@planger planger commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

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-webshop with an Enclave session
that 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-api asks 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.sh records it with real Claude Code agents in a throwaway demo home on a
virtual 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

none

Checklist

  • Tests added: unit and e2e, or a regression test for a bug fix (see AGENTS.md)
    (none: no product code changes)
  • Docs updated per the trigger table in AGENTS.md

@planger
planger force-pushed the homeshell-enclave-cli-sessions branch 5 times, most recently from acb6166 to 8ba147e Compare November 13, 2026 12:12
Base automatically changed from homeshell-enclave-cli-sessions to main November 13, 2026 12:55
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.
@planger
planger force-pushed the homeshell-readme-demo branch from 336c715 to 2eff942 Compare November 13, 2026 22:53
@planger
planger marked this pull request as ready for review November 16, 2026 12:42
@planger
planger requested a review from fismif November 16, 2026 12:42

@EclipseSourceAI EclipseSourceAI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 -rfs DEMO_ROOT and DEMO_PROJECTS. The .homeshell-demo marker guard is sound, but relative paths get past the outside-$HOME check (inline comment).
  • Key handling: the last 20 characters of ANTHROPIC_API_KEY are 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).

Comment thread scripts/demo-video/setup.sh Outdated
Comment on lines +34 to +40
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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread scripts/demo-video/setup.sh Outdated
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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread scripts/demo-video/xsession.sh Outdated

display=${1:?display number}
shift
screen=${DEMO_SCREEN:-1280x800}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread scripts/demo-video/seed.mjs Outdated
// 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).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

DEMO_TERMINAL is set in take.sh, not run.sh.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 EclipseSourceAI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.sh is dropped.
  • DEMO_ROOT/DEMO_PROJECTS are now resolved with realpath -m in both setup.sh and run.sh, and the outside-$HOME guard now also rejects $HOME itself. I tested the updated case guard directly and it behaves correctly for the exact-match, subdir, and non-matching-prefix cases.
  • DEMO_SCREEN is dropped from xsession.sh (and no longer mentioned in DEV.md), since desktop.mjs hardcoded the screen size anyway.
  • The DEMO_TERMINAL doc comment in seed.mjs now points at take.sh.
  • As a bonus, setup.sh now traps its own failure to delete the demo home (and the key tail in it) even when run.sh's cleanup was never armed, and DEV.md documents 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:

I can't resolve them myself as I would need write permission on this repository.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 fismif left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

@planger
planger merged commit 0c05887 into main Nov 16, 2026
6 checks passed
@planger
planger deleted the homeshell-readme-demo branch November 16, 2026 16:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants