<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[MaxonT]]></title><description><![CDATA[MaxonT]]></description><link>https://maxont.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Sun, 22 Nov 2026 19:56:49 GMT</lastBuildDate><atom:link href="https://maxont.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Does traces fmt convert without loss? A round-trip test, and a status check that needs a threshold]]></title><description><![CDATA[I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability…]]></description><link>https://maxont.hashnode.dev/does-traces-fmt-convert-without-loss-a-round-trip-test-and-a-status-check-that-needs-a-threshold</link><guid isPermaLink="true">https://maxont.hashnode.dev/does-traces-fmt-convert-without-loss-a-round-trip-test-and-a-status-check-that-needs-a-threshold</guid><category><![CDATA[Testing]]></category><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 15:44:52 GMT</pubDate><content:encoded><![CDATA[<p>I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. TRACES.md is a plain-text format, plus a <code>traces</code> CLI, for recording what an agent did. Its README says <code>traces fmt</code> converts between the Markdown and JSONL forms "without loss". I ran that claim, and the <code>status</code> command next to it, to see where the edges are.</p>
<p>I used a temporary <code>HOME</code>, <code>traces 0.1.5</code> (spec traces/0.1.1) straight from the <code>v0.1.5</code> git tag with <code>uvx</code>, and <code>NO_STAR_PROMPT=1</code> so the one-time star question stayed out of the way.</p>
<h2>A round trip with awkward text</h2>
<p>I made a trace with three steps: an edit whose action contains a pipe (<code>use %Y-%m-%d | not %d/%m</code>), a detail with a tab and <code>é ünïcode 日本語</code>, a failing <code>pytest</code> step and a passing retry. In the Markdown file the pipe is stored as <code>\|</code>. Then:</p>
<pre><code class="language-sh">traces fmt --to jsonl --write     # exit 0
rm .trace/&lt;name&gt;.md
traces fmt --to md --write        # exit 0
cmp orig.md .trace/&lt;name&gt;.md      # exit 0, no output
</code></pre>
<p>The regenerated Markdown file was byte-identical to the original.</p>
<h2>A second round trip with more edge cases</h2>
<p>I added a <code>partial</code> step whose detail has two lines, and an <code>ok</code> step with no detail at all. <code>traces append</code> stores the newline in Markdown as a literal <code>\n</code>. The JSONL form holds it as a real JSON string, <code>"first line\nsecond line"</code>, and the step with no detail has a <code>result</code> that is only <code>{"status":"ok"}</code>. The same round trip gave <code>cmp</code> exit 0 again.</p>
<h2>What <code>--write</code> does to your folder</h2>
<p><code>--write</code> leaves the original and writes the converted copy next to it, as the help says. After that, <code>traces validate</code> reports <code>valid: 2 files, 0 errors, 0 warnings</code>, while <code>traces status</code> and <code>traces stats</code> both report <code>1 traces</code>, so they treat the two files as one trace.</p>
<p>If a different <code>.jsonl</code> already exists, <code>fmt</code> refuses to overwrite it:</p>
<pre><code class="language-text">refusing to overwrite different .../2026-11-16-claude-code-fix-the-date-parser.jsonl
</code></pre>
<p>That exit 1 is correct. It also caught me. My first attempt at the second round trip failed this way, and I then deleted the <code>.md</code> and regenerated it from the stale <code>.jsonl</code>, which gave back a file with two steps missing. The tool did what it says. The mistake was mine, and it is easy to make: convert, edit one side, convert again.</p>
<h2><code>fmt --check</code> is stricter than <code>validate</code></h2>
<p>I doubled the space after a <code>|</code> separator in a step line, the one in front of the status word. <code>traces validate</code> still said valid (exit 0). <code>traces fmt --check</code> printed <code>not normalized: &lt;path&gt;</code> and exited 1. A second, independent re-run found that doubling a space inside the action text is not flagged, so I can only say that the separators and the status field are checked.</p>
<h2><code>status --check</code> needs thresholds</h2>
<p>The help says <code>--check</code> exits 1 "if there is any alert", and alerts come from two options, <code>--max-failure-rate</code> and <code>--stale-days</code>. With neither, there is nothing to alert on. I appended a final step with <code>-s fail</code>, which made the summary line read <code>last fail</code>, and <code>traces status --check</code> still exited 0. With a limit it behaves as described:</p>
<pre><code class="language-sh">traces status --check --max-failure-rate 0.3   # exit 1
</code></pre>
<pre><code class="language-text">ALERT: failure rate 33.3% is above the limit 30.0%
</code></pre>
<p>With <code>0.5</code> it exited 0, and <code>--stale-days 1</code> exited 0 for a trace written seconds earlier. The failure rate is <code>fail</code> steps over all steps. The <code>pytest</code> failure that I retried and fixed still counts, so a recovered failure raises the number. <code>--json</code> shows the same data with <code>"alerts": []</code> and <code>"ok": true</code> when no threshold is set.</p>
<h2>What this does not show</h2>
<ul>
<li>Two small traces from one agent. Not tested: many agents, large files, concurrent writers, Windows, or a trace that is actually old for <code>--stale-days</code>.</li>
<li><code>fmt</code> without <code>--write</code>, and the other file types the spec allows.</li>
<li>Whether the "without loss" sentence is meant to cover hand-edited files. I only converted files that <code>traces append</code> wrote.</li>
<li>I changed no code and filed no issue. Everything above is what the help text says, observed.</li>
</ul>
<h2>If you use it in CI</h2>
<p>Run <code>traces validate</code>, then <code>traces fmt --check</code>, then <code>traces status --check</code> with a failure-rate limit that you pick. Without the limit, the last command cannot fail.</p>
<ul>
<li>Repo (MIT): <a href="https://github.com/MaxonT/TRACES.md">https://github.com/MaxonT/TRACES.md</a></li>
<li>Site: <a href="https://maxont.github.io/TRACES.md/">https://maxont.github.io/TRACES.md/</a></li>
<li>Sibling project: <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a> (Multi-Agent Context Management, Coordination &amp; Observability)</li>
</ul>
<p>This post and the test runs were written and run by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.</p>
<p><em>Originally published on <a href="https://dev.to/maxont/does-traces-fmt-convert-without-loss-a-round-trip-test-and-a-status-check-that-needs-a-threshold-2kgc">DEV</a>.</em></p>
]]></content:encoded></item><item><title><![CDATA[The first outside pull request to existence-trace, and what an AI agent checked before merging it]]></title><description><![CDATA[I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability…]]></description><link>https://maxont.hashnode.dev/the-first-outside-pull-request-to-existence-trace-and-what-an-ai-agent-checked-before-merging-it</link><guid isPermaLink="true">https://maxont.hashnode.dev/the-first-outside-pull-request-to-existence-trace-and-what-an-ai-agent-checked-before-merging-it</guid><category><![CDATA[GitHub]]></category><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 15:28:59 GMT</pubDate><content:encoded><![CDATA[<p>I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. existence-trace is a journal that an AI reads, and it has to prove it used what it learned. This morning existence-trace got its first pull request from someone outside the project. An AI agent (Claude Code) reviewed it and merged it for me, so this post is about what the agent checked, and what it did not.</p>
<h2>How the pull request came about</h2>
<p>The agent had been testing existence-trace's weekly audit and found that an empty week prints "Every chain is complete" with no count of chains audited. It filed that as issue #4 at 14:41 UTC, with the commands to reproduce it, the output, the line in <code>etrace/container/audit.py</code> where <code>passed</code> comes from, and three options. The first option named the new JSON field and gave the exact wording for the report line, and the pull request below follows it. The issue carries the labels <code>good first issue</code> and <code>help wanted</code>.</p>
<p>At 14:58 UTC the user i-sayankh forked the repository. At 15:12 UTC they opened PR #8, "Report empty weekly audits explicitly", with two commits: 37 lines added and 2 removed across six files, <code>etrace/cli.py</code>, <code>etrace/container/audit.py</code>, <code>etrace/render.py</code> and three test files. The description said <code>Closes #4</code> and listed what was tested, including that 11 unrelated failures remained on their Windows machine. I do not know how they found the issue.</p>
<h2>What the agent checked</h2>
<ol>
<li>It read the whole diff before running anything. The changes are display strings, one new JSON field (<code>chains_audited</code>) and tests. Nothing opens a network connection, runs a command or writes outside the tests.</li>
<li>It cloned the repository into an empty directory, checked out the PR branch, and set a temporary <code>HOME</code> so nothing could touch real data.</li>
<li>It ran the three new tests: 46 tests in the audit and render modules passed, and the new CLI test passed.</li>
<li>It ran the whole suite on the PR branch: 650 tests, OK. On <code>main</code> the same command ran 648 tests, OK. The difference is the two tests the PR adds.</li>
<li>It left a comment on the PR saying what it had run, with a note that an AI agent did the review, and merged with a merge commit so that both of the contributor's commits stay in the history (<code>188b5a8</code>). Issue #4 closed by itself.</li>
</ol>
<h2>What it did not check</h2>
<ul>
<li>Windows. The contributor reported 11 failures there, which I did not see on macOS, and I did not look into them.</li>
<li>No CI ran on the PR branch (<code>gh pr checks</code> reported nothing), so the local run was the only check.</li>
<li>The agent did not re-run the experiments from the earlier article against the new code. On <code>main</code> an empty week now reads "Result: passed (0 chains this week, nothing was audited)." The v0.4.6 tag and the PyPI-style install still behave as before until a release is cut.</li>
<li>The merge decision was made by an agent working for me. I can still revert it.</li>
</ul>
<h2>What I would take from it</h2>
<p>The issue was small, had a reproduction that took three commands, and said what a good result looks like. That is what a stranger needs to start. The fix came 31 minutes after the issue, and 14 minutes after the fork. One data point does not make a trend, and I cannot say that the issue text caused it.</p>
<p>If you run a small project, label two or three issues <code>good first issue</code> and write the reproduction first. aisync has several open (<a href="https://github.com/MaxonT/aisync/issues?q=is%3Aopen+label%3A%22good+first+issue%22">https://github.com/MaxonT/aisync/issues?q=is%3Aopen+label%3A%22good+first+issue%22</a>), for example the path matching in <code>aisync claim</code> (#31, #32).</p>
<ul>
<li>PR: <a href="https://github.com/MaxonT/existence-trace/pull/8">https://github.com/MaxonT/existence-trace/pull/8</a></li>
<li>Issue: <a href="https://github.com/MaxonT/existence-trace/issues/4">https://github.com/MaxonT/existence-trace/issues/4</a></li>
<li>Repo (MIT): <a href="https://github.com/MaxonT/existence-trace">https://github.com/MaxonT/existence-trace</a></li>
<li>Sibling project: <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a> (Multi-Agent Context Management, Coordination &amp; Observability)</li>
</ul>
<p>This post was written by an AI agent (Claude Code) for the maintainer. The review and the test runs described above were real runs, and the numbers are copied from them.</p>
<p><em>Originally published on <a href="https://dev.to/maxont/the-first-outside-pull-request-to-existence-trace-and-what-an-ai-agent-checked-before-merging-it-4oa5">DEV</a>.</em></p>
]]></content:encoded></item><item><title><![CDATA[The existence-trace installer: a dry run that works, and three ways to trip it]]></title><description><![CDATA[I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability…]]></description><link>https://maxont.hashnode.dev/the-existence-trace-installer-a-dry-run-that-works-and-three-ways-to-trip-it</link><guid isPermaLink="true">https://maxont.hashnode.dev/the-existence-trace-installer-a-dry-run-that-works-and-three-ways-to-trip-it</guid><category><![CDATA[Testing]]></category><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 15:15:16 GMT</pubDate><content:encoded><![CDATA[<p>I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. existence-trace is a journal that an AI reads, and it has to prove it used what it learned. This post is about the second one's installer, the first thing a new user runs. Its README promises that it "never edits your shell config without asking". I read the script, ran only its dry run, and tried the ways a user could trip over it.</p>
<p>I used a temporary <code>HOME</code> and <code>TMPDIR</code>, so nothing on my machine could change. The script is the one served at <code>https://maxont.github.io/existence-trace/install.sh</code> (4,382 bytes, the same bytes as <code>docs/install.sh</code> on <code>main</code>). I read the whole script before running anything. The machine had Python 3.14.8, <code>uv</code> and <code>pipx</code>.</p>
<h2>What the script does</h2>
<p>It checks that <code>python3</code> is 3.11 or newer, asks the GitHub API for the latest release, and installs the wheel with <code>uv tool install</code>, <code>pipx install</code> or <code>pip install --user</code>, in that order of preference. I found no line that writes to a shell config file. When <code>etrace</code> is not on <code>PATH</code> afterwards it prints a command for you to run instead. I did not run the real install, so I did not check what <code>uv tool install</code> itself does to your shell setup.</p>
<h2>The dry run works, in the right form</h2>
<pre><code class="language-sh">cat install.sh | bash -s -- --dry-run
</code></pre>
<pre><code class="language-text">[1/3] Checking Python (needs 3.11 or newer)
ok: Python 3.14.8

[2/3] Getting existence-trace
asking GitHub for the latest release...
latest: existence_trace-0.4.6-py3-none-any.whl
[dry-run] download https://github.com/MaxonT/existence-trace/releases/download/v0.4.6/existence_trace-0.4.6-py3-none-any.whl

[3/3] Installing
installer: uv
[dry-run] uv tool install --force ...

dry-run finished: nothing was changed.
</code></pre>
<p>Exit code 0, and the temp <code>HOME</code> was empty afterwards. It does contact the GitHub API to find the latest release.</p>
<h2>Trip 1: the README's <code>--dry-run</code> after the pipe</h2>
<p>Under the <code>curl ... | bash</code> line, the README says "Add <code>--dry-run</code> to see what it would do first." It does not say where. The obvious reading fails:</p>
<pre><code class="language-sh">cat install.sh | bash --dry-run
</code></pre>
<pre><code class="language-text">bash: --dry-run: invalid option
</code></pre>
<p>Exit code 2 and nothing runs, so it is harmless. The flag has to go through <code>bash -s --</code>, as above. The install page on the site, which reads as instructions for an agent, shows the other working form: download the file with <code>curl -o /tmp/etrace-install.sh</code>, then <code>bash /tmp/etrace-install.sh --dry-run</code>.</p>
<h2>Trip 2: <code>--help</code> only works from a file</h2>
<pre><code class="language-sh">bash install.sh --help                  # prints the header, exit 0
cat install.sh | bash -s -- --help      # prints nothing, exit 1
</code></pre>
<p>The help text comes from <code>sed -n '2,11p' "$0"</code>. Under a pipe <code>$0</code> is <code>bash</code>, there is no file to read, and the script exits 1 without a word. A mistyped flag is handled well: <code>--dryrun</code> prints <code>unknown option: --dryrun</code> and exits 2.</p>
<h2>Trip 3: an old system Python stops it, even with <code>uv</code> installed</h2>
<p>The Python check looks only at <code>python3</code> on <code>PATH</code>. I put a fake <code>python3</code> first on <code>PATH</code> that reports 3.9.6, with <code>uv</code> still available:</p>
<pre><code class="language-text">error: Python 3.11+ required, found Python 3.9.6.
</code></pre>
<p>Exit code 1. This is a simulation and not a real old machine. I did not test whether <code>uv tool install</code> would have found a suitable Python on its own, so the strict check may be a deliberate choice.</p>
<h2>What this does not show</h2>
<ul>
<li>No real install. I ran <code>--dry-run</code> only, and I did not exercise the <code>pipx</code>, <code>pip --user</code> or <code>git+</code> fallbacks.</li>
<li>One machine (macOS, arm64), with <code>uv</code> and <code>pipx</code> present. The old Python is a fake.</li>
<li>I changed nothing in the installer or the README.</li>
<li>Each trip is filed as an issue with the commands above: the piped <code>--dry-run</code> form is <a href="https://github.com/MaxonT/existence-trace/issues/5">https://github.com/MaxonT/existence-trace/issues/5</a>, the silent piped <code>--help</code> is <a href="https://github.com/MaxonT/existence-trace/issues/6">https://github.com/MaxonT/existence-trace/issues/6</a>, and the old system Python is <a href="https://github.com/MaxonT/existence-trace/issues/7">https://github.com/MaxonT/existence-trace/issues/7</a>.</li>
</ul>
<h2>If you ship an installer</h2>
<p>Show every flag in the form people will paste, which for <code>curl | bash</code> is <code>bash -s -- &lt;flag&gt;</code>, and make <code>--help</code> work when the script comes from a pipe.</p>
<ul>
<li>Repo (MIT): <a href="https://github.com/MaxonT/existence-trace">https://github.com/MaxonT/existence-trace</a></li>
<li>Site: <a href="https://maxont.github.io/existence-trace/">https://maxont.github.io/existence-trace/</a></li>
<li>Sibling project: <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a> (Multi-Agent Context Management, Coordination &amp; Observability)</li>
</ul>
<p>This post and the test runs were written and run by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.</p>
<p><em>Originally published on <a href="https://dev.to/maxont/the-existence-trace-installer-a-dry-run-that-works-and-three-ways-to-trip-it-bp8">DEV</a>.</em></p>
]]></content:encoded></item><item><title><![CDATA[An unrelated "unblocked" clears every blocker: testing aisync log and status]]></title><description><![CDATA[aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability across AI coding tools. I maintain it. Two agents can write to its…]]></description><link>https://maxont.hashnode.dev/an-unrelated-unblocked-clears-every-blocker-testing-aisync-log-and-status</link><guid isPermaLink="true">https://maxont.hashnode.dev/an-unrelated-unblocked-clears-every-blocker-testing-aisync-log-and-status</guid><category><![CDATA[Testing]]></category><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 15:03:57 GMT</pubDate><content:encoded><![CDATA[<p>aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. I maintain it. Two agents can write to its journal with <code>aisync log</code>, and <code>aisync status</code> shows who is blocked. I tested how blockers are closed and what <code>--project</code> defaults to, and found that one unrelated <code>unblocked</code> event can clear every open blocker in a project.</p>
<p>I used a throwaway hub (<code>AISYNC_HOME</code> and <code>HOME</code> in a temp directory) and <code>aisync-cli</code> 0.2.11 from PyPI, run with <code>uvx</code>.</p>
<h2>An unrelated <code>unblocked</code> closes everything</h2>
<p>Agents A and B each log a blocker in project <code>shop2</code>, and <code>aisync status</code> lists both:</p>
<pre><code class="language-sh">aisync log -a A -p shop2 -k blocked -m "A: waiting for the API key"
aisync log -a B -p shop2 -k blocked -m "B: staging database is down"
aisync status
</code></pre>
<pre><code class="language-text">BLOCKED  A            shop2: A: waiting for the API key (since 11-16 08:59)
BLOCKED  B            shop2: B: staging database is down (since 11-16 08:59)
</code></pre>
<p>Agent C then logs a message that has nothing to do with either blocker:</p>
<pre><code class="language-sh">aisync log -a C -p shop2 -k unblocked -m "C: finished my own unrelated task"
aisync status
</code></pre>
<p>Both <code>BLOCKED</code> lines are gone. The rule is in <code>ai_sync/core.py</code> (<code>build_current</code>): an <code>unblocked</code> event closes the blocker whose id is in its <code>blocked_id</code> ref, and when there is no <code>blocked_id</code> it closes every open blocker with the same project. Who logged it does not matter.</p>
<p>The precise form works. <code>aisync log</code> prints the id of the event it wrote (<code>logged a7acf21bd4ad35da</code>). Passing it back closes only that blocker:</p>
<pre><code class="language-sh">aisync log -a A -p shop3 -k unblocked --ref blocked_id=&lt;id of A's blocked event&gt; -m "A: key arrived"
</code></pre>
<p>In a second project, with A's and B's blockers open, this left only B's <code>BLOCKED</code> line.</p>
<p>What I did not find is any documentation for it. <code>blocked_id</code> appears in <code>core.py</code>, <code>board.py</code> and the built-in demo, but not in the README, in the <code>docs</code> folder, in the <code>--ref</code> help (<code>key=value, e.g. pr=45</code>), or in the MCP text. The MCP <code>log</code> tool is declared as <code>log(agent, project, summary, kind, files)</code>, with no way to pass a ref. An agent that reaches aisync through MCP can only write the broad form.</p>
<h2><code>--project</code> defaults to the checkout's directory name</h2>
<p>The help says <code>default: name of the current git repo</code>. In practice it is the name of the directory that <code>git rev-parse --show-toplevel</code> returns:</p>
<table>
<thead>
<tr>
<th>Where <code>aisync log</code> ran</th>
<th>project recorded</th>
</tr>
</thead>
<tbody><tr>
<td>repo root <code>myrepo</code></td>
<td><code>myrepo</code></td>
</tr>
<tr>
<td><code>myrepo/src/deep</code></td>
<td><code>myrepo</code></td>
</tr>
<tr>
<td>a plain directory, no git</td>
<td><code>-</code> (the event is still written)</td>
</tr>
<tr>
<td>a git worktree directory <code>wt-feature</code> of <code>myrepo</code></td>
<td><code>wt-feature</code></td>
</tr>
</tbody></table>
<p>Claims compare project names for equality, so a claim from the worktree does not meet a claim from the main checkout. A claimed <code>src/a.py</code> with the default project in <code>myrepo</code>. Then B claimed the same path from <code>wt-feature</code> with exit 0 (<code>claimed wt-feature [src/a.py] for B</code>), while C in <code>myrepo</code> got exit 3. Two worktrees are separate checkouts, so this may be what you want. If you use worktrees to give each agent its own branch and want claims to span them, pass the same <code>--project</code> everywhere. Outside a git repo, <code>aisync claim</code> without <code>-p</code> stops with <code>error: claim needs --agent, --project and --summary</code> (exit 2).</p>
<h2><code>aisync log -k claim</code> is only a journal line</h2>
<p><code>claim</code> and <code>release</code> are listed among the kinds <code>log</code> accepts. Logging one does not claim anything:</p>
<pre><code class="language-sh">aisync log -a A -p myrepo -k claim -f docs/z.md -m "claimed docs/z.md"
aisync claims
</code></pre>
<pre><code class="language-text">no active claims
</code></pre>
<p>B then claimed <code>docs/z.md</code> with exit 0. Use <code>aisync claim</code> to claim.</p>
<h2>What this does not show</h2>
<ul>
<li>One version (0.2.11), one machine (macOS, arm64), the CLI only. For the MCP <code>log</code> tool I read the source and did not run it.</li>
<li>I tried one git worktree layout. I did not test submodules.</li>
<li>I changed nothing in the code. Each finding is filed with the commands above: the broad <code>unblocked</code> is <a href="https://github.com/MaxonT/aisync/issues/34">https://github.com/MaxonT/aisync/issues/34</a>, the worktree project name is <a href="https://github.com/MaxonT/aisync/issues/35">https://github.com/MaxonT/aisync/issues/35</a>, and <code>log -k claim</code> is <a href="https://github.com/MaxonT/aisync/issues/36">https://github.com/MaxonT/aisync/issues/36</a>. Whether an <code>unblocked</code> without an id should close one blocker, the latest one by that agent, or all of them is a decision for the maintainer.</li>
</ul>
<h2>If you build something like this</h2>
<p>Make closing a blocker name the blocker, or at least restrict it to the agent that opened it. Put the id in the output of the command that opens it, as aisync does, and document that it exists.</p>
<ul>
<li>Repo (MIT): <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a></li>
<li>Site: <a href="https://maxont.github.io/aisync/">https://maxont.github.io/aisync/</a></li>
<li>Install: <code>pip install aisync-cli</code></li>
</ul>
<p>This post and the test runs were written and run by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.</p>
<p>Originally published on DEV: <a href="https://dev.to/maxont/an-unrelated-unblocked-clears-every-blocker-testing-aisync-log-and-status-4gl7">https://dev.to/maxont/an-unrelated-unblocked-clears-every-blocker-testing-aisync-log-and-status-4gl7</a></p>
]]></content:encoded></item><item><title><![CDATA[A file-claim check that misses ./src and flags mydocs: testing aisync claim]]></title><description><![CDATA[aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability across AI coding tools. I maintain it. One part of the coordination…]]></description><link>https://maxont.hashnode.dev/a-file-claim-check-that-misses-src-and-flags-mydocs-testing-aisync-claim</link><guid isPermaLink="true">https://maxont.hashnode.dev/a-file-claim-check-that-misses-src-and-flags-mydocs-testing-aisync-claim</guid><category><![CDATA[Testing]]></category><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 14:55:33 GMT</pubDate><content:encoded><![CDATA[<p>aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. I maintain it. One part of the coordination is <code>aisync claim</code>: an agent says which files it is working on, and a second agent that claims an overlapping file gets exit code 3. I tested how that overlap decision treats real path spellings, and found two misses, one false alarm and one behavior the docs do not mention.</p>
<p>I used a throwaway hub (<code>AISYNC_HOME</code> and <code>HOME</code> in a temp directory) and <code>aisync-cli</code> 0.2.11 from PyPI, run with <code>uvx</code>. Agents A and B, project <code>p</code>. For each case A claims first, then B, and I recorded B's exit code.</p>
<pre><code class="language-sh">export HOME="$(mktemp -d)" AISYNC_HOME="$HOME/hub"
uvx aisync-cli@0.2.11 init
uvx aisync-cli@0.2.11 claim --agent A --project p --files "docs/" -m "A work"
uvx aisync-cli@0.2.11 claim --agent B --project p --files "docs/x.md" -m "B work"; echo $?
</code></pre>
<h2>What is caught</h2>
<table>
<thead>
<tr>
<th>A claims</th>
<th>B claims</th>
<th>B's exit</th>
</tr>
</thead>
<tbody><tr>
<td><code>docs/</code></td>
<td><code>docs/x.md</code></td>
<td>3</td>
</tr>
<tr>
<td><code>docs/x.md</code></td>
<td><code>docs/</code></td>
<td>3</td>
</tr>
<tr>
<td><code>docs</code></td>
<td><code>docs/x.md</code></td>
<td>3</td>
</tr>
<tr>
<td><code>src/a.py</code></td>
<td><code>src/a.py</code></td>
<td>3</td>
</tr>
<tr>
<td><code>src/a.py</code></td>
<td><code>tests/b.py</code></td>
<td>0</td>
</tr>
</tbody></table>
<p>On a conflict B sees <code>OVERLAP: A is working on p [b.py] until 10:46: second claim</code> (that exact line came from the replace test further down), and the CLI adds "Your claim is noted, so A can see you are waiting."</p>
<h2>Two misses: path spellings</h2>
<table>
<thead>
<tr>
<th>A claims</th>
<th>B claims</th>
<th>B's exit</th>
</tr>
</thead>
<tbody><tr>
<td><code>./src/a.py</code></td>
<td><code>src/a.py</code></td>
<td>0</td>
</tr>
<tr>
<td><code>src/../src/a.py</code></td>
<td><code>src/a.py</code></td>
<td>0</td>
</tr>
<tr>
<td><code>README.md</code></td>
<td><code>readme.md</code></td>
<td>0</td>
</tr>
</tbody></table>
<p>Both agents end up with the same file and nothing is flagged. The cause is in <code>ai_sync/collab.py</code>: <code>_overlaps</code> compares the file strings as written (<code>set(a.files) &amp; set(b.files)</code>), with no normalisation. The <code>README.md</code> / <code>readme.md</code> pair is only a real miss on a case-insensitive filesystem, such as macOS's default. I did not test one.</p>
<h2>One false alarm: substring match</h2>
<table>
<thead>
<tr>
<th>A claims</th>
<th>B claims</th>
<th>B's exit</th>
</tr>
</thead>
<tbody><tr>
<td><code>docs</code></td>
<td><code>mydocs/x.md</code></td>
<td>3</td>
</tr>
<tr>
<td><code>src</code></td>
<td><code>lib/src/a.py</code></td>
<td>3</td>
</tr>
</tbody></table>
<p>These are different directories and B is refused anyway. The directory test is <code>x.rstrip("/") + "/" in y</code>, which asks whether <code>docs/</code> appears anywhere inside the other path, not whether the other path starts with it.</p>
<h2>A second claim silently replaces the first</h2>
<pre><code class="language-sh">aisync claim --agent A --project p --files a.py -m "first claim"
aisync claim --agent A --project p --files b.py -m "second claim"
aisync claims
</code></pre>
<pre><code class="language-text">A            p                        until 10:46  [b.py]  second claim
</code></pre>
<p><code>a.py</code> is no longer claimed. B claims <code>a.py</code> with exit 0. Claiming <code>b.py</code> as B still gives exit 3. The claim function drops the agent's earlier claim for the same project before adding the new one. I searched the README's claim lines and <code>aisync claim --help</code>: neither says a new claim replaces the old one.</p>
<p>What works: one claim with a comma-separated list. <code>--files "a.py,b.py"</code> from A made both of B's claims exit 3.</p>
<h2>What this does not show</h2>
<ul>
<li>One version (0.2.11), one machine (macOS, arm64), the CLI only. I did not run the MCP <code>claim</code> tool, so I do not know whether it behaves the same.</li>
<li>Claims are cooperative by design, as the README says; none of this is about enforcement.</li>
<li>I changed nothing in the code. Each finding is filed with the commands above: the substring match is <a href="https://github.com/MaxonT/aisync/issues/31">https://github.com/MaxonT/aisync/issues/31</a>, the path spellings are <a href="https://github.com/MaxonT/aisync/issues/32">https://github.com/MaxonT/aisync/issues/32</a>, and the silent replace is <a href="https://github.com/MaxonT/aisync/issues/33">https://github.com/MaxonT/aisync/issues/33</a>. Whether paths should be normalised, and whether a second claim should add or replace, are decisions for the maintainer.</li>
</ul>
<h2>If you build something like this</h2>
<p>Normalise paths before comparing them, compare directories by prefix, and decide whether a new claim from the same agent adds to its old one. Then say which in the help text.</p>
<ul>
<li>Repo (MIT): <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a></li>
<li>Site: <a href="https://maxont.github.io/aisync/">https://maxont.github.io/aisync/</a></li>
<li>Install: <code>pip install aisync-cli</code></li>
</ul>
<p>This post and the test runs were written and run by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.</p>
<p>Originally published on DEV: <a href="https://dev.to/maxont/a-file-claim-check-that-misses-src-and-flags-mydocs-testing-aisync-claim-3ecj">https://dev.to/maxont/a-file-claim-check-that-misses-src-and-flags-mydocs-testing-aisync-claim-3ecj</a></p>
]]></content:encoded></item><item><title><![CDATA[A trace validator that catches "ok: exit 1" but not "ok: returncode 1"]]></title><description><![CDATA[I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability…]]></description><link>https://maxont.hashnode.dev/a-trace-validator-that-catches-ok-exit-1-but-not-ok-returncode-1</link><guid isPermaLink="true">https://maxont.hashnode.dev/a-trace-validator-that-catches-ok-exit-1-but-not-ok-returncode-1</guid><category><![CDATA[Testing]]></category><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 14:37:56 GMT</pubDate><content:encoded><![CDATA[<p>I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. <a href="http://TRACES.md">TRACES.md</a> is a plain-text format for recording what an agent did, with a validator that is supposed to catch a trace that hides a failure. This post tests that validator: which hidden failures it catches, and which it lets through.</p>
<p>I used a temporary <code>HOME</code> and the v0.1.5 tag of <a href="http://TRACES.md">TRACES.md</a> (spec traces/0.1.1). It is not on PyPI, so I ran it from git:</p>
<pre><code class="language-sh">export HOME="$(mktemp -d)"
traces() { uvx --from git+https://github.com/MaxonT/TRACES.md@v0.1.5 traces "$@"; }
traces init --agent claude-code --task "demo run"
</code></pre>
<h2>A recorded failure is a valid trace</h2>
<pre><code class="language-sh">traces run -- python3 -c "import sys; sys.exit(3)"
</code></pre>
<p>The step in the file reads <code>shell: python3 -c 'import sys; sys.exit(3)' | run python3 -c ... | fail: exit 3</code>. <code>traces run</code> returns the command's own exit code to the shell (3 here, 0 for a command that succeeds). <code>traces validate</code> says <code>valid: 1 files, 0 errors, 0 warnings</code>. A failure that is written down counts as a good record.</p>
<h2>The CLI refuses a hidden failure</h2>
<pre><code class="language-sh">traces append -t "shell: pytest" -a "run the tests" -s ok -d "exit 1, 2 failed"
</code></pre>
<pre><code class="language-text">traces: step refused: error[E040]: hidden failure: status is ok but the result reports exit code 1; record it as 'fail'
</code></pre>
<p>Exit code 1, and the file still had one step afterwards.</p>
<h2>Lines written straight into the file</h2>
<p>The check is a validator, so I also wrote single-step trace files by hand, the way a script or a person could. One file per case, each validated alone:</p>
<table>
<thead>
<tr>
<th>Result written in the file</th>
<th><code>validate</code></th>
<th>exit</th>
</tr>
</thead>
<tbody><tr>
<td><code>ok: exit 1, 2 failed</code></td>
<td>error E040, hidden failure</td>
<td>1</td>
</tr>
<tr>
<td><code>ok: 2 tests failed</code></td>
<td>warning W002 only</td>
<td>0 (1 with <code>--strict</code>)</td>
</tr>
<tr>
<td><code>ok: returncode 1</code></td>
<td>valid, no warnings</td>
<td>0</td>
</tr>
<tr>
<td>first step is "retry the tests", no earlier <code>fail</code></td>
<td>error E041, the failure being retried is missing</td>
<td>1</td>
</tr>
<tr>
<td><code>ok: exit 0, 12 passed</code> in place of a deleted <code>fail</code> step</td>
<td>valid</td>
<td>0</td>
</tr>
</tbody></table>
<p>The third row is the gap. The exit-code check is a regular expression in <code>traces/validate.py</code> (<code>EXIT_NONZERO_RE</code>), and it looks for the word <code>exit</code> followed by a non-zero number. <code>returncode 1</code> has no such word and no failure word either, so nothing fires.</p>
<p>The last row is a limit by construction. A validator reads one file. If a <code>fail</code> step is deleted and the next step is not labelled as a retry, the file is consistent with itself. E041 only helps when the later step says "retry", "again" or similar.</p>
<h2>What <code>stats</code> shows</h2>
<p>On a trace with one <code>fail</code> and one <code>ok</code> step:</p>
<pre><code class="language-text">1 traces, 2 steps: 1 ok, 1 fail, 0 partial (failure rate 50.0%)
1 of 1 traces contain at least one failure
</code></pre>
<p>It also lists failures per agent, per tool and per command.</p>
<h2>What this does not show</h2>
<ul>
<li>I wrote every step myself, with a script. No agent produced these traces, so I measured the validator and nothing else.</li>
<li>All checks are regular expressions over text. I did not look for other phrasings that slip through, only this one.</li>
<li>I did not change anything. Whether <code>returncode</code> should count is a decision for the spec. I opened <a href="https://github.com/MaxonT/TRACES.md/issues/22">https://github.com/MaxonT/TRACES.md/issues/22</a> with a table of the phrasings I tried afterwards: <code>rc=1</code>, <code>return code 1</code> and <code>status 1</code> also pass, <code>exited 1</code> is caught.</li>
<li>One version (v0.1.5), one machine (macOS, arm64), uv. I did not test the JSONL format, <code>traces fmt</code>, the schema, or <code>traces status</code>.</li>
</ul>
<h2>If you validate agent logs</h2>
<p>Do not treat a clean validator run as proof that nothing failed. It tells you the file is consistent with its own rules. Record the exit code from the process, as <code>traces run</code> does, instead of typing it.</p>
<ul>
<li>Repo (MIT): <a href="https://github.com/MaxonT/TRACES.md">https://github.com/MaxonT/TRACES.md</a></li>
<li>Spec: <a href="https://github.com/MaxonT/TRACES.md/blob/main/SPEC.md">https://github.com/MaxonT/TRACES.md/blob/main/SPEC.md</a></li>
<li>Sibling project: <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a> (Multi-Agent Context Management, Coordination &amp; Observability)</li>
</ul>
<p>This post and the test runs were written and run by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.</p>
<p>Originally published on DEV: <a href="https://dev.to/maxont/a-trace-validator-that-catches-ok-exit-1-but-not-ok-returncode-1-3h9">https://dev.to/maxont/a-trace-validator-that-catches-ok-exit-1-but-not-ok-returncode-1-3h9</a></p>
]]></content:encoded></item><item><title><![CDATA[A weekly audit that passes on an empty week: testing existence-trace]]></title><description><![CDATA[I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability…]]></description><link>https://maxont.hashnode.dev/a-weekly-audit-that-passes-on-an-empty-week-testing-existence-trace</link><guid isPermaLink="true">https://maxont.hashnode.dev/a-weekly-audit-that-passes-on-an-empty-week-testing-existence-trace</guid><category><![CDATA[Testing]]></category><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 14:28:58 GMT</pubDate><content:encoded><![CDATA[<p>I maintain two small open-source CLIs for working with AI agents. aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. existence-trace is a journal that an AI reads, and it has to prove it used what it learned. This post tests the second one: its weekly audit, which the README sums up as "A weekly audit fails if a rule was never applied." I wanted to see when it fails and when it quietly passes.</p>
<p>I used a temporary <code>HOME</code>, so none of my real data was touched, and the v0.4.6 tag of existence-trace. It is not on PyPI, so I ran it straight from git:</p>
<pre><code class="language-sh">export HOME="$(mktemp -d)"
uvx --from git+https://github.com/MaxonT/existence-trace@v0.4.6 etrace init
</code></pre>
<h2>An empty week passes</h2>
<p>Before I had written anything:</p>
<pre><code class="language-sh">etrace audit weekly
</code></pre>
<pre><code class="language-json">{"week": "2026-W47", "passed": true, "broken": [], "scope_overlaps": [], ...}
</code></pre>
<p>There were no chains to check, so nothing was broken. That is fine as a rule, but it means a green audit tells you nothing about a week in which no feedback arrived.</p>
<h2>A fresh decision passes without a receipt</h2>
<p>The loop is feedback, then a decision with a rule change, then a usage receipt. I wrote one line in the "Feedback for the AI" block of today's note, "Keep the daily narrative to two sentences.", and ran <code>etrace feedback ingest</code>. The entry came back as <code>pending</code>. Then I stored a decision for it with <code>etrace decide dec.json</code> (a JSON file with <code>feedback_ids</code>, <code>decision_text</code>, <code>value_source</code> and one rule change). The rules went from version 9 to 10.</p>
<p>There was still no receipt, and the audit still passed. The report lists the decision under "Still open (not broken)":</p>
<pre><code class="language-plaintext">decision D-20261116-1 is within the 2-day grace period
</code></pre>
<p>The grace period is <code>GRACE = datetime.timedelta(days=2)</code> in <code>etrace/container/audit.py</code>. So the README sentence is true after two days, not before.</p>
<h2>Past the grace period it fails</h2>
<p>I needed a decision that was three days old. The CLI has no option for that, but <code>decisions.decide()</code> takes a <code>now</code> argument, so I called it from Python in the temp data folder with a timestamp three days back, for a second feedback entry ("Ask about sleep before work when energy is low."). Then:</p>
<pre><code class="language-sh">etrace audit weekly     # passed: false, broken: ["2026-11-16:feedback:9c02e8d550dd"]
etrace validate; echo $?
</code></pre>
<pre><code class="language-plaintext">decision D-20261113-1 is older than 2 days with no usage receipt and is not pending
1
</code></pre>
<p>The audit report says the same thing in its "Broken chains" section: <code>decision D-20261113-1 has no usage receipt and is not pending</code>. <code>validate</code> exits with 1, so a script can stop on it.</p>
<h2>A receipt makes it pass</h2>
<pre><code class="language-sh">etrace usage add rec.json
</code></pre>
<p>The receipt has <code>task</code>, <code>target</code>, <code>rule_version</code>, <code>before</code>, <code>after</code>, <code>status</code> (<code>changed</code>), <code>verified_readback</code> (<code>true</code>) and the decision and feedback ids. After it was stored, <code>audit weekly</code> returned <code>passed: true</code> and <code>validate</code> exited 0. The report now includes a spot check for a person to read:</p>
<pre><code class="language-plaintext">applied: U-20261116-1 (daily -&gt; journal/2026-11-16.md, changed)
  before: question order: free (the agent asked about work first)
  after: questions for 2026-11-16 ask about sleep first
</code></pre>
<h2>What this does not show</h2>
<ul>
<li>I wrote the receipt myself. No AI rewrote a narrative or changed a question order in this run. The audit accepted a receipt whose <code>before</code> and <code>after</code> I typed, and it cannot know whether they are true. That is what the spot check is for: it samples one applied receipt and puts it in front of a person.</li>
<li>The three-day-old decision came from a Python call, not from three real days of use.</li>
<li>One version (v0.4.6), one machine (macOS, arm64), uv, a synthetic journal with two entries.</li>
<li>I did not test <code>scope_overlaps</code>, the email intake, or the Notion mirror.</li>
<li>The empty-week result is filed as <a href="https://github.com/MaxonT/existence-trace/issues/4">https://github.com/MaxonT/existence-trace/issues/4</a>, with a suggestion to report how many chains were audited. I did not change the code myself.</li>
<li>Update, 2026-11-16 09:21 CT: an outside contributor, i-sayankh, fixed that in <a href="https://github.com/MaxonT/existence-trace/pull/8">https://github.com/MaxonT/existence-trace/pull/8</a>, merged on <code>main</code> as 188b5a8. The v0.4.6 tag still behaves as shown above. On <code>main</code>, an empty week now reads "Result: passed (0 chains this week, nothing was audited)." and the JSON has a <code>chains_audited</code> field. I read the diff and ran the test suite on the PR branch (650 tests OK), but I did not re-run this post's runs against the new code.</li>
</ul>
<h2>If you build something like this</h2>
<p>Decide what an empty period should report, and say how long a rule may wait before it counts as ignored. In existence-trace both answers are visible in the audit report, and the second one is a constant in the source.</p>
<ul>
<li>Repo (MIT): <a href="https://github.com/MaxonT/existence-trace">https://github.com/MaxonT/existence-trace</a></li>
<li>Site: <a href="https://maxont.github.io/existence-trace/">https://maxont.github.io/existence-trace/</a></li>
<li>Sibling project: <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a> (Multi-Agent Context Management, Coordination &amp; Observability)</li>
</ul>
<p>This post and the test runs were written and run by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.</p>
<p>Originally published on DEV: <a href="https://dev.to/maxont/a-weekly-audit-that-passes-on-an-empty-week-testing-existence-trace-2mf">https://dev.to/maxont/a-weekly-audit-that-passes-on-an-empty-week-testing-existence-trace-2mf</a></p>
]]></content:encoded></item><item><title><![CDATA[uvx fails on a Python MCP server whose command name differs from its PyPI name]]></title><description><![CDATA[aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability across AI coding tools. I maintain it, and it ships an MCP server…]]></description><link>https://maxont.hashnode.dev/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name</link><guid isPermaLink="true">https://maxont.hashnode.dev/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name</guid><category><![CDATA[mcp]]></category><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 14:19:48 GMT</pubDate><content:encoded><![CDATA[<p>aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. I maintain it, and it ships an MCP server (<code>aisync mcp</code>). While preparing it for the official MCP registry I found that <code>uvx &lt;package-name&gt;</code> failed for it, and the reason applies to any Python MCP server whose command name differs from its PyPI name. This post is what I ran and what I did not run.</p>
<h2>The failure</h2>
<p>The PyPI package is <code>aisync-cli</code>; the command it installs is <code>aisync</code>. With <code>HOME</code> pointed at a temp directory (so nothing from my real setup was reused), on 0.2.10:</p>
<pre><code class="language-sh">uvx aisync-cli@0.2.10 --version
</code></pre>
<pre><code class="language-plaintext">An executable named `aisync-cli` is not provided by package `aisync-cli`.
The following executables are available:
- aisync

Use `uvx --from aisync-cli aisync` instead.
</code></pre>
<p>Exit code 1. <code>uvx &lt;name&gt;</code> looks for an executable with the same name as the package. A registry entry that names <code>aisync-cli</code> as its PyPI identifier points at exactly that form.</p>
<h2>The second trap: the extra</h2>
<p>The MCP SDK is an optional extra in this package (<code>aisync-cli[mcp]</code>). With the right executable but no extra:</p>
<pre><code class="language-sh">uvx --from aisync-cli@0.2.10 aisync mcp
</code></pre>
<p>It exits with code 2 and prints <code>error: the MCP server needs the official SDK: pip install 'aisync-cli[mcp]' (mcp&gt;=2.3)</code>. With the extra (<code>--from 'aisync-cli[mcp]@0.2.10'</code>) the server answers an <code>initialize</code> request and exits cleanly when stdin closes.</p>
<h2>The fix I shipped</h2>
<p>Two small changes in 0.2.11:</p>
<ol>
<li>A second console script with the package's name, so <code>uvx aisync-cli</code> finds an executable: in <code>pyproject.toml</code>, <code>aisync-cli = "ai_sync.cli:main"</code> next to <code>aisync = ...</code>.</li>
<li>The extra goes in the registry manifest as a runtime argument: <code>--with "mcp&gt;=2.3,&lt;3"</code>, plus the positional argument <code>mcp</code>.</li>
</ol>
<pre><code class="language-sh">uvx aisync-cli@0.2.11 --version
# aisync 0.2.11
uvx --with "mcp&gt;=2.3,&lt;3" aisync-cli@0.2.11 mcp
# answers initialize, exit 0
</code></pre>
<p>Both ran in a temp HOME against the version published on PyPI.</p>
<h2>The manifest</h2>
<p>The registry's <code>server.json</code> for a PyPI package, as I wrote it:</p>
<pre><code class="language-json">{
  "name": "io.github.MaxonT/aisync",
  "version": "0.2.11",
  "packages": [{
    "registryType": "pypi",
    "identifier": "aisync-cli",
    "version": "0.2.11",
    "runtimeHint": "uvx",
    "runtimeArguments": [{"type": "named", "name": "--with", "value": "mcp&gt;=2.3,&lt;3"}],
    "packageArguments": [{"type": "positional", "value": "mcp"}],
    "transport": {"type": "stdio"}
  }]
}
</code></pre>
<p>(<code>$schema</code>, title, description and repository are left out here.) The registry checks ownership of a PyPI package by looking for <code>mcp-name: io.github.MaxonT/aisync</code> in the package README, which becomes the PyPI description. I put it in an HTML comment in <code>README.md</code> and read it back from the PyPI JSON after the release. <code>mcp-publisher validate</code> printed <code>server.json is valid</code>; it validates against the live registry, so it is a stronger check than the JSON schema alone.</p>
<h2>What I did not do</h2>
<ul>
<li>I have not published to the registry. The last step is a GitHub device authorization, and I stopped there. This post will be updated when it is done or if it fails.</li>
<li>I did not test how a registry client assembles the command from <code>runtimeHint</code>, <code>runtimeArguments</code> and <code>packageArguments</code>. I read the schema descriptions and assumed the arguments go before the package name and the package arguments after it. The local runs above use that shape; no real client was involved.</li>
<li>The fix is one project, one platform (macOS, arm64) and uv, not pipx.</li>
</ul>
<h2>If you maintain a Python MCP server</h2>
<p>Run <code>uvx &lt;your-pypi-name&gt; --version</code> in a clean directory. If the executable name differs, add a console script with the package name, and check whether your server needs an extra before <code>uvx</code> can start it.</p>
<ul>
<li>Repo (MIT): <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a></li>
<li>Site: <a href="https://maxont.github.io/aisync/">https://maxont.github.io/aisync/</a></li>
<li>Install: <code>pip install aisync-cli</code></li>
</ul>
<p>This post and the test runs were written and tested by an AI agent (Claude Code) for the maintainer. The outputs above are copied from those runs.</p>
<p>Originally published on DEV: <a href="https://dev.to/maxont/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name-13do">https://dev.to/maxont/uvx-fails-on-a-python-mcp-server-whose-command-name-differs-from-its-pypi-name-13do</a></p>
]]></content:encoded></item><item><title><![CDATA[What aisync news shows: only what changed after your first call]]></title><description><![CDATA[aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability across AI coding tools. I maintain it. One of its jobs is telling an…]]></description><link>https://maxont.hashnode.dev/what-aisync-news-shows-only-what-changed-after-your-first-call</link><guid isPermaLink="true">https://maxont.hashnode.dev/what-aisync-news-shows-only-what-changed-after-your-first-call</guid><category><![CDATA[Python]]></category><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 12:09:15 GMT</pubDate><content:encoded><![CDATA[<p>aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. I maintain it. One of its jobs is telling an agent what the other agents did while it was working, and the command for that is <code>aisync news</code>. I ran it with two agents in a throwaway hub to see what it shows, and what it does not.</p>
<p>I used a temporary virtualenv, pointed <code>AISYNC_HOME</code> and <code>HOME</code> at temp directories so my real hub and tool files were never touched, and installed <code>aisync-cli</code> 0.2.10.</p>
<pre><code class="language-sh">python3 -m venv v &amp;&amp; ./v/bin/pip install aisync-cli==0.2.10
export AISYNC_HOME="$PWD/home" HOME="$PWD/fakehome"
./v/bin/aisync init
./v/bin/aisync news --agent codex
</code></pre>
<h2>The first call shows nothing</h2>
<pre><code class="language-plaintext">cursor set; next call shows what changed after now
</code></pre>
<p>A session's first <code>news</code> call only sets a cursor. Anything that happened before that moment is not reported. If you want the earlier history you use <code>aisync tail</code> or <code>aisync status</code>. This is by design, because a new session gets the live picture another way. By default the progress (other agents, claims, blockers) sits in a block of the shared <code>agents.md</code>, which the tools load. With <code>progress_file = "progress.md"</code> at the top of <code>config.toml</code> the SessionStart hook injects it instead. I ran that second case in the temp hub by feeding the hook a SessionStart payload by hand (<code>echo '{"hook_event_name":"SessionStart","session_id":"c4"}' | aisync hook claude-code</code>) and got the progress table with the other agent's claim and blocker. In the default setup that hook printed nothing. Without either source, <code>news</code> alone shows nothing until something changes.</p>
<h2>Then it shows what the other agent did</h2>
<p>Claude Code logs two events, then Codex asks again:</p>
<pre><code class="language-sh">./v/bin/aisync log --agent claude-code --project demo --kind dev_log --summary "added retry to the uploader"
./v/bin/aisync log --agent claude-code --project demo --kind blocked --summary "waiting for API key"
./v/bin/aisync news --agent codex
</code></pre>
<pre><code class="language-plaintext">[aisync] While you were working, other AI tools changed things:
- 06:04 claude-code dev_log @ demo: added retry to the uploader
- 06:04 claude-code blocked @ demo: waiting for API key
If any of this touches files you are editing, coordinate (`aisync claims`) before going on.
</code></pre>
<p>A third call prints <code>nothing new</code>: the cursor moved past those two events.</p>
<h2>An agent does not see its own events</h2>
<p>Claude Code had already run <code>aisync news --agent claude-code</code> once, so its cursor was set (the output was the same "cursor set" line). It then logged a <code>decision</code> event and ran <code>aisync news --agent claude-code</code> again. The output was <code>nothing new</code>. Without that first call the second one would only have set the cursor, so the order matters. The result matches the intent ("what other tools did"), and it means <code>news</code> is not a general activity feed.</p>
<h2>Each session has its own cursor</h2>
<p>With <code>--session</code>, two Codex sessions keep separate cursors. Session <code>s1</code> set its cursor, Claude Code logged a note, and then session <code>s2</code> set its cursor. Asking <code>s1</code> showed the note. Asking <code>s2</code> printed <code>nothing new</code>, because its cursor was set after the note. The cursors are small files, one per agent and session, under <code>state/cursors/</code> in the hub (for example <code>codex-s1.json</code>).</p>
<h2>What this does not show</h2>
<ul>
<li>I tested one hub, two agents, and a handful of events. I did not test hundreds of events or many agents writing at the same moment.</li>
<li>The hooks that call <code>news</code> automatically for Claude Code, Codex and Cursor were not part of this test. I called the command by hand.</li>
<li>I fed the hook command JSON by hand in a temp hub. I did not run it inside a real Claude Code, Codex or Cursor session, so how each tool treats the output was not tested. One trap I hit: <code>progress_file</code> is silently ignored if it sits below a <code>[[target]]</code> table in the TOML, because it then belongs to that table.</li>
<li>Repo (MIT): <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a></li>
<li>Site: <a href="https://maxont.github.io/aisync/">https://maxont.github.io/aisync/</a></li>
<li>Install: <code>pip install aisync-cli</code></li>
</ul>
<p>This post and the test run were written and tested by an AI agent (Claude Code) for the maintainer. The outputs above are copied from that run.</p>
<p>First published on DEV: <a href="https://dev.to/maxont/a-fresh-agent-session-sees-nothing-what-aisync-news-shows-and-what-it-doesnt-59n5">https://dev.to/maxont/a-fresh-agent-session-sees-nothing-what-aisync-news-shows-and-what-it-doesnt-59n5</a></p>
]]></content:encoded></item><item><title><![CDATA[Two nearly identical rules, and aisync tidy said zero duplicates]]></title><description><![CDATA[aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability across AI coding tools. I maintain it. One job of the hub is keeping…]]></description><link>https://maxont.hashnode.dev/two-nearly-identical-rules-and-aisync-tidy-said-zero-duplicates</link><guid isPermaLink="true">https://maxont.hashnode.dev/two-nearly-identical-rules-and-aisync-tidy-said-zero-duplicates</guid><category><![CDATA[Python]]></category><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 11:12:18 GMT</pubDate><content:encoded><![CDATA[<p>aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. I maintain it. One job of the hub is keeping a single set of shared rules for every agent, and <code>aisync tidy</code> is the command that proposes cleanups for those rules and never edits a file. I tested it with two rules that say almost the same thing, and it reported zero duplicates. This post is what I found.</p>
<p>I used a throwaway virtualenv and pointed <code>AISYNC_HOME</code> at a temp directory, so my real hub was never touched. Version 0.2.9. The PyPI package is called <code>aisync-cli</code>.</p>
<pre><code class="language-sh">python3 -m venv v &amp;&amp; ./v/bin/pip install aisync-cli
export AISYNC_HOME="$PWD/home"
./v/bin/aisync init
./v/bin/aisync rule add --agent claude-code --project demo --when "a test fails" --do "fix the cause before committing" --not "skipping the test" --reason demo --judgment-only "nothing in code can check it"
./v/bin/aisync rule add --agent codex --project demo --when "a test fails" --do "fix the cause, then commit" --not "skipping the test" --reason demo --judgment-only "nothing in code can check it"
./v/bin/aisync rule add --agent cursor --project demo --when "a release is cut" --do "tag the commit" --not "tagging a dirty tree" --reason demo
./v/bin/aisync tidy
</code></pre>
<p>The first two rules have the same trigger and nearly the same action. <code>tidy</code> printed:</p>
<pre><code class="language-plaintext">Checked 6 rules. Proposals only: ...

## Likely duplicates (0)
- none
</code></pre>
<p>Six rules, because <code>init</code> seeds three. Zero duplicates.</p>
<h2>Why it missed them</h2>
<p><code>tidy</code> compares the When and Do text of each rule with <code>difflib.SequenceMatcher</code>, and calls a pair a likely duplicate when both ratios are at least 0.72 (<code>SAME = 0.72</code> in <code>tidy.py</code>). I computed the two ratios with the package's own functions: When 1.0, Do 0.79. That is over the line, so the pair should have been caught.</p>
<p>The difference was in the text <code>tidy</code> reads. In a hub with no topic headings, <code>aisync rule add</code> stored this bullet:</p>
<pre><code class="language-plaintext">- [R-004] 2026-11-16 05:04 CST (claude-code, demo): When: a test fails. Do: fix the cause before committing. Not: skipping the test. Reason: demo
</code></pre>
<p>The package's rule parser returned <code>None</code> for that line. <code>tidy</code> drops every rule it cannot parse before it compares anything, so the duplicate check saw no rules at all. The same <code>tidy</code> report agrees: it listed all six rules, including the three <code>rule add</code> had just written, under "Out of the When/Do/Not shape (6)". The parser wants <code>When: ... Do: ... Not: ...</code> with a <code>(YYYY-MM-DD · agent, project)</code> tag at the end. The same text with the tag moved to the end parses fine. Turning on <code>rule_spec = true</code> in <code>config.toml</code> did not change the stored format in my run.</p>
<h2>The way that works today</h2>
<p>Rules grouped under a topic heading are written in the shape the parser reads. I added a <code>### Basics</code> line inside the rules block of <code>preferences.md</code> and used <code>--topic Basics</code>:</p>
<pre><code class="language-sh">./v/bin/aisync rule add --topic Basics --agent claude-code --project demo --when "a test fails" --do "fix the cause before committing" --not "skipping the test" --reason demo --judgment-only "nothing in code can check it"
./v/bin/aisync rule add --topic Basics --agent codex --project demo --when "a test fails" --do "fix the cause, then commit" --not "skipping the test" --reason demo --judgment-only "nothing in code can check it"
./v/bin/aisync tidy
</code></pre>
<p>The stored bullet is now <code>- [R-004] When: a test fails. Do: fix the cause before committing. Not: skipping the test. (2026-11-16 · claude-code, demo)</code>, and <code>tidy</code> prints:</p>
<pre><code class="language-plaintext">## Likely duplicates (1)
- [ ] merge R-005 and R-004 (When 1.0, Do 0.79)
</code></pre>
<h2>What <code>tidy</code> does right</h2>
<p>It only proposes. I hashed every file in the hub before and after a <code>tidy</code> run and the hash was identical, so nothing was edited. The proposals are checkboxes you apply yourself with <code>aisync rule rewrite</code> or <code>aisync rule add --replaces</code>, and a replaced rule moves to <code>rules-archive.md</code> with its ID.</p>
<h2>What this does not show</h2>
<ul>
<li>I only ran version 0.2.9, one pair of rules, and fresh hubs. A hub that already has topic headings is not affected the way a fresh one is.</li>
<li>Update, 2026-11-16: the fix shipped in aisync-cli 0.2.10, as the second option. <code>aisync tidy</code> now prints a "Not compared: N of M rules are not in the When/Do/Not shape..." line that lists the rules it skipped. The parser still does not read the format <code>rule add</code> writes without topics, so those pairs stay uncompared, but the report says so. I reran the commands above on 0.2.10 in a clean virtualenv. Under "Likely duplicates (0)" the report now prints "Not compared: 6 of 6 rules ..." (the hub seeds three rules and the commands add three). With the topic setup from the previous section, the line says "3 of 5", listing the three seeded rules it cannot read.</li>
<li>The 0.72 line comes from the source, and I did not test other pairs near it.</li>
<li>Repo (MIT): <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a></li>
<li>Site: <a href="https://maxont.github.io/aisync/">https://maxont.github.io/aisync/</a></li>
<li>Install: <code>pip install aisync-cli</code></li>
</ul>
<p>This post, the test runs and the fix were written and tested by an AI agent (Claude Code) for the maintainer. The outputs above are copied from that run.</p>
]]></content:encoded></item><item><title><![CDATA[Edit one line of an AI agent journal and see what aisync verify says]]></title><description><![CDATA[aisync is a local CLI for Multi-Agent Context Management, Coordination & Observability across AI coding tools. I maintain it. Part of the hub is a journal…]]></description><link>https://maxont.hashnode.dev/edit-one-line-of-an-ai-agent-journal-and-see-what-aisync-verify-says</link><guid isPermaLink="true">https://maxont.hashnode.dev/edit-one-line-of-an-ai-agent-journal-and-see-what-aisync-verify-says</guid><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 09:49:31 GMT</pubDate><content:encoded><![CDATA[<p>aisync is a local CLI for Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools. I maintain it. Part of the hub is a journal that every agent event goes into, and the journal is hash-chained. This post tests that claim by editing the journal by hand and seeing what <code>aisync verify</code> says.</p>
<p>I used a throwaway virtualenv and pointed <code>AISYNC_HOME</code> at a temp directory, so my real hub was never touched. The first three cases (edit, delete the second line, restore) were run on 0.2.9; the last-entry case below was run on 0.2.10, and a later independent rerun of all of them gave the same results on both versions. The PyPI package is called <code>aisync-cli</code>, not <code>aisync</code>.</p>
<pre><code class="language-sh">python3 -m venv v &amp;&amp; ./v/bin/pip install aisync-cli
export AISYNC_HOME="$PWD/home"
./v/bin/aisync init
for i in 1 2 3; do ./v/bin/aisync log --agent claude-code --project demo --kind dev_log --summary "step $i"; done
./v/bin/aisync verify
</code></pre>
<p>That gave a journal of five lines and <code>journal chain intact</code>, exit code 0.</p>
<h2>Edit one entry</h2>
<p>I changed <code>step 2</code> to <code>step 2 (edited)</code> directly in <code>journal.jsonl</code> and ran verify again:</p>
<pre><code class="language-plaintext">line 4: id mismatch (event edited by hand)
exit=1
</code></pre>
<h2>Delete one entry</h2>
<p>I restored the file, deleted its second line and ran verify:</p>
<pre><code class="language-plaintext">line 2: prev link broken (event lost, reordered or forked)
exit=1
</code></pre>
<h2>Delete the last entry</h2>
<p>Reviewing this post I ran the case I had skipped: I copied the five-line journal, deleted its last line and ran verify.</p>
<pre><code class="language-plaintext">journal chain intact
exit=0
</code></pre>
<p>The journal had four lines instead of five and verify still printed "journal chain intact". Deleting the first line printed "line 1: prev link broken (event lost, reordered or forked)" with exit 1. My reading of why: each event stores the id of the one before it, so a missing event is only noticed when a later event points at it, and nothing follows the last one. I did not look for a separate record of the expected length. Run on aisync-cli 0.2.10. An independent rerun also checked three more cases on 0.2.10. Truncating the last two lines: "journal chain intact", exit 0. An empty journal: also "intact", exit 0. Appending a forged line with a wrong previous id: "line 6: prev link broken" and "line 6: id mismatch (event edited by hand)", exit 1. In that rerun <code>aisync status</code> and <code>aisync doctor</code> also said the chain was intact for the shortened journal, <code>aisync report</code> has no journal-length check, and <code>git diff</code> in the hub showed the deleted lines, so git history was the only detector I found. If you rely on the chain, keep the journal in git or record the line count somewhere else.</p>
<h2>Restore it</h2>
<p>With the original file back, verify printed <code>journal chain intact</code> and exited 0.</p>
<h2>Why this matters when several agents share a repo</h2>
<p>When Claude Code, Codex and Cursor all write to one journal, the question after a bad day is "which agent did what, and has anyone changed the record since". Every event stores the id of the one before it. An edit changes that event's id. Removing an entry that is followed by another one breaks the link to that next entry. Removing the last entry does not break any link (see above). An edit or a removal in the middle shows up as a non-zero exit, so a script or a CI step can check those two.</p>
<h2>What this does not show</h2>
<p>I did not test an attacker who recomputes every later hash after editing. A hash chain on its own detects accidental or careless changes. It is not a signature, so I would not call the journal tamper-proof. Only the cases in this post were run.</p>
<ul>
<li>Repo (MIT): <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a></li>
<li>Site: <a href="https://maxont.github.io/aisync/">https://maxont.github.io/aisync/</a></li>
<li>Install: <code>pip install aisync-cli</code></li>
</ul>
<p>This post and the test run were prepared with AI assistance (Claude Code). The outputs above are copied from that run.</p>
<p><em>Originally published on</em> <a href="https://dev.to/maxont/edit-one-line-of-an-ai-agent-journal-and-see-what-aisync-verify-says-1202"><em>Dev.to</em></a><em>.</em></p>
]]></content:encoded></item><item><title><![CDATA[Two AI coding agents, one file: detecting overlapping edits with exit code 3]]></title><description><![CDATA[aisync is a local hub for Multi-Agent Context Management, Coordination & Observability. This post covers the coordination part: how two coding agents on…]]></description><link>https://maxont.hashnode.dev/two-ai-coding-agents-one-file-detecting-overlapping-edits-with-exit-code-3</link><guid isPermaLink="true">https://maxont.hashnode.dev/two-ai-coding-agents-one-file-detecting-overlapping-edits-with-exit-code-3</guid><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 09:30:10 GMT</pubDate><content:encoded><![CDATA[<p>aisync is a local hub for Multi-Agent Context Management, Coordination &amp; Observability. This post covers the coordination part: how two coding agents on one machine find out they are about to edit the same file.</p>
<h2>The problem</h2>
<p>Run Claude Code and Codex in the same repository and nothing stops both from rewriting <code>app/payments/refunds.py</code>. Each tool only sees its own session, so the clash shows up later as a confusing merge or a silently overwritten fix.</p>
<h2>What aisync does about it</h2>
<p>An agent declares a claim on the files it is about to touch. If another agent already holds a claim on those files, the CLI refuses with exit code 3, so a script or a hook can stop instead of editing.</p>
<p>I ran this in a throwaway virtualenv with <code>AISYNC_HOME</code> pointing at a temp directory, so it did not touch my real hub (aisync 0.2.9):</p>
<pre><code class="language-sh">pip install aisync-cli
aisync init
aisync claim -a claude-code -p api -f app/payments/refunds.py -m "refund fix"
# claimed api [app/payments/refunds.py] for claude-code until 05:28      (exit 0)

aisync claim -a codex -p api -f app/payments/refunds.py -m "sdk upgrade"
# OVERLAP: claude-code is working on api [app/payments/refunds.py] until 05:28: refund fix
# stop and coordinate with claude-code, or pick other files (exit 3). Your claim is noted, so claude-code can see you are waiting.   (exit 3)

aisync release -a claude-code -p api
# released 1 claim(s)

aisync claim -a codex -p api -f app/payments/refunds.py -m "sdk upgrade"
# claimed api [app/payments/refunds.py] for codex until 05:28            (exit 0)

aisync verify
# journal chain intact                                                   (exit 0)
</code></pre>
<p>Three details from that run. The refused claim is still recorded, so the first agent can see someone is waiting. <code>aisync claims</code> lists both. And claims carry an expiry: the output above says <code>until 05:28</code> for a claim made around 03:28, so about two hours.</p>
<h2>The observability half</h2>
<p>Every claim, release and other agent event goes into a journal in the hub, which is a plain git repo. Each event stores the id of the one before it, so <code>aisync verify</code> can detect an edited entry, or a removed one that a later entry points at (a removed last entry is not caught).</p>
<h2>Limits</h2>
<ul>
<li>Claims are cooperative. They are not operating-system locks: an agent that never calls <code>aisync claim</code> can still edit the file.</li>
<li>Hash-chain verification detects changes to recorded events. It does not prove that every action an agent claimed actually happened.</li>
<li>Native hooks exist for Claude Code, Codex and Cursor. Other agents need to call the CLI or the MCP server themselves, and instruction files alone give standing rules but no claim enforcement.</li>
<li>It needs Python 3.11+ on macOS or Linux, and has no runtime dependencies. MIT licensed.</li>
<li>Repo: <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a></li>
<li>Site: <a href="https://maxont.github.io/aisync/">https://maxont.github.io/aisync/</a></li>
<li>Earlier post: <a href="https://dev.to/maxont/aisync-one-local-hub-for-rules-and-coordination-across-ai-coding-agents-4egp">https://dev.to/maxont/aisync-one-local-hub-for-rules-and-coordination-across-ai-coding-agents-4egp</a></li>
</ul>
<p>This post and the test run were written and tested by an AI agent (Claude Code) for the maintainer. The outputs above are copied from that run.</p>
<p><em>Originally published on</em> <a href="https://dev.to/maxont/two-ai-coding-agents-one-file-detecting-overlapping-edits-with-exit-code-3-14ph"><em>Dev.to</em></a><em>.</em></p>
]]></content:encoded></item><item><title><![CDATA[existence-trace: a journal your AI reads, and has to prove it used]]></title><description><![CDATA[existence-trace is an open-source CLI (etrace) for an AI that reads your journal every day, asks you where it is unsure, turns your answers into rules, and…]]></description><link>https://maxont.hashnode.dev/existence-trace-a-journal-your-ai-reads-and-has-to-prove-it-used</link><guid isPermaLink="true">https://maxont.hashnode.dev/existence-trace-a-journal-your-ai-reads-and-has-to-prove-it-used</guid><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 08:57:00 GMT</pubDate><content:encoded><![CDATA[<p>existence-trace is an open-source CLI (<code>etrace</code>) for an AI that reads your journal every day, asks you where it is unsure, turns your answers into rules, and has to prove it used them. It runs on your own files with any model, under the MIT license.</p>
<h2>The problem</h2>
<p>You spend hours a week with Claude, ChatGPT or Codex. They learn your stack, your repo and your naming style. What they pick up about you ends up in a vendor's memory you cannot fully check, or nowhere at all. existence-trace is the missing half: a journal your AI actually reads, in files you own.</p>
<h2>How it works</h2>
<ul>
<li><strong>You write.</strong> A few lines a day, or import old diary files (<code>.md</code>, <code>.txt</code>, Day One <code>.json</code>) with one command.</li>
<li><strong>It reads.</strong> Each day it writes a report through three lenses: emotion (PAD), stability and exploration (G), growth (XP).</li>
<li><strong>It asks.</strong> When it is unsure about you, it asks one question with evidence instead of guessing.</li>
<li><strong>It proves.</strong> Your answer becomes a rule. When a rule changes a report, it records a receipt with the before and the after. A weekly audit fails if a rule was never applied.</li>
</ul>
<p>Your own words stay word for word in a protected block that nothing can rewrite; the AI only writes its own blocks. PAD, G and XP are reflection aids, not clinical scales.</p>
<h2>Compared with built-in chat memory</h2>
<table>
<thead>
<tr>
<th></th>
<th>Built-in chat memory</th>
<th>existence-trace</th>
</tr>
</thead>
<tbody><tr>
<td>Where it lives</td>
<td>the vendor's account</td>
<td>plain text files in your own folder, versioned with git</td>
</tr>
<tr>
<td>Who decides what is remembered</td>
<td>mostly the model</td>
<td>you: it asks, you answer, the answer becomes a versioned rule</td>
</tr>
<tr>
<td>Proof it used what it knows</td>
<td>none</td>
<td>a receipt with before and after, and a weekly audit</td>
</tr>
<tr>
<td>Which AI</td>
<td>one vendor</td>
<td>Anthropic, OpenAI, DeepSeek, OpenRouter, Ollama, or any OpenAI-compatible address</td>
</tr>
</tbody></table>
<h2>Try it</h2>
<p>It needs Python 3.11+ and uses the standard library only.</p>
<pre><code class="language-sh">curl -fsSL https://maxont.github.io/existence-trace/install.sh | bash
etrace ai set                            # connect an AI
etrace import ~/Documents/diary --run    # bring in your old diary and let the AI read it
</code></pre>
<p>Add <code>--dry-run</code> to the installer or to <code>etrace import</code> to preview first. With no old diary, run <code>etrace init</code>, then <code>etrace note</code> to open today's page and <code>etrace run daily</code> to read it. Your AI key is kept outside your data folder.</p>
<h2>Where it fits</h2>
<p>existence-trace is about one person's own record. Its sibling projects are about agents. <a href="https://github.com/MaxonT/aisync">aisync</a> handles Multi-Agent Context Management, Coordination &amp; Observability across AI coding tools, and <a href="https://github.com/MaxonT/TRACES.md">TRACES.md</a> is a format for recording what each agent did. They are separate repos; existence-trace does not depend on either.</p>
<h2>Limits</h2>
<p>This is a young project and the numbers it reports are reflection aids, not measurements. It is not a clinical or therapy tool. It sends your journal text to whichever AI service you connect, so choose one you are comfortable with, or use a local model through Ollama.</p>
<ul>
<li>Repo (MIT): <a href="https://github.com/MaxonT/existence-trace">https://github.com/MaxonT/existence-trace</a></li>
<li>Site: <a href="https://maxont.github.io/existence-trace/">https://maxont.github.io/existence-trace/</a></li>
</ul>
<p>This post was written by an AI agent (Claude Code) for the maintainer.</p>
<p><em>Originally published on</em> <a href="https://dev.to/maxont/existence-trace-a-journal-your-ai-reads-and-has-to-prove-it-used-3p8i"><em>Dev.to</em></a><em>.</em></p>
]]></content:encoded></item><item><title><![CDATA[TRACES.md: a plain-text flight recorder for what AI agents did]]></title><description><![CDATA[TRACES.md is an open format for recording what AI agents did. AGENTS.md tells an agent how to behave. TRACES.md is the file where it writes down what it…]]></description><link>https://maxont.hashnode.dev/traces-md-a-plain-text-flight-recorder-for-what-ai-agents-did</link><guid isPermaLink="true">https://maxont.hashnode.dev/traces-md-a-plain-text-flight-recorder-for-what-ai-agents-did</guid><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 08:52:28 GMT</pubDate><content:encoded><![CDATA[<p><a href="http://TRACES.md">TRACES.md</a> is an open format for recording what AI agents did. <a href="http://AGENTS.md">AGENTS.md</a> tells an agent how to behave. <a href="http://TRACES.md">TRACES.md</a> is the file where it writes down what it actually did.</p>
<p>I run several coding agents (Cursor, Trae, Kiro, Claude Code, Codex) on the same repositories. When something broke, I had no plain record of which agent ran which command and how it ended. <a href="http://TRACES.md">TRACES.md</a> came out of that.</p>
<h2>The format</h2>
<p>A trace is one plain, append-only file per task. One line per operation: when, which tool, what it did, how it ended. It records no reasoning and no story, and it records failures.</p>
<p>A minimal file, <code>.trace/2026-10-12-claude-code-fix-date-parser.md</code>:</p>
<pre><code class="language-plaintext">task: Fix the failing date parser test
agent: claude-code
started: 2026-10-12T09:14:02-05:00
spec: traces/0.1.1

2026-10-12T09:14:31-05:00 | shell: python -m pytest tests/test_dates.py | run the date tests | fail: exit 1, 1 failed, 11 passed
2026-10-12T09:15:02-05:00 | edit: src/dates.py | change the parse format string to %Y-%m-%d | ok: 1 line changed
2026-10-12T09:15:20-05:00 | shell: python -m pytest tests/test_dates.py | run the date tests | ok: exit 0, 12 passed
</code></pre>
<p>Each step is <code>ts | tool | action | result</code>, and the result is <code>ok</code>, <code>fail</code> or <code>partial</code> plus a factual detail. The same trace also exists as JSONL with a JSON Schema, and <code>traces fmt</code> converts between the two without loss.</p>
<h2>The CLI</h2>
<p>It needs Python 3.9+ and the standard library only.</p>
<pre><code class="language-sh">traces init --agent claude-code --task "fix the date parser"
export TRACES_FILE=.trace/&lt;printed file&gt;
traces run -- python -m pytest
traces append -t "edit: src/dates.py" -a "fix the format string" -s ok -d "1 line changed"
traces validate
traces stats
</code></pre>
<p><code>traces run</code> runs a command and records its real exit code. <code>traces validate</code> exits 1 if a trace is invalid or hides a failure, for example an <code>ok</code> next to a non-zero exit code, or a retry whose failure was never recorded. <code>traces stats</code> reports per agent, per tool, and the failure rate.</p>
<h2>One pitfall if you record from hooks</h2>
<p>Many hook systems fire their "after tool" event only when a call succeeds. In Claude Code, <code>PostToolUse</code> never sees a failed call. That arrives as <code>PostToolUseFailure</code>. A hook on the success event alone writes a trace that looks clean while every failure is missing. Register the failure event too, then make a command fail on purpose and check that a <code>fail</code> step shows up.</p>
<h2>Where it fits</h2>
<p><a href="http://TRACES.md">TRACES.md</a> is the observability piece of a larger setup. The sibling project is <a href="https://github.com/MaxonT/aisync">aisync</a>: Multi-Agent Context Management, Coordination &amp; Observability. aisync keeps shared rules and a journal across every AI coding tool, and coordinates who is editing what. <a href="http://TRACES.md">TRACES.md</a> is the per-task record of what each agent did. aisync is a separate repo and tool; <a href="http://TRACES.md">TRACES.md</a> works without it.</p>
<h2>Limits</h2>
<p>This is version 0.1 of the spec, so expect changes. The repo is small and has no adoption numbers I would put in an article. It is not affiliated with <a href="http://AGENTS.md">AGENTS.md</a>. It borrows that project's shape: one plain Markdown convention any agent can follow with no SDK.</p>
<p>The repository writes its own traces in <code>.trace/</code>, failures included.</p>
<ul>
<li>Repo (MIT): <a href="https://github.com/MaxonT/TRACES.md">https://github.com/MaxonT/TRACES.md</a></li>
<li>Spec: <a href="https://github.com/MaxonT/TRACES.md/blob/main/SPEC.md">https://github.com/MaxonT/TRACES.md/blob/main/SPEC.md</a></li>
<li>Site: <a href="https://maxont.github.io/TRACES.md/">https://maxont.github.io/TRACES.md/</a></li>
</ul>
<p><em>Originally published on</em> <a href="https://dev.to/maxont/tracesmd-a-plain-text-flight-recorder-for-what-ai-agents-did-1nom"><em>Dev.to</em></a><em>.</em></p>
<p>This post and the repository were written and tested by an AI agent (Claude Code) for the maintainer. First published on DEV: <a href="https://dev.to/maxont/tracesmd-a-plain-text-flight-recorder-for-what-ai-agents-did-1nom">https://dev.to/maxont/tracesmd-a-plain-text-flight-recorder-for-what-ai-agents-did-1nom</a></p>
]]></content:encoded></item><item><title><![CDATA[aisync: one local hub for rules and coordination across AI coding agents]]></title><description><![CDATA[aisync is a local hub for Multi-Agent Context Management, Coordination & Observability. If you run Claude Code, Codex and Cursor on the same machine, each…]]></description><link>https://maxont.hashnode.dev/aisync-one-local-hub-for-rules-and-coordination-across-ai-coding-agents</link><guid isPermaLink="true">https://maxont.hashnode.dev/aisync-one-local-hub-for-rules-and-coordination-across-ai-coding-agents</guid><dc:creator><![CDATA[Ming]]></dc:creator><pubDate>Mon, 16 Nov 2026 08:37:18 GMT</pubDate><content:encoded><![CDATA[<p>aisync is a local hub for Multi-Agent Context Management, Coordination &amp; Observability.</p>
<p>If you run Claude Code, Codex and Cursor on the same machine, each tool keeps its own rules, two of them can edit the same file, and nothing records who did what. aisync is a small local hub that tries to fix those three things.</p>
<h2>What it is</h2>
<p>aisync keeps everything in <code>~/.ai-sync</code>, which is a plain git repo. It is agent-agnostic at its core. It ships native hooks for Claude Code, Codex and Cursor, and other agents can use the same hub through a CLI, an MCP server or shared instruction files.</p>
<h2>What it does</h2>
<ul>
<li><strong>Shared rules.</strong> Rules are shared across tools and synced with a 3-way merge, so a rule written once reaches every agent.</li>
<li><strong>A verifiable journal.</strong> Agent activity is written to a hash-chained journal. <code>aisync verify</code> checks the chain for edits.</li>
<li><strong>File claims.</strong> An agent declares the files it is about to touch. An overlapping claim is detected and reported with exit code 3, so two agents can avoid editing the same file.</li>
<li><strong>Mid-session news.</strong> Where hooks are available, an agent is told what other agents did while it was working.</li>
</ul>
<h2>Limits</h2>
<p>File claims are cooperative, not OS-level locks: agents have to use the claim protocol. Hash-chain verification detects changes to recorded events. It does not prove that every claimed action happened.</p>
<h2>Try it</h2>
<p>It is MIT licensed, needs Python 3.11 or newer and has no runtime dependencies.</p>
<pre><code class="language-bash">pip install aisync-cli
</code></pre>
<p>Source and docs: <a href="https://github.com/MaxonT/aisync">https://github.com/MaxonT/aisync</a> Website: <a href="https://maxont.github.io/aisync/">https://maxont.github.io/aisync/</a></p>
<p>This post was written and tested by an AI agent (Claude Code) for the maintainer.</p>
<p><em>Originally published on</em> <a href="http://Dev.to"><em>Dev.to</em></a><em>:</em> <a href="https://dev.to/maxont/aisync-one-local-hub-for-rules-and-coordination-across-ai-coding-agents-4egp"><em>https://dev.to/maxont/aisync-one-local-hub-for-rules-and-coordination-across-ai-coding-agents-4egp</em></a></p>
]]></content:encoded></item></channel></rss>