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
12 changes: 9 additions & 3 deletions progress/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ On Paseo 0.14 and later, Progress hands agents a tool for each common command, s
| `progress_question_answer` | `question answer` |
| `progress_deliverable_add` | `deliverable add` |
| `progress_activity_add` | `activity add` |
| `progress_ticker` | `ticker set`, or `ticker clear` when the text is empty |
| `progress_ticker` | `ticker set` |
| `progress_finish` | `finish` |
| `paseo_progress` | Any command, given as the list of words you'd type after `paseo-progress` |

Expand Down Expand Up @@ -125,7 +125,7 @@ for dir in ~/.agents/skills ~/.claude/skills ~/.codex/skills; do mkdir -p "$dir"

## Recording progress

Run `paseo-progress --help` for every command, and `paseo-progress <command> --help` for one. Commands find the worktree root from the current directory.
Run `paseo-progress --help` for every command, and `paseo-progress <command> --help` for one. Commands find the worktree root from the current directory. A Claude Code subagent that works in its own checkout under `.claude/worktrees/` records on the dashboard of the worktree its Paseo agent runs in.

```sh
paseo-progress start "Loan Options snapshots" --subtitle "4 tickets"
Expand Down Expand Up @@ -154,7 +154,7 @@ paseo-progress finish "Snapshots ship for all four tables"
- Paseo keeps the question mode in its own settings, which only the plugin's server can read, so the server copies it to `~/.local/state/paseo-progress/settings.json` for the command. Without that file, for example while the plugin is off, the command uses Work around.
- Deliverable paths are stored relative to the worktree root. Web links open in Paseo's browser. Pressing an image (PNG, JPEG, GIF, WebP, up to 10 MB) or text deliverable (Markdown, text, logs, JSON, YAML, CSV; the first 256 KB) previews it in a dialog inside Paseo, which also works from a phone. Markdown shows formatted, with links and images relative to the file's own folder; **Open** there opens the file in its default app. **Open** shows only when the computer running Paseo can open files. A Linux server with no desktop can't, so there a file Paseo can't preview copies its path and says why. A video (MP4, MOV, WebM, up to 200 MB) plays in the same dialog in the desktop app, and a PDF (up to 100 MB) shows there too. When there are several files, **Previous** and **Next** step through them, and so do the left and right arrow keys. Pressing a folder lists its files in the same dialog. Press a file to preview it, or a folder inside to list that one, and **Back** returns to the list. Pressing an audio file opens it with its default app on the machine running the Paseo daemon. Pressing an HTML page opens it in a Paseo tab with Paseo's own preview, on desktop and on phones, never in your browser. The preview runs the page's own scripts but loads nothing from the web, so a report needs its CSS and images inside the file. Progress hands no other file or folder to a default app, because a script or an app would run, so pressing one copies its path. On macOS, **Open** sends text files to your default browser. Previews and **Open** work only for recorded deliverables inside the worktree; for any other file the path is copied. An HTML page or PDF opens in a Paseo tab from the path the agent recorded. The copy icon on each row copies the path.
- Several agents can share one run. When another session adds a ticket, each agent sees it at the end of its next command's output (and in `show`), and the skill has it work that ticket in order after its current one. An agent only hears about tickets added since its own last update in the run, and only once.
- Subagents record their own progress. A Claude Code subagent can call the Progress tools too, and its updates carry its parent chat's agent id. Since Paseo 0.11, an agent waiting on background subagents shows as idle, so only the subagents' updates show the work is still going. The skill has the agent give each subagent the worktree path and ticket id, and the subagent records its stages and a ticker line on that worktree's dashboard.
- Subagents record their own progress. A Claude Code subagent can call the Progress tools too, and its updates carry its parent chat's agent id. Since Paseo 0.11, an agent waiting on background subagents shows as idle, so only the subagents' updates show the work is still going. The skill has the agent give each subagent its ticket id, and the subagent records its stages and a ticker line on the agent's dashboard.
- `start` begins a fresh dashboard. Earlier runs stay in the file. Question references stay unique across runs.
- `finish "<outcome>"` closes the run once every ticket is done or skipped, no question is open, and nothing is flagged stuck; otherwise it says what is left. The run stays on the dashboard, marked Finished with its outcome, and takes no more updates, so the next agent in the worktree starts a new run instead of adding to it.

Expand All @@ -178,6 +178,12 @@ The progress file, `progress.jsonl`, holds one JSON event per line, each with a

## Changelog

### 1.14.7

- [Fixed] **Subagents record progress from their own folder.** Claude Code can give a subagent its own copy of the repo. To record progress from there, the subagent had to switch to its agent's worktree first, and Claude Code refused the command whenever it also ran git. The `paseo-progress` command now sends a subagent's progress to its agent's dashboard from the subagent's own folder, and the skill no longer tells subagents to switch folders.
- [Fixed] **A step can start in a stage.** Agents often add a step that is already under way and name its stage in the same call. Progress refused the stage, the step was never added, and every later step that waited for it failed too. `paseo-progress ticket add` and the Add ticket tool now take a stage.
- [Fixed] **An empty ticker hides it from the command too.** `paseo-progress ticker set ""` asked for text, though the ticker tool hides the line when it gets `""`. Both now hide it.

### 1.14.6

- [Fixed] **The Progress pill spins only while work is happening.** It used to show a spinner until you first opened the panel, even after every ticket was done or the agent had stopped. Now it spins while an agent in the worktree is running and tickets are left, and shows the checklist icon otherwise. On phones, the pill that stays above the message box follows the same rule.
Expand Down
4 changes: 2 additions & 2 deletions progress/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion progress/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@stevecastaneda/paseo-progress",
"version": "1.14.6",
"version": "1.14.7",
"description": "A live progress dashboard per worktree for Paseo, drawn from a file agents write with the Progress tools or the paseo-progress command.",
"keywords": [
"coding-agents",
Expand Down
41 changes: 28 additions & 13 deletions progress/server/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { isSettled, type Dashboard, type NextIds, type Ticket } from "../shared/
import { DELIVERABLE_KINDS, TICKET_STATUSES, type FileLink, type ProgressEvent } from "../shared/events.ts";
import { QUESTION_MODE_RULES, type QuestionMode } from "../shared/question-modes.ts";
import { appendProgress, InvalidEvent, readLatestRun, readProgress, type EventDraft } from "./progress-file.ts";
import { findRoot, outside } from "./paths.ts";
import { outside, progressRoot } from "./paths.ts";
import { installLauncher } from "./launcher.ts";
import { findStore, saveRunCopy } from "./store.ts";
import { readQuestionMode } from "./question-mode.ts";
Expand All @@ -23,6 +23,7 @@ export interface CliOptions {
out?: (line: string) => void;
// The Paseo agent running the command, recorded on each event it writes.
agentId?: string;
agentCwd?: string;
}

class UsageError extends Error {}
Expand Down Expand Up @@ -188,6 +189,10 @@ function shown(value: unknown) {
return typeof value === "object" ? ((value as FileLink).path ?? (value as FileLink).url) : value;
}

function clearTicker() {
return { event: { type: "ticker.clear" as const }, message: "Ticker cleared" };
}

const commands: Record<string, Command> = {
start: {
usage: `start "<title>" [--subtitle <text>] [--item-label <word>]`,
Expand All @@ -214,20 +219,27 @@ const commands: Record<string, Command> = {
},
},
"ticket add": {
usage: `ticket add "<title>" --estimate <minutes> [--status <status>] [--waits-for <id>] [--source <path or http(s) URL>[=<label>]]`,
usage: `ticket add "<title>" --estimate <minutes> [--status <status>] [--stage <name>] [--waits-for <id>] [--source <path or http(s) URL>[=<label>]]`,
summary:
"Add a ticket. Prints its id (T01, T02, ...). --waits-for names a ticket it can't start before; that is the order of work, not a blocker. --source is where the ticket is written up, like its spec file or issue link.",
options: { estimate: { type: "string" }, status: { type: "string" }, "waits-for": { type: "string" }, source: { type: "string" } },
"Add a ticket. Prints its id (T01, T02, ...). --stage names the step in progress when it starts as working, like Build. --waits-for names a ticket it can't start before; that is the order of work, not a blocker. --source is where the ticket is written up, like its spec file or issue link.",
options: {
estimate: { type: "string" },
status: { type: "string" },
stage: { type: "string" },
"waits-for": { type: "string" },
source: { type: "string" },
},
run({ positionals, values, state, cwd, root }) {
const waitsFor = values["waits-for"] === undefined ? undefined : existingTicket(state, stringOption(values["waits-for"])).id;
const title = required(positionals[0], "ticket title");
const estimateMin = minutesOption(values.estimate, "estimate");
if (estimateMin === undefined) throw new UsageError("Missing --estimate <minutes>.");
const source = values.source === undefined ? undefined : parseFile(String(values.source), cwd, root);
const stage = stringOption(values.stage)?.trim() || undefined;
const id = state.nextIds.ticket;
return {
event: { type: "ticket.add", id, title, estimateMin, status: statusOption(values.status), waitsFor, source },
message: `Added ${id}: ${title} (${formatMinutes(estimateMin)})${waitsFor ? `, waits for ${waitsFor}` : ""}${source ? `, source ${source.path ?? source.url}` : ""}`,
event: { type: "ticket.add", id, title, estimateMin, status: statusOption(values.status), stage, waitsFor, source },
message: `Added ${id}: ${title} (${formatMinutes(estimateMin)})${stage ? `, stage ${stage}` : ""}${waitsFor ? `, waits for ${waitsFor}` : ""}${source ? `, source ${source.path ?? source.url}` : ""}`,
};
},
},
Expand Down Expand Up @@ -466,18 +478,17 @@ const commands: Record<string, Command> = {
},
"ticker set": {
usage: `ticker set "<text>"`,
summary: "Show one line at the top saying what you are doing right now.",
summary: 'Show one line at the top saying what you are doing right now. Pass "" to hide it.',
run({ positionals }) {
if (positionals[0]?.trim() === "") return clearTicker();
const text = required(positionals[0], "ticker text");
return { event: { type: "ticker.set", text }, message: `Ticker: ${text}` };
},
},
"ticker clear": {
usage: `ticker clear`,
summary: "Hide the ticker line.",
run() {
return { event: { type: "ticker.clear" }, message: "Ticker cleared" };
},
run: clearTicker,
},
"stuck set": {
usage: `stuck set "<reason>" [--ticket <id>]`,
Expand Down Expand Up @@ -564,7 +575,7 @@ export async function runCli(argv: string[], options: CliOptions): Promise<numbe
return 0;
}
if (first === "show") {
const root = findRoot(options.cwd);
const root = progressRoot(options.cwd, options.agentCwd);
const store = await findStore(root);
const { dashboard } = await readProgress(store.directory, now());
const added = addedByOthersText(addedByOthers(await readLatestRun(store.directory), dashboard, options.agentId), dashboard);
Expand Down Expand Up @@ -593,7 +604,7 @@ export async function runCli(argv: string[], options: CliOptions): Promise<numbe
} catch (error) {
throw new UsageError((error as Error).message);
}
const root = findRoot(options.cwd);
const root = progressRoot(options.cwd, options.agentCwd);
const store = await findStore(root);
const mode = await readQuestionMode();
const message = await appendProgress(
Expand Down Expand Up @@ -631,7 +642,11 @@ function isMain(): boolean {
}

if (isMain()) {
runCli(process.argv.slice(2), { cwd: process.cwd(), agentId: process.env.PASEO_AGENT_ID || undefined }).then(
runCli(process.argv.slice(2), {
cwd: process.cwd(),
agentId: process.env.PASEO_AGENT_ID || undefined,
agentCwd: process.env.PASEO_AGENT_CWD || undefined,
}).then(
(code) => {
process.exitCode = code;
},
Expand Down
14 changes: 13 additions & 1 deletion progress/server/paths.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { existsSync } from "node:fs";
import { dirname, isAbsolute, join, resolve, sep } from "node:path";
import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";

// Whether a path from relative(root, target) leaves the root. "..notes" is a
// name inside it, not a step out.
Expand Down Expand Up @@ -32,3 +32,15 @@ export function findRoot(cwd: string): string {
directory = parent;
}
}

// The worktree a command records progress for. Claude Code gives an isolated
// subagent its own checkout at .claude/worktrees/<name>, in the repo's main
// checkout unless a WorktreeCreate hook moves it. The user watches the
// dashboard of the Paseo agent's workspace, which Paseo names in
// PASEO_AGENT_CWD, so progress from a subagent's checkout goes there.
export function progressRoot(cwd: string, agentCwd: string | undefined): string {
const root = findRoot(cwd);
const folder = dirname(root);
const subagentCheckout = basename(folder) === "worktrees" && basename(dirname(folder)) === ".claude";
return agentCwd && subagentCheckout ? findRoot(agentCwd) : root;
}
60 changes: 60 additions & 0 deletions progress/server/progress.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -415,6 +415,66 @@ test("commands find the worktree root from a subdirectory", async (t) => {
assert.equal((await w.dashboard()).dashboard.run?.title, "From below");
});

async function checkout(parent: string, ...folders: string[]) {
const directory = join(parent, ...folders);
await mkdir(join(directory, "shots"), { recursive: true });
await git(directory, "init", "-q");
await writeFile(join(directory, "shots", "after.png"), "");
return directory;
}

// Claude Code refuses an isolated subagent's command that changes to the
// agent's workspace and then runs git, so the subagent records from where it is.
test("a subagent in its own checkout records on its agent's dashboard", async (t) => {
const w = await worktree(t);
const main = await worktree(t);
const output: string[] = [];
const runIn = (cwd: string, agentCwd: string | undefined, ...argv: string[]) =>
runCli(argv, { cwd, agentCwd, now: () => minutes(0), out: (line) => output.push(line) });
const inWorkspace = await checkout(w.directory, ".claude", "worktrees", "agent-1");
const inMainCheckout = await checkout(main.directory, ".claude", "worktrees", "agent-2");
const vendored = await checkout(w.directory, "vendor", "library");
await w.run("start", "Run");
await w.run("ticket", "add", "Ticket 01: Button", "--estimate", "30");

assert.equal(await runIn(inWorkspace, w.directory, "ticket", "update", "T01", "--stage", "Build"), 0, output.join("\n"));
assert.equal(await runIn(inWorkspace, w.directory, "deliverable", "add", "After", "shots/after.png"), 0, output.join("\n"));
assert.equal(await runIn(inMainCheckout, w.directory, "ticker", "set", "Reviewing"), 0, output.join("\n"));
const { dashboard } = await w.dashboard();
assert.equal(dashboard.tickets[0].stage, "Build");
assert.equal(
dashboard.deliverables[0].path,
join(".claude", "worktrees", "agent-1", "shots", "after.png"),
"a path from the checkout opens from the workspace",
);
assert.equal(dashboard.ticker?.text, "Reviewing");
output.length = 0;
await runIn(inMainCheckout, w.directory, "show");
assert.equal(output.join("\n").split("\n")[0], `Worktree: ${w.directory}`);

assert.equal(await runIn(vendored, w.directory, "start", "Another repo"), 0, "a checkout that isn't a subagent's keeps its own dashboard");
assert.equal(await runIn(inMainCheckout, undefined, "start", "Outside Paseo"), 0, "so does a subagent's checkout outside Paseo");
assert.equal((await readProgress(outsideDirectory(vendored), minutes(0))).dashboard.run?.title, "Another repo");
assert.equal((await readProgress(outsideDirectory(inMainCheckout), minutes(0))).dashboard.run?.title, "Outside Paseo");
assert.equal((await w.dashboard()).dashboard.run?.title, "Run");
});

test("a ticket can start in a stage, and an empty ticker hides it", async (t) => {
const w = await worktree(t);
await w.run("start", "Run");
const added = await w.run("ticket", "add", "Step 01: Reproduce it", "--estimate", "20", "--status", "working", "--stage", "Verify");
assert.equal(added.text, "Added T01: Step 01: Reproduce it (20m), stage Verify");
const [ticket] = (await w.dashboard()).dashboard.tickets;
assert.deepEqual(
{ stage: ticket.stage, stageSince: ticket.stageSince, history: ticket.history },
{ stage: "Verify", stageSince: minutes(0).toISOString(), history: [{ at: minutes(0).toISOString(), status: "working", stage: "Verify" }] },
);
await w.run("ticker", "set", "Reproducing");
assert.equal((await w.run("ticker", "set", "")).text, "Ticker cleared");
assert.equal((await w.dashboard()).dashboard.ticker, null);
assert.match((await w.run("ticker", "set")).text, /^Missing ticker text\./);
});

// A Paseo project registered at a subfolder of the repo: the workspace
// directory is <worktree>/apps/client, but the agent writes at the root.
test("a workspace below the worktree root reads the root's progress and attachments", async (t) => {
Expand Down
8 changes: 8 additions & 0 deletions progress/server/tool.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,14 @@ test("the note after a question names the answer tool's fields", () => {
for (const field of fields) assert.match(ANSWER_NOTE, new RegExp(`\\b${field} is `));
});

test("a ticket added through the tool can start in a stage", async (t) => {
const w = await worktree(t);
await w.call("progress_start", { title: "Bug" });
const added = await w.call("progress_ticket_add", { title: "Step 01: Reproduce it", estimateMinutes: 20, status: "working", stage: "Verify" });
assert.equal(added.text, "Added T01: Step 01: Reproduce it (20m), stage Verify");
assert.equal((await w.dashboard()).tickets[0].stage, "Verify");
});

test("the skill loads every tool in one search", async () => {
const skill = await readFile(new URL("../skills/paseo-progress/SKILL.md", import.meta.url), "utf8");
const query = /^select:(.+)$/m.exec(skill)?.[1].split(",");
Expand Down
Loading
Loading