v1.7.0

What's changed

appmap-setup: one source per tool, and stop when it cannot be installed

Phase 0 now lists the one place each AppMap tool comes from, and says the list is complete. (#10)

Tool	Source
AppMap CLI	the appmap-js release manifest
Java agent, appmap.jar	appmap-java GitHub releases
Maven and Gradle plugins	resolved by the build tool; the releases pages give the version number
Ruby, Python, Node agents	RubyGems, PyPI, npm, through the project's package manager

The CLI and the Java agent are installed to ~/.appmap, the same layout the IDE extensions use, so the Phase 0 check passes afterward. Each download is checked against its sha256. Before, the CLI was put "on PATH as appmap", and there was no supported way to get the Java agent jar without an IDE.

~/.appmap/bin/appmap           -> ~/.appmap/lib/appmap/appmap-v<version>
~/.appmap/lib/java/appmap.jar  -> ~/.appmap/lib/java/appmap-<version>.jar

When an install fails, the agent stops and tells the user which tool is missing, the exact command and error text, the likely cause, and what they can do about it. One retry is fine for an error that is clearly temporary. The skill lists what not to try: npm, Homebrew, or Docker for the CLI; installing or launching an IDE; other download URLs; copies found on disk; older versions; building from source; turning off checksum or TLS checks; or changing proxy, registry, or plugin repository settings.

appmap-record: install commands and the same stop rule

• SKILL.md gains an "If a tool is missing" section that points at the one source for each tool and at the stop rule in appmap-setup.
• languages/ruby.md, python.md, and node.md give the install command for the project's package manager, and say the package must come from RubyGems, PyPI, or npm.
• languages/java.md no longer says the agent jar is on Maven Central. It names the releases pages for the agent jar and both build plugins, and says where the Gradle version number comes from.

appmap-gold-traces and appmap-review: pointer to Phase 0

Both skills say that when the CLI or an agent is missing, follow appmap-setup Phase 0 rather than installing it some other way, and stop as Phase 0 describes if that fails.

Upgrading

Nothing to change in projects. The helper scripts are unchanged from v1.6.2.

Full changelog: v1.6.2...v1.7.0

v1.6.2

What's changed

appmap-gold-traces: detected launchers work on Windows

When commands.runner is unset, the engine picks a launcher for the project. The record command runs through the platform's shell, which is cmd.exe on Windows, and three of the choices did not run there. (#8, #12)

Framework	Windows launcher now	Why
pytest, unittest	.venv\Scripts\appmap-python .venv\Scripts\pytest	pip writes appmap-python.exe, so the venv was never found. venv is covered too.
maven, gradle	mvnw test, gradlew appmap test	cmd.exe reads ./mvnw as the command . with a switch. The bare name works: cmd.exe looks in the current directory and adds the .cmd or .bat itself.
rails-test	ruby bin/rails test	bin/rails has no extension.

Nothing changes on macOS or Linux. manage.mjs --help shows the Windows forms. A test runs the wrapper launcher through the real shell on each CI system, so this is checked on Windows, not just reasoned about.

appmap-gold-traces: no APPMAP=true for Ruby

rspec, minitest and rails-test no longer set APPMAP=true on the record command. appmap-ruby's test hooks turn recording on by themselves, and APPMAP=true enables every recording method, requests included, which the gem warns about. commands.record_env still works for a project that needs something else. The cucumber example in the manifest template drops the variable too.

Upgrading

Nothing to change in projects. If a manifest sets runner: to work around either of these on Windows, it can be removed; run plan to see what the engine picks.

Full changelog: v1.6.1...v1.6.2

v1.6.1

What's changed

appmap-gold-traces: gold traces work on Windows

The engine compared file paths it read from disk with paths in the manifest. On Windows the disk paths carry backslashes and the manifest carries slashes, so no recording ever matched its manifest entry. discover, update --record, and covers --fresh failed. The engine now writes every recording path with slashes, on every platform. (#4, #5)

The CLI is installed the way appmap-setup says, and no other way

The helpers no longer say to install the AppMap CLI from npm, and the docs no longer name the @appland/appmap package. appmap-setup holds the two supported ways to get the CLI: the IDE extension, or the manual download from the release manifest. When a helper cannot start the CLI, or the CLI is too old, it now says only that, and leaves the fix to the skill.

Tests run on Windows

Every pull request now runs the helper tests on Ubuntu, macOS, and Windows. The first Windows run reproduced the path bug above; with the fix, all three pass. (#9, #11)

Upgrading

Nothing to change in projects. Manifests and committed baselines stay valid.

Full changelog: v1.6.0...v1.6.1

v1.6.0

What's changed

appmap-review: compare two recordings made by hand

The compare no longer needs gold traces. Give it two recordings, for example one Postman run recorded on each of two branches:

node "${CLAUDE_SKILL_DIR}/assets/review.mjs" compare --base-appmap <file> --head-appmap <file>

• Both files are copied to one trace name, so files named by timestamp compare as one trace instead of one removed plus one new. --name sets that name. The default is the basename the two files share, or recording.
• This mode reads no manifest and no gold_traces/. --base and --head are optional and only name the source diff. --appmap-cli picks the CLI, since there is no manifest to name it.
• The skill has a short section on what differs in this mode: values are real instead of sanitized tokens, coverage is only what the run touched, and the report says the two sides are hand-made recordings of one scenario.

appmap-review: moved blocks are named, and each diff is also text

With AppMap CLI 3.204.0 or later, a block of calls that moved to another caller is reported as one move. Older CLIs showed it as a removal plus an addition.

For every changed trace the summary now prints:

• how many nodes changed, by kind: added, removed, changed, moved
• one line per moved block, naming the caller it left and the caller it is under now, or "reordered within" when the caller is the same
• the labels on the changed nodes
• the path to the same diff as text, one line per changed node, under out/report/text/. This reads better than JSON for large recordings.

An older CLI still runs. The summary then says that a moved block shows as removed plus added. A block that moved and also changed inside still shows as removed plus added, because the CLI pairs a move only when the block is identical. The skill explains how to read that.

Step 5 of the review recipe gains the questions to ask about a moved block: which caller the diff touched, what now runs before and after the block, and whether anything involved carries a label.

appmap-review: the report records how the review was run

The helper's summary ends with the command line as typed and the directory it ran in. The report header gains a one-line Method summary, and a closing section holds the request, the compare command, the working directory, and the evidence path. A reader can rerun the compare from that. For two hand-made recordings, that command is the only record of which files were compared.

appmap-setup: install the CLI without an IDE

The skill now has steps to install the AppMap CLI by hand when no IDE is available: fetch the release manifest, pick the asset for this machine's OS and CPU, check its sha256, and put it on PATH as appmap.

Upgrading

Nothing to change in projects. Manifests and committed baselines stay valid. Moved-block reporting needs AppMap CLI 3.204.0 or later.

Full changelog: v1.5.0...v1.6.0

v1.5.0

What's changed

appmap-review: the compare is a command, not a shell script

The skill used to carry about 60 lines of bash for the compare. It pulled each revision's gold traces out of git, then ran appmap archive, appmap restore, and appmap compare, with comments about each CLI trap. On Windows the agent had to translate all of it to PowerShell. That is now one command:

node "${CLAUDE_SKILL_DIR}/assets/review.mjs" compare --base <rev> [--head <rev> | --fresh | --uncommitted]

It needs only git, Node, and the AppMap CLI. It prints how many traces changed, were added, and were removed, plus the SQL, API, and scanner-finding counts. It also prints where change-report.json and the diff diagrams are, and the git diff to run for the source side of the review.

Head	Flag
a commit	--head <rev> (default HEAD)
fresh recordings, before blessing	--fresh
baselines blessed but not committed	--uncommitted

• A first baseline, where the base has no gold traces, works. Every head trace shows as new.
• The workspace is <system temp>/appmap-review and is cleared on every run. --workspace DIR puts it elsewhere. The helper refuses to clear a non-empty directory it did not create.
• In a monorepo, pass --dir packages/<name>/gold_traces.

On a real project, the command produced the same change report and diff diagrams as the old shell recipe. It has tests, but it has not been run on Windows yet.

appmap-gold-traces

• The release flow's review step now says to run the review with --fresh.
• The engine also looks for the AppMap CLI at ~/.appmap/bin/appmap.exe on Windows.

Upgrading

Nothing to change in projects. Manifests and committed baselines stay valid.

Full changelog: v1.4.0...v1.5.0

v1.4.0

What's changed

appmap-gold-traces: coverage comes from the recordings

• expect and expect_labels are gone from manifest entries. They asked the author to type, per entry, which functions and labels the recording must contain. The recording already holds that in its class map, the compare already reports a call that disappears, and a hand-kept list drifts on every rename. A manifest that still has the fields parses as before and gets a one-line note to delete them.
• The duplicate check now compares what the recordings actually run. discover prints its facts without a verdict; the recording-based coverage delta is the only duplicate check.
• New engine command covers --name <part of a class or method name> lists the committed baselines that run a matching code object, spelled as the recordings spell it. This answers "does a gold trace already run this?" without recording anything. covers --fresh searches the recordings under appmap_dir instead and names each by its test metadata.
• New warning: a recording that stays inside one project class and makes no SQL or HTTP calls reads like a unit test. The overlap warning now says to keep an entry that drives a branch its nearest neighbour does not, and that the engine compares functions, not branches.
• New section, "Finding the test for a code path": run covers on the code object, then on its caller, then hand a subagent the prompt in assets/find-candidates.md to walk the call chain upward, and as a last resort record a test directory. Every candidate is then measured with discover, and the smallest recording wins.
• Maintain is now a six-step release flow where every step is a command except the two marked as a decision. Branch coverage is the test suite's job; only a security gate earns a trace for its refused branch.
• Fix: a dotted packages[].path (Java, Python) never matched a source path, so nothing counted as project code and every entry looked like a duplicate. The coverage comparison now falls back to all code objects when the filter matches nothing.
• The hand-written YAML reader is replaced by js-yaml 5.4.1, vendored under assets/vendor with its MIT license. The manifest and appmap.yml are standard YAML now: same-line comments, flow lists, anchors, and gem: entries all work.

Verified on a real Rails project at two historical revisions. The flow reproduced the real bless commits with identical digests.

appmap-review: decide coverage from the recordings

The Coverage Matrix no longer guesses from test names. A feature behind a trace that changed in the compare is covered by that trace. For a feature whose traces did not change, the review asks the gold-traces engine's covers whether any baseline runs its code. For each gap, the report names the existing test to discover, or says a focused test is needed and what it must drive, instead of printing a record command.

appmap-setup: the record commands live in the manifest

Setup no longer writes docs/appmap.md or imports it from CLAUDE.md. Every line of that file duplicated something a tool already reads. Setup now ends by seeding gold_traces/manifest.yaml with its commands block filled and an empty entries list, verified with plan and one smoke recording. Project-specific lessons go as comments next to the thing they describe.

appmap-setup-review

The replay phase cherry-picks a "commands" commit instead of a "docs" one, and the gold-traces phase follows the new "Finding the test for a code path" section.

Upgrading

Delete expect and expect_labels from existing manifest entries. Nothing else changes; committed baselines stay valid.

Full changelog: v1.3.1...v1.4.0

v1.3.1

What's changed

appmap-gold-traces and appmap-review: frontmatter

Both skills began with a # Skill: heading instead of YAML frontmatter, so Claude Code read no name or description for them. It could not trigger either skill on its own, and the skill listing showed the heading where the description belongs. Each file now opens with a name and a description that says what the skill does and when to use it. The rest of the content is unchanged.

appmap-gold-traces: engine path

The engine commands used a <skill> placeholder with an instruction to substitute the skill's absolute path. They now use ${CLAUDE_SKILL_DIR}/assets/manage.mjs, which Claude Code fills in when it loads the skill, for symlinked and plugin skills alike. A sentence beside the first command explains the path for any other runner, which should substitute the skill's directory as before.

No manifest, command, or output changes. Existing gold_traces/ directories need nothing.

v1.3.0

What's changed

appmap-gold-traces: name the framework, record in batches

• The manifest can now name the test framework instead of spelling out a full command. commands.framework takes pytest, unittest, rspec, minitest, rails-test, jest, vitest, mocha, maven, or gradle. The engine knows how each one names a test on its command line and how it names several, and records the whole gold set in as few runs as the framework allows: one pytest run, one jest run with a name filter, one mvn run with a -Dtest= list, one run per file for minitest. Each agent still writes one recording per test, so entries keep their own appmap_path.
• Optional commands.runner replaces the launcher and commands.args appends flags. commands.record remains as the full-template path for a runner the engine does not know; the two are exclusive.
• With runner unset, the engine detects it per project. A Python .venv or venv that has appmap-python installed is run with both tools named by path, because appmap-python finds its command through PATH and does not add the venv to it, so the plain form ran a foreign pytest and recorded nothing. uv, Poetry, and Pipenv projects run through their own run. Maven and Gradle prefer the project's wrapper script.
• Batches are bounded by the machine's shell limit, measured at run time: getconf ARG_MAX minus the environment on POSIX, capped by Linux's 128 KB single-argument limit, and the 8 KB line on Windows. A run that would exceed it is halved until every piece fits. Optional commands.batch_size caps the count per run on top of that, for isolating a flaky test.
• New plan command prints the record commands the engine would run, and which entries each covers, without running anything. --help lists the frameworks with their default launcher, what is detected, and what test_name means for each.
• The registry lives in assets/frameworks.mjs with its own tests; manage.test.mjs gains end-to-end batch tests against a stub runner.
• Maintain step: when a release materially changes a subsystem an entry already guards, extend that entry's expect with the new release-critical code objects, using the project code objects that check --record prints as the candidate list. The baseline's contract grows with the code.

appmap-review: review before committing

The pipeline only read gold traces from git, but the gold-traces workflow reviews before blessing, when the recordings are not committed. A new "Head from the working tree" section and a step 1b in the script extract the head side from disk: (a) the fresh, sanitized recordings under appmap_dir for the manifest's entries, the exact set update would bless; or (b) gold_traces/ after a bless and before the commit. The gold-traces maintain step now names source (a).

appmap-record and appmap-config: one file per language

Both skills were mostly four language sections, so an agent working on one language read three it did not need. Each language now lives in languages/<lang>.md, and SKILL.md keeps the general material and ends with a table mapping language to file. Names, descriptions, and cross-references are unchanged. appmap-record also gains proper frontmatter and indexes with ~/.appmap/bin/appmap, matching where the other skills expect the tools.

appmap-setup and appmap-setup-review

docs/appmap.md now records the framework name and launcher, so the pair pastes into commands.framework and commands.runner unchanged; the full-command form with placeholders is kept for unknown runners. appmap-setup-review's gold-traces phase points at plan to confirm the commands before recording.

Full changelog: v1.2.1...v1.3.0

v1.2.1

What's changed

appmap-setup: no more repo-local skill

• The skill no longer writes a .claude/skills/<repo>-appmap-setup skill. Setup happens once, so a re-invokable skill was the wrong shape. The repo's facts now go into a short docs/appmap.md that CLAUDE.md imports with an @docs/appmap.md line, so every later session sees the record commands. If the repo has no CLAUDE.md, the skill creates one with only that line.
• The doc lists one record command per test suite using the gold-traces manifest placeholders {test_file} and {test_name}, so a line can be pasted into commands.record unchanged. The setup ends by running each documented command once.
• Tools are checked at their well-known location: ~/.appmap/bin/appmap (3.201 or newer) and ~/.appmap/lib/java/appmap.jar for Java projects. If either is missing, install the AppMap IDE extension, which downloads and keeps them current. A global npm install of the CLI is not a substitute, since nothing updates it.
• The commits it leaves behind are now "config", "exclusions", and "docs".

appmap-setup-review

Uses the new commit names in its cherry-pick step and notes that the docs commit conflicts if CLAUDE.md changed between BASE and HEAD: keep HEAD's content and re-add the import line.

appmap-config

"Cutting noise" gains the measurement step: run appmap stats on the recording, aim for well under 1 MB, and check that the callers of an excluded function still appear after re-recording. appmap-setup's noise-pruning phase is now a pointer to this section.

Full changelog: v1.2.0...v1.2.1

v1.2.0

What's new

appmap-label is now appmap-config

The skill is renamed and rewritten against each agent's source. It is now the one place for everything about appmap.yml and labels:

• The default appmap.yml each agent writes, and a starting config per language that changes as little as possible from it.
• What exclude: matches in each agent. Ruby matches file path substrings under a package and class names at the top level. Python matches dotted names relative to the package path. Node matches file path substrings, function names, or Class.method. Java matches package, class, or Class.method names by prefix. This differs per agent and is the most common mistake.
• A label attaches to a function that is already being recorded, so packages: and exclude: come first.
• The label taxonomy, the "Cutting noise" rules, and the YAML rule to quote method ids containing #.

The other skills point at appmap-config instead of repeating it. appmap-review drops its copy of the taxonomy. appmap-gold-traces drops its copies of the exclude syntax and layout advice. appmap-record drops stale references to skills that no longer exist and gains an "Output directory" section with the per-agent rules for appmap_dir.

If you symlinked appmap-label into ~/.claude/skills, replace the link:

rm ~/.claude/skills/appmap-label
ln -s "$PWD/appmap-config" ~/.claude/skills/appmap-config

appmap-setup is split in two

• appmap-setup now covers recording only: environment checks, build and test as-is, one unit recording, one integration recording, noise pruning, and a repo-local skill with the working commands. It works on whatever commit is checked out and names the three commits it leaves behind so other workflows can cherry-pick them.
• appmap-setup-review is new. It chooses BASE and HEAD commits one feature apart, runs appmap-setup on BASE, seeds gold traces, replays the commits onto HEAD, updates the gold traces, and runs appmap-review. It is a demonstration and evaluation workflow and says so, so it does not trigger for plain setup requests.
• Cross-skill references use phase headings and commit names, never numbers.

appmap-review

The SQL pass now says to use the recorded query text to confirm what a performance fix claims. A LIMIT pushed down into the database shows up in the query, and a fix whose query text did not change did not do what its commit message says.

Full changelog: v1.1.0...v1.2.0