Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@ agent session, whether it runs on your machine or in an Eclipse Enclave containe
them all in one web UI or desktop window: what each agent is doing, which ones wait for you, and
a way to answer them.

![HomeShell starting an agent session and answering one that waits for input](docs/assets/homeshell-demo.gif)
![HomeShell with agents at work in four projects: a new worktree gets an Enclave session that is
briefed in a terminal, another agent's question is answered, the finished feature is reviewed in its
folder, and an old conversation is continued](docs/assets/homeshell-demo.gif)

Docs: start at the [docs index](docs/README.md).

Expand Down
36 changes: 36 additions & 0 deletions docs/DEV.md
Original file line number Diff line number Diff line change
Expand Up @@ -305,6 +305,42 @@ The rules for which doc a change updates, and how to write it, are in

- The PR template (`.github/pull_request_template.md`) asks for tests, docs and changelog.

### Demo GIF

`scripts/demo-video/run.sh` re-records `docs/assets/homeshell-demo.gif`, the README's demo, and
`homeshell-demo.mp4` next to it, the same cut at full size. Real Claude Code agents do the work.

```sh
make build
ANTHROPIC_API_KEY=... scripts/demo-video/run.sh
```

- **Needs:** Linux with Xvfb, metacity, gnome-terminal, dbus-run-session, xdotool, xwininfo,
ffmpeg, python3 and the DejaVu fonts; podman with the `enclave` CLI; `claude` on `PATH`;
Playwright's Chromium (`make setup`).
- **Costs:** the agents' model use is billed to `ANTHROPIC_API_KEY`. Why a key: a copy of your
Claude login would share its rotating refresh token with your own installation.
- **Demo home:** `setup.sh` builds a throwaway `HOME` with Claude Code's first-run screens already
answered, an Enclave config with only the built-in features plus `playwright-mcp`, and the
projects in `projects/`, copied to `DEMO_PROJECTS`. Your own `~/.claude`, Enclave config and
HomeShell data are only read. Why outside `$HOME`: the paths show in the video.
- **Take:** `xsession.sh` runs a virtual desktop; `take.sh` starts a daemon there, `seed.mjs`
gives it projects, worktrees and finished sessions (`layout.json`), and `story.mjs` plays the
story with the real X pointer (`desktop.mjs`) while ffmpeg records the screen.
- **Cut:** `story.mjs` marks where it waits on agents; `encode.sh` speeds those stretches up to a
few seconds with a badge. The container's start and waits for a notification to clear are cut.
- **Re-takes:** agents differ from run to run, so look at the result. A take that times out
prints the waiting session's last screen.
- **Cleanup:** deletes the demo home, which holds the key (also when `setup.sh` fails), then
stops the demo's daemon, bridges, desktop and the containers of the demo projects, by exact
match only.
- **Wipes:** `DEMO_ROOT` and `DEMO_PROJECTS` are deleted at the start of a run. A non-empty folder
without the `.homeshell-demo` mark a previous run left is refused.
- Env: `DEMO_PROJECTS` (default `/tmp/code`), `DEMO_ROOT` (default `/tmp/homeshell-demo`),
`DEMO_PORT`, `DEMO_DISPLAY` (must be free), `DEMO_KEEP=1` (keep the raw take and the daemon's
data), `DEMO_SKIP_CONTINUE=1` (end before the old conversation is continued), `DEMO_WIDTH`,
`DEMO_FPS`, `DEMO_FAST_SECONDS`, `FFMPEG`.

## CI

`.github/workflows/ci.yml` runs on every pull request and on pushes to `main`. A new push to a
Expand Down
Binary file modified docs/assets/homeshell-demo.gif

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.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/assets/homeshell-demo.mp4

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.

Binary file not shown.
103 changes: 103 additions & 0 deletions scripts/demo-video/api.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
// The demo daemon's API, for seeding and for waiting on agents while recording.
import { readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const here = dirname(fileURLToPath(import.meta.url));
export const layout = JSON.parse(readFileSync(join(here, 'layout.json'), 'utf8'));
const TOKEN = process.env.HOMESHELL_API_TOKEN ?? 'demo-token';
let base = process.env.DEMO_URL ?? 'http://127.0.0.1:8431';

export const setBase = (url) => {
base = url;
};
export const pause = (ms) => new Promise((r) => setTimeout(r, ms));

export async function api(method, path, body) {
const res = await fetch(`${base}/api${path}`, {
method,
headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
body: body === undefined ? undefined : JSON.stringify(body),
});
if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${await res.text()}`);
return res.status === 204 ? null : res.json().catch(() => null);
}

export const projects = async () => (await api('GET', '/projects')).projects;
export const project = async (name) => (await projects()).find((p) => p.name === name);
export const wsPath = (p, ws) => `/projects/${p.id}/workstreams/${ws.id}`;

export async function workstream(projectName, wsName) {
const p = await project(projectName);
const ws = p?.workstreams.find((w) => w.name === wsName);
if (!ws) throw new Error(`no workstream ${projectName}/${wsName}`);
return { p, ws };
}

/** Every session with its project and workstream names. */
export async function allSessions() {
const out = [];
for (const p of await projects())
for (const w of p.workstreams) for (const s of w.sessions ?? []) out.push({ ...s, project: p.name, ws: w.name });
return out;
}

/** Polls until `poll()` returns something truthy; throws `what` after `timeoutMs`. */
export async function until(what, poll, timeoutMs = 120_000, everyMs = 500) {
const end = Date.now() + timeoutMs;
for (;;) {
const v = await poll();
if (v) return v;
if (Date.now() > end) throw new Error(`timed out after ${timeoutMs / 1000}s: ${what}`);
await pause(everyMs);
}
}

/** The session of `projectName/wsName` matching `pick` (default: the newest), once it is in `states`. */
export async function waitForSession(projectName, wsName, states, { timeoutMs = 300_000, pick } = {}) {
let last;
try {
return await until(
`${projectName}/${wsName} session in ${states}`,
async () => {
const list = (await allSessions()).filter((s) => s.project === projectName && s.ws === wsName && !s.placeholder);
last = pick ? list.find(pick) : list.at(-1);
return last && states.includes(last.state) ? last : null;
},
timeoutMs,
);
} catch (err) {
err.message += `\nlast state: ${last?.state}\nlast preview:\n${last?.preview ?? '(none)'}`;
throw err;
}
}

/** Creates a worktree workstream named `name` and waits until it exists. */
export async function addWorktree(projectName, name) {
const p = await project(projectName);
if (!p.workstreams.some((w) => w.name === name))
await api('POST', `/projects/${p.id}/workstreams`, { providerId: 'core', name, config: { strategy: 'worktree' } });
return until(`worktree ${projectName}/${name}`, async () => {
const ws = (await project(projectName)).workstreams.find((w) => w.name === name);
if (ws?.status?.kind === 'error') throw new Error(`creating ${name}: ${ws.status.message}`);
return ws && !ws.placeholder && ws.state !== 'creating' && !ws.id.startsWith('creating-') ? ws : null;
});
}

/** Starts a Local System Claude Code session with `prompt` in `projectName/wsName`. */
export async function startClaude(projectName, wsName, prompt, config = {}) {
const { p, ws } = await workstream(projectName, wsName);
const config_ = { model: 'claude-sonnet-5', permissionMode: 'auto', prompt, ...config };
await api('POST', `${wsPath(p, ws)}/sessions`, { providerId: 'local', optionId: 'claude', config: config_ });
}

export async function sessionAction(s, action, body) {
const { p, ws } = await workstream(s.project, s.ws);
return api('POST', `${wsPath(p, ws)}/sessions/${encodeURIComponent(s.id)}/${action}`, body);
}

/** Renames `s` in HomeShell, as a user does from the row's menu. */
export async function rename(s, title) {
const { p, ws } = await workstream(s.project, s.ws);
await api('PATCH', `${wsPath(p, ws)}/sessions/${encodeURIComponent(s.id)}`, { title });
}
179 changes: 179 additions & 0 deletions scripts/demo-video/desktop.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
// The virtual desktop for the README demo: a HomeShell window in Chromium, the real X pointer
// moved and clicked with xdotool (so it shows in the recording and crosses windows), and ffmpeg
// capturing the X screen. Expects DISPLAY to be the demo's Xvfb (xsession.sh).
import { execFileSync, spawn } from 'node:child_process';
import { createRequire } from 'node:module';
import { mkdtempSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const here = dirname(fileURLToPath(import.meta.url));
const require = createRequire(join(here, '../../webapp/apps/web-e2e/package.json'));
const { chromium } = require('@playwright/test');

export const SCREEN = { width: 1280, height: 800 };
export const pause = (ms) => new Promise((r) => setTimeout(r, ms));
const xdotool = (...args) => execFileSync('xdotool', args.map(String), { encoding: 'utf8' }).trim();

// -- Browser ------------------------------------------------------------------------------------

/** HomeShell in a Chromium app window covering the screen, signed in with the token cookie. */
export async function openBrowser(baseUrl, token) {
const context = await chromium.launchPersistentContext(mkdtempSync(join(tmpdir(), 'hs-demo-chromium-')), {
headless: false,
viewport: null,
colorScheme: 'dark',
ignoreDefaultArgs: ['--enable-automation'],
// X11 explicitly: with WAYLAND_DISPLAY set Chromium would open on the user's own desktop.
env: { ...process.env, WAYLAND_DISPLAY: '' },
args: [
`--app=${baseUrl}`,
'--ozone-platform=x11',
'--window-position=0,0',
`--window-size=${SCREEN.width},${SCREEN.height}`,
],
});
await context.addCookies([{ name: 'hs_api_token', value: token, url: baseUrl }]);
const page = context.pages()[0] ?? (await context.waitForEvent('page'));
await page.goto(baseUrl);
return { context, page };
}

/** Where the page's viewport starts on the screen. */
async function viewportOrigin(page) {
return page.evaluate(() => ({
x: window.screenX + (window.outerWidth - window.innerWidth) / 2,
y: window.screenY + window.outerHeight - window.innerHeight,
}));
}

// -- Pointer and keyboard ----------------------------------------------------------------------

let pointer = { x: SCREEN.width / 2, y: SCREEN.height / 2 };

/** Glides the X pointer to a screen point, easing in and out, about 900 px per second. */
export async function glide(x, y) {
const from = pointer;
const distance = Math.hypot(x - from.x, y - from.y);
const steps = Math.max(8, Math.round(distance / 22));
for (let i = 1; i <= steps; i++) {
const t = i / steps;
const e = t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2;
xdotool('mousemove', Math.round(from.x + (x - from.x) * e), Math.round(from.y + (y - from.y) * e));
await pause(16);
}
pointer = { x, y };
}

/** Screen point at the centre of `locator`, or at `offset` from its top left. */
export async function screenPoint(page, locator, offset) {
await locator.waitFor({ state: 'visible' });
await locator.scrollIntoViewIfNeeded();
const box = await locator.boundingBox();
const origin = await viewportOrigin(page);
return {
x: Math.round(origin.x + box.x + (offset ? offset.x : box.width / 2)),
y: Math.round(origin.y + box.y + (offset ? offset.y : box.height / 2)),
};
}

export async function pointTo(page, locator, offset) {
const p = await screenPoint(page, locator, offset);
await glide(p.x, p.y);
}

export async function clickAt(x, y) {
await glide(x, y);
await pause(220);
xdotool('click', 1);
await pause(120);
}

export async function click(page, locator, offset) {
const p = await screenPoint(page, locator, offset);
await clickAt(p.x, p.y);
}

/** Types into whatever has the keyboard focus, like a person (xdotool type). */
export async function typeText(text, delayMs = 45) {
xdotool('type', '--delay', delayMs, text);
}

export const key = (...names) => xdotool('key', ...names);

// -- Windows -----------------------------------------------------------------------------------

/** A window's content area on screen (xwininfo; xdotool's geometry is off by the frame). */
function geometry(id) {
const info = execFileSync('xwininfo', ['-id', id], { encoding: 'utf8' });
const num = (label) => Number(info.match(new RegExp(`${label}:\\s+(-?\\d+)`))[1]);
return { id, x: num('Absolute upper-left X'), y: num('Absolute upper-left Y'), width: num('Width'), height: num('Height') };
}

/** Every window id currently mapped, to tell a new one apart. */
export function windowIds() {
try {
return new Set(xdotool('search', '--onlyvisible', '--name', '.').split('\n').filter(Boolean));
} catch {
return new Set(); // xdotool exits 1 when nothing matches
}
}

/** The first sizeable window mapped after `before` (windowIds()), once it has stopped moving. */
export async function waitNewWindow(before, timeoutMs = 30_000) {
const end = Date.now() + timeoutMs;
let last;
for (;;) {
const id = [...windowIds()].find((w) => !before.has(w) && geometry(w).width > 200);
if (id) {
const geo = geometry(id);
if (last && JSON.stringify(last) === JSON.stringify(geo)) return geo;
last = geo;
}
if (Date.now() > end) throw new Error('no new window opened');
await pause(250);
}
}

/** Waits until window `win` is gone. */
export async function waitGone(win, timeoutMs = 10_000) {
const end = Date.now() + timeoutMs;
while (windowIds().has(win.id)) {
if (Date.now() > end) throw new Error(`window ${win.id} did not close`);
await pause(150);
}
}

/** Clicks the × of a window's title bar (metacity's frame, above the content area). */
export async function closeWindow(win) {
await clickAt(win.x + win.width - 19, win.y - 20);
await waitGone(win);
}

// -- Capture -----------------------------------------------------------------------------------

/** Records the X screen to `file` until the returned stop() is awaited. */
export function startCapture(file, framerate = 25) {
const ff = spawn(
process.env.FFMPEG ?? 'ffmpeg',
['-v', 'error', '-y', '-f', 'x11grab', '-draw_mouse', '1', '-framerate', String(framerate),
'-video_size', `${SCREEN.width}x${SCREEN.height}`, '-i', process.env.DISPLAY,
'-c:v', 'libx264', '-preset', 'ultrafast', '-crf', '0', '-pix_fmt', 'yuv444p', file],
{ stdio: ['pipe', 'inherit', 'inherit'] },
);
const started = Date.now();
const timeline = [{ t: 0, mode: 'normal', label: 'start' }];
return {
/** From now on the video plays as `mode`: normal, fast (sped up) or cut (dropped). */
mark(mode, label = '') {
timeline.push({ t: (Date.now() - started) / 1000, mode, label });
},
async stop(timelineFile) {
timeline.push({ t: (Date.now() - started) / 1000, mode: 'end', label: 'end' });
ff.stdin.write('q');
await new Promise((r) => ff.on('exit', r));
writeFileSync(timelineFile, JSON.stringify(timeline, null, 1));
},
};
}
56 changes: 56 additions & 0 deletions scripts/demo-video/encode.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
#!/usr/bin/env bash
# Turns a take (story.mjs) into the README GIF and an MP4 of the same cut at full size. The
# timeline marks stretches: "normal" plays at 1x, "fast" (waiting on an agent) is sped up to at
# most DEMO_FAST_SECONDS with a badge, "cut" is dropped.
#
# Usage: scripts/demo-video/encode.sh <raw.mkv> <timeline.json> <out.gif> [out.mp4]
# Env: DEMO_WIDTH (GIF width, default 1100), DEMO_FPS (GIF frame rate, default 10),
# DEMO_FAST_SECONDS (default 3), FFMPEG (default ffmpeg).
set -euo pipefail

raw=${1:?raw video}
timeline=${2:?timeline}
gif=${3:?output gif}
mp4=${4:-${gif%.gif}.mp4}
ffmpeg=${FFMPEG:-ffmpeg}
ffprobe=${ffmpeg%ffmpeg}ffprobe
width=${DEMO_WIDTH:-1100}
fps=${DEMO_FPS:-10}
fast=${DEMO_FAST_SECONDS:-3}
font=$(fc-match -f '%{file}' 'DejaVu Sans:bold')
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT

# The cut, as a filter graph ending in [cat]: every kept stretch, sped up where marked.
python3 - "$timeline" "$fast" "$font" >"$work/cut" <<'EOF'
import json, sys
marks = json.load(open(sys.argv[1]))
fast, font = float(sys.argv[2]), sys.argv[3]
segments = []
for a, b in zip(marks, marks[1:]):
if a["mode"] != "cut" and b["t"] - a["t"] > 0.05:
segments.append((a["t"], b["t"], a["mode"]))
parts = [f"[0:v]split={len(segments)}" + "".join(f"[s{i}]" for i in range(len(segments)))]
for i, (start, end, mode) in enumerate(segments):
chain = f"[s{i}]trim=start={start:.3f}:end={end:.3f},setpts=PTS-STARTPTS"
if mode == "fast":
speed = max(4.0, (end - start) / fast)
chain += (f",setpts=PTS/{speed:.3f},drawtext=fontfile='{font}':text='>> {speed:.0f}x':fontsize=26"
":fontcolor=white:box=1:boxcolor=0x0d9488@0.9:boxborderw=10:x=w-tw-28:y=h-th-28")
parts.append(chain + f"[v{i}]")
parts.append("".join(f"[v{i}]" for i in range(len(segments))) + f"concat=n={len(segments)}:v=1:a=0[cat]")
print(";\n".join(parts), end="")
EOF

{ cat "$work/cut"; echo ";"
echo "[cat]fps=$fps,scale=$width:-1:flags=lanczos,split[a][b];"
echo "[a]palettegen=max_colors=192:stats_mode=diff[p];"
echo "[b][p]paletteuse=dither=bayer:bayer_scale=4:diff_mode=rectangle"; } >"$work/gif"
{ cat "$work/cut"; echo ";[cat]fps=25,format=yuv420p"; } >"$work/mp4"

"$ffmpeg" -v error -y -i "$raw" -filter_complex_script "$work/gif" -loop 0 "$gif"
"$ffmpeg" -v error -y -i "$raw" -filter_complex_script "$work/mp4" -c:v libx264 -crf 20 -preset slow \
-movflags +faststart "$mp4"
for f in "$gif" "$mp4"; do
echo "wrote $f ($(du -h "$f" | cut -f1), $("$ffprobe" -v error -show_entries format=duration -of csv=p=0 "$f")s)"
done
Loading
Loading