@dorywoof/agentreplay 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +42 -0
- package/bin/agentreplay.js +39 -3
- package/package.json +5 -2
- package/skills/replay/SKILL.md +76 -0
- package/src/install-skill.js +88 -0
package/README.md
CHANGED
|
@@ -49,6 +49,47 @@ npx @dorywoof/agentreplay --agents # which agents were found on this machine
|
|
|
49
49
|
|
|
50
50
|
Requires Node 18+. Nothing is uploaded anywhere: everything happens on your machine.
|
|
51
51
|
|
|
52
|
+
### As a Claude Code plugin
|
|
53
|
+
|
|
54
|
+
Replay the session you're in without leaving Claude Code:
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
/plugin install agentreplay --marketplace dorywoof/agentreplay
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
On older Claude Code versions, use two steps instead:
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
/plugin marketplace add dorywoof/agentreplay
|
|
64
|
+
/plugin install agentreplay@agentreplay
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Then type `/agentreplay:replay`, or just ask *"make a replay of this session"*. Claude runs the CLI for you, writes the HTML next to your project and tells you what was redacted. Arguments pass through, for example `/agentreplay:replay --list`.
|
|
68
|
+
|
|
69
|
+
### As a skill in Codex, Gemini CLI, OpenCode, Copilot, Cursor…
|
|
70
|
+
|
|
71
|
+
Most agents now read the open [Agent Skills](https://agentskills.io) format (`SKILL.md`). One command installs the replay skill into every agent it finds on your machine:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
npx @dorywoof/agentreplay install-skill
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
| Agent | Installed to |
|
|
78
|
+
|---|---|
|
|
79
|
+
| Shared folder several agents read | `~/.agents/skills/agentreplay/` (always) |
|
|
80
|
+
| Claude Code | `~/.claude/skills/agentreplay/` |
|
|
81
|
+
| Codex | `~/.codex/skills/agentreplay/` |
|
|
82
|
+
| Gemini CLI | `~/.gemini/skills/agentreplay/` |
|
|
83
|
+
| Qwen Code | `~/.qwen/skills/agentreplay/` |
|
|
84
|
+
| OpenCode | `~/.config/opencode/skills/agentreplay/` |
|
|
85
|
+
| GitHub Copilot | `~/.copilot/skills/agentreplay/` |
|
|
86
|
+
| Cursor | `~/.cursor/skills/agentreplay/` |
|
|
87
|
+
| Windsurf, Amp, Goose | their own `skills/` folders |
|
|
88
|
+
|
|
89
|
+
Folders are only written for agents that are installed (`--force` writes all of them). `--agent codex` limits it to one agent, `--project` installs into the current repo instead (`.agents/skills`, `.claude/skills`, …) so your whole team gets it, and `uninstall-skill` removes it again. Restart the agent afterwards, then ask it to *"make a replay of this session"*.
|
|
90
|
+
|
|
91
|
+
> Skill folder locations differ between agents and versions. If your agent doesn't pick the skill up, copy [`skills/replay/SKILL.md`](skills/replay/SKILL.md) into the folder its docs name.
|
|
92
|
+
|
|
52
93
|
### Where sessions live
|
|
53
94
|
|
|
54
95
|
Sessions are found automatically. You can also pass any file directly.
|
|
@@ -77,6 +118,7 @@ Sessions are found automatically. You can also pass any file directly.
|
|
|
77
118
|
```
|
|
78
119
|
-o, --out <file> output HTML path (default: ./replay-<id>.html)
|
|
79
120
|
-a, --agent <name> only one agent (see the table above)
|
|
121
|
+
-s, --session <id> replay the session whose id / file name matches
|
|
80
122
|
-t, --title <text> override the replay title
|
|
81
123
|
--no-thinking hide thinking / reasoning blocks
|
|
82
124
|
--no-redact keep secrets, e-mails and home paths (not for sharing!)
|
package/bin/agentreplay.js
CHANGED
|
@@ -8,6 +8,7 @@ import { createRedactor } from '../src/redact.js';
|
|
|
8
8
|
import { computeStats } from '../src/stats.js';
|
|
9
9
|
import { loadPricing } from '../src/pricing.js';
|
|
10
10
|
import { renderHtml } from '../src/render.js';
|
|
11
|
+
import { installSkill, uninstallSkill } from '../src/install-skill.js';
|
|
11
12
|
|
|
12
13
|
const HELP = `
|
|
13
14
|
agentreplay — turn an AI coding session into a shareable replay
|
|
@@ -17,7 +18,13 @@ Usage
|
|
|
17
18
|
agentreplay <session.jsonl> replay a specific log file
|
|
18
19
|
agentreplay --list list recent sessions
|
|
19
20
|
agentreplay --pick 3 replay #3 from --list
|
|
21
|
+
agentreplay --session <id> replay the session whose id / file name matches
|
|
20
22
|
agentreplay --agents show supported agents and what was found
|
|
23
|
+
agentreplay install-skill add a "replay" skill to every agent on this machine
|
|
24
|
+
(Claude Code, Codex, Gemini CLI, OpenCode, Copilot,
|
|
25
|
+
Cursor…). --project installs into the current repo,
|
|
26
|
+
--agent <name> limits it to one agent.
|
|
27
|
+
agentreplay uninstall-skill remove it again
|
|
21
28
|
|
|
22
29
|
Options
|
|
23
30
|
-o, --out <file> output HTML path (default: ./replay-<id>.html)
|
|
@@ -42,6 +49,9 @@ const { values: opts, positionals } = parseArgs({
|
|
|
42
49
|
list: { type: 'boolean', short: 'l' },
|
|
43
50
|
agents: { type: 'boolean' },
|
|
44
51
|
pick: { type: 'string', short: 'p' },
|
|
52
|
+
session: { type: 'string', short: 's' },
|
|
53
|
+
project: { type: 'boolean' },
|
|
54
|
+
force: { type: 'boolean' },
|
|
45
55
|
'no-thinking': { type: 'boolean' },
|
|
46
56
|
'no-redact': { type: 'boolean' },
|
|
47
57
|
'keep-paths': { type: 'boolean' },
|
|
@@ -69,6 +79,22 @@ function ago(ms) {
|
|
|
69
79
|
|
|
70
80
|
function main() {
|
|
71
81
|
if (opts.help) return console.log(HELP);
|
|
82
|
+
|
|
83
|
+
if (positionals[0] === 'install-skill' || positionals[0] === 'uninstall-skill') {
|
|
84
|
+
const project = opts.project ? process.cwd() : null;
|
|
85
|
+
const results =
|
|
86
|
+
positionals[0] === 'install-skill'
|
|
87
|
+
? installSkill({ project, only: opts.agent, force: opts.force })
|
|
88
|
+
: uninstallSkill({ project });
|
|
89
|
+
const done = results.filter((r) => r.status !== 'skipped');
|
|
90
|
+
for (const r of done) console.log(`${bold('✓')} ${r.agent.padEnd(20)} ${dim(r.status.padEnd(9))} ${r.file}`);
|
|
91
|
+
const skipped = results.filter((r) => r.status === 'skipped').map((r) => r.agent);
|
|
92
|
+
if (skipped.length) console.log(dim(` not installed (agent not found): ${skipped.join(', ')}. Use --force to install anyway.`));
|
|
93
|
+
if (!done.length) console.log(positionals[0] === 'install-skill' ? 'Nothing installed.' : 'No agentreplay skill found to remove.');
|
|
94
|
+
else if (positionals[0] === 'install-skill') console.log(`\nRestart your agent, then ask it to ${bold('"make a replay of this session"')} (in Claude Code: ${bold('/agentreplay')}).`);
|
|
95
|
+
return;
|
|
96
|
+
}
|
|
97
|
+
|
|
72
98
|
if (opts.agent && !PARSERS[opts.agent]) fail(`unknown agent "${opts.agent}" (one of: ${Object.keys(PARSERS).join(', ')})`);
|
|
73
99
|
|
|
74
100
|
if (opts.agents) {
|
|
@@ -102,9 +128,19 @@ function main() {
|
|
|
102
128
|
} else {
|
|
103
129
|
const sessions = listSessions({ agent: opts.agent });
|
|
104
130
|
if (!sessions.length) fail('no agent sessions found on this machine. Pass a log file path instead.');
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
131
|
+
let chosen = null;
|
|
132
|
+
const wanted = (opts.session || '').trim();
|
|
133
|
+
// An unexpanded "${CLAUDE_SESSION_ID}" or an unknown id falls back to the newest session.
|
|
134
|
+
if (wanted && !wanted.includes('$')) {
|
|
135
|
+
chosen = sessions.find((s) => path.basename(s.file).includes(wanted) || s.file.endsWith('#' + wanted));
|
|
136
|
+
if (!chosen) console.error(dim(`session "${wanted}" not found — using the most recent one`));
|
|
137
|
+
}
|
|
138
|
+
if (!chosen) {
|
|
139
|
+
const idx = opts.pick ? Number(opts.pick) - 1 : 0;
|
|
140
|
+
if (!sessions[idx]) fail(`no session #${opts.pick} — run with --list to see what's available`);
|
|
141
|
+
chosen = sessions[idx];
|
|
142
|
+
}
|
|
143
|
+
({ file, agent } = chosen);
|
|
108
144
|
}
|
|
109
145
|
|
|
110
146
|
let session = PARSERS[agent].parse(file);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dorywoof/agentreplay",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Turn any AI coding agent session (Claude Code, Codex, Gemini CLI, OpenCode, Cline, Roo, Copilot CLI, Aider, …) into a shareable, video-like HTML replay with cost stats and secret redaction.",
|
|
5
5
|
"homepage": "https://github.com/dorywoof/agentreplay#readme",
|
|
6
6
|
"repository": {
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
"files": [
|
|
18
18
|
"bin",
|
|
19
19
|
"src",
|
|
20
|
+
"skills",
|
|
20
21
|
"README.md",
|
|
21
22
|
"LICENSE"
|
|
22
23
|
],
|
|
@@ -46,7 +47,9 @@
|
|
|
46
47
|
"amp",
|
|
47
48
|
"aider",
|
|
48
49
|
"chat-log",
|
|
49
|
-
"transcript-viewer"
|
|
50
|
+
"transcript-viewer",
|
|
51
|
+
"claude-code-plugin",
|
|
52
|
+
"claude-skill"
|
|
50
53
|
],
|
|
51
54
|
"license": "MIT"
|
|
52
55
|
}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: replay
|
|
3
|
+
description: Turn the current coding-agent session into a shareable, video-like HTML replay with diffs, tool calls, token/cost stats and automatic secret redaction. Use when the user asks to replay, share, export, record or show off what was done in this session, or asks for a replay of an earlier Claude Code, Codex, Gemini CLI, OpenCode, Cline, Roo, Copilot CLI, Qwen, Amp or Aider session.
|
|
4
|
+
argument-hint: "[--list | --pick N | path/to/log] [--title \"…\"] [--no-thinking]"
|
|
5
|
+
allowed-tools: Bash(npx -y @dorywoof/agentreplay*), Bash(npx @dorywoof/agentreplay*)
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Replay this session
|
|
9
|
+
|
|
10
|
+
agentreplay is a zero-dependency CLI on npm (`@dorywoof/agentreplay`). It reads
|
|
11
|
+
agent session logs from disk and writes one self-contained HTML file that plays
|
|
12
|
+
the session back like a video. It runs locally and uploads nothing. It works the
|
|
13
|
+
same no matter which agent is running this skill.
|
|
14
|
+
|
|
15
|
+
## Default: replay the current session
|
|
16
|
+
|
|
17
|
+
Run this in the user's shell, with `<agent>` set to the agent you are:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npx -y @dorywoof/agentreplay@latest --agent <agent> -o agentreplay.html
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
| You are | `<agent>` |
|
|
24
|
+
|---|---|
|
|
25
|
+
| Claude Code | `claude` (also add `--session "${CLAUDE_SESSION_ID}"`) |
|
|
26
|
+
| OpenAI Codex | `codex` |
|
|
27
|
+
| Gemini CLI | `gemini` |
|
|
28
|
+
| Qwen Code | `qwen` |
|
|
29
|
+
| OpenCode | `opencode` |
|
|
30
|
+
| GitHub Copilot CLI | `copilot` |
|
|
31
|
+
| Cline / Roo Code / Kilo Code | `cline` / `roo` / `kilo` |
|
|
32
|
+
| Amp | `amp` |
|
|
33
|
+
| Aider | `aider` |
|
|
34
|
+
| Not sure | leave `--agent` out: the newest session of any agent is used |
|
|
35
|
+
|
|
36
|
+
- The session being written right now is the newest log of that agent, so
|
|
37
|
+
this picks it up without an id. If a `--session` value is empty or not found,
|
|
38
|
+
the CLI falls back to the newest session by itself.
|
|
39
|
+
- Write the file in the current working directory unless the user names
|
|
40
|
+
another place; use a more descriptive file name when there is an obvious
|
|
41
|
+
one. The file opens in the browser; add `--no-open` if the user asked not to
|
|
42
|
+
open it or there is no desktop.
|
|
43
|
+
- Add `--title "…"` when the session has an obvious one-line summary.
|
|
44
|
+
|
|
45
|
+
## Other requests
|
|
46
|
+
|
|
47
|
+
| User wants | Add |
|
|
48
|
+
|---|---|
|
|
49
|
+
| Choose an earlier session | run with `--list` first, then `--pick N` |
|
|
50
|
+
| See which agents have sessions on this machine | `--agents` |
|
|
51
|
+
| Replay a specific log file | the file path as the first argument |
|
|
52
|
+
| Hide reasoning | `--no-thinking` |
|
|
53
|
+
| Keep file paths but still strip secrets | `--keep-paths` |
|
|
54
|
+
| Raw data instead of HTML | `--json` |
|
|
55
|
+
|
|
56
|
+
Pass through any arguments the user gave this skill.
|
|
57
|
+
|
|
58
|
+
## Rules
|
|
59
|
+
|
|
60
|
+
- Never pass `--no-redact` unless the user explicitly asks for it, and if they
|
|
61
|
+
do, warn them that secrets, e-mails and home paths will be in the file.
|
|
62
|
+
- Redaction covers common secret formats but not everything private. Tell the
|
|
63
|
+
user to skim the replay before posting it publicly.
|
|
64
|
+
- Don't upload or publish the HTML anywhere yourself. Offer the sharing options
|
|
65
|
+
below and let the user choose.
|
|
66
|
+
|
|
67
|
+
## After it runs
|
|
68
|
+
|
|
69
|
+
Report in two or three lines: the output path, the one-line stats the CLI
|
|
70
|
+
printed (events, tool calls, files, minutes, cost), and what was redacted. Then
|
|
71
|
+
mention the ways to share it: drag the file onto Netlify Drop, attach it in Slack/Discord,
|
|
72
|
+
or commit it to a GitHub Pages branch. `#e42` at the end of the URL opens the
|
|
73
|
+
replay at event 42 and `?static` shows everything at once.
|
|
74
|
+
|
|
75
|
+
If the command fails because Node is missing, say that agentreplay needs
|
|
76
|
+
Node.js 18 or newer.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Install the replay skill (an Agent Skills SKILL.md) into every coding agent
|
|
3
|
+
* on this machine. The format is shared; only the folder each agent reads from
|
|
4
|
+
* differs, so we copy the same file into each one.
|
|
5
|
+
*/
|
|
6
|
+
import fs from 'node:fs';
|
|
7
|
+
import os from 'node:os';
|
|
8
|
+
import path from 'node:path';
|
|
9
|
+
import { fileURLToPath } from 'node:url';
|
|
10
|
+
|
|
11
|
+
const SKILL_SRC = fileURLToPath(new URL('../skills/replay/SKILL.md', import.meta.url));
|
|
12
|
+
export const SKILL_NAME = 'agentreplay';
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Where each agent looks for skills. `home` is the agent's own folder: we only
|
|
16
|
+
* install for agents that are present. `.agents/skills` is the shared location
|
|
17
|
+
* several agents read, so it is always written.
|
|
18
|
+
*/
|
|
19
|
+
export function targets({ home = os.homedir(), project = null } = {}) {
|
|
20
|
+
const env = process.env;
|
|
21
|
+
const xdg = env.XDG_CONFIG_HOME || path.join(home, '.config');
|
|
22
|
+
if (project) {
|
|
23
|
+
return [
|
|
24
|
+
{ agent: 'Shared (.agents)', dir: path.join(project, '.agents', 'skills'), always: true },
|
|
25
|
+
{ agent: 'Claude Code', dir: path.join(project, '.claude', 'skills'), always: true },
|
|
26
|
+
{ agent: 'Gemini CLI', dir: path.join(project, '.gemini', 'skills'), when: path.join(project, '.gemini') },
|
|
27
|
+
{ agent: 'OpenCode', dir: path.join(project, '.opencode', 'skills'), when: path.join(project, '.opencode') },
|
|
28
|
+
{ agent: 'GitHub Copilot', dir: path.join(project, '.github', 'skills'), when: path.join(project, '.github') },
|
|
29
|
+
{ agent: 'Cursor', dir: path.join(project, '.cursor', 'skills'), when: path.join(project, '.cursor') },
|
|
30
|
+
];
|
|
31
|
+
}
|
|
32
|
+
return [
|
|
33
|
+
{ agent: 'Shared (~/.agents)', dir: path.join(home, '.agents', 'skills'), always: true },
|
|
34
|
+
{ agent: 'Claude Code', dir: path.join(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'), 'skills'), when: env.CLAUDE_CONFIG_DIR || path.join(home, '.claude') },
|
|
35
|
+
{ agent: 'Codex', dir: path.join(env.CODEX_HOME || path.join(home, '.codex'), 'skills'), when: env.CODEX_HOME || path.join(home, '.codex') },
|
|
36
|
+
{ agent: 'Gemini CLI', dir: path.join(home, '.gemini', 'skills'), when: path.join(home, '.gemini') },
|
|
37
|
+
{ agent: 'Qwen Code', dir: path.join(home, '.qwen', 'skills'), when: path.join(home, '.qwen') },
|
|
38
|
+
{ agent: 'OpenCode', dir: path.join(xdg, 'opencode', 'skills'), when: path.join(xdg, 'opencode') },
|
|
39
|
+
{ agent: 'GitHub Copilot', dir: path.join(env.COPILOT_HOME || path.join(home, '.copilot'), 'skills'), when: env.COPILOT_HOME || path.join(home, '.copilot') },
|
|
40
|
+
{ agent: 'Cursor', dir: path.join(home, '.cursor', 'skills'), when: path.join(home, '.cursor') },
|
|
41
|
+
{ agent: 'Windsurf', dir: path.join(home, '.codeium', 'windsurf', 'skills'), when: path.join(home, '.codeium', 'windsurf') },
|
|
42
|
+
{ agent: 'Amp', dir: path.join(xdg, 'amp', 'skills'), when: path.join(xdg, 'amp') },
|
|
43
|
+
{ agent: 'Goose', dir: path.join(xdg, 'goose', 'skills'), when: path.join(xdg, 'goose') },
|
|
44
|
+
];
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The SKILL.md with `name:` matching the folder it's installed into (the spec requires that). */
|
|
48
|
+
function skillText() {
|
|
49
|
+
return fs.readFileSync(SKILL_SRC, 'utf8').replace(/^name:\s*.+$/m, `name: ${SKILL_NAME}`);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* @returns {{agent:string, file:string, status:'installed'|'updated'|'unchanged'|'skipped'}[]}
|
|
54
|
+
*/
|
|
55
|
+
export function installSkill({ home, project, only, force = false } = {}) {
|
|
56
|
+
const text = skillText();
|
|
57
|
+
const results = [];
|
|
58
|
+
for (const t of targets({ home, project })) {
|
|
59
|
+
if (only && !t.agent.toLowerCase().includes(only.toLowerCase())) continue;
|
|
60
|
+
const file = path.join(t.dir, SKILL_NAME, 'SKILL.md');
|
|
61
|
+
if (!t.always && !force && !(t.when && fs.existsSync(t.when))) {
|
|
62
|
+
results.push({ agent: t.agent, file, status: 'skipped' });
|
|
63
|
+
continue;
|
|
64
|
+
}
|
|
65
|
+
let status = 'installed';
|
|
66
|
+
if (fs.existsSync(file)) status = fs.readFileSync(file, 'utf8') === text ? 'unchanged' : 'updated';
|
|
67
|
+
if (status !== 'unchanged') {
|
|
68
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
69
|
+
fs.writeFileSync(file, text);
|
|
70
|
+
}
|
|
71
|
+
results.push({ agent: t.agent, file, status });
|
|
72
|
+
}
|
|
73
|
+
return results;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** Remove only folders this tool created (they hold our SKILL.md). */
|
|
77
|
+
export function uninstallSkill({ home, project } = {}) {
|
|
78
|
+
const results = [];
|
|
79
|
+
for (const t of targets({ home, project })) {
|
|
80
|
+
const dir = path.join(t.dir, SKILL_NAME);
|
|
81
|
+
const file = path.join(dir, 'SKILL.md');
|
|
82
|
+
if (!fs.existsSync(file)) continue;
|
|
83
|
+
if (!fs.readFileSync(file, 'utf8').includes('@dorywoof/agentreplay')) continue; // not ours
|
|
84
|
+
fs.rmSync(dir, { recursive: true, force: true });
|
|
85
|
+
results.push({ agent: t.agent, file, status: 'removed' });
|
|
86
|
+
}
|
|
87
|
+
return results;
|
|
88
|
+
}
|