@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 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!)
@@ -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
- const idx = opts.pick ? Number(opts.pick) - 1 : 0;
106
- if (!sessions[idx]) fail(`no session #${opts.pick} — run with --list to see what's available`);
107
- ({ file, agent } = sessions[idx]);
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.2.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
+ }