<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: chowyu</title>
    <description>The latest articles on DEV Community by chowyu (@chowyu12).</description>
    <link>https://dev.to/chowyu12</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F3971363%2F1a718455-75dc-463a-940e-b06417e82f97.png</url>
      <title>DEV Community: chowyu</title>
      <link>https://dev.to/chowyu12</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/chowyu12"/>
    <language>en</language>
    <item>
      <title>How AIClaw 3.12.14 Shows Sub-Agent Progress Without Leaving the Parent Chat</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Sat, 21 Nov 2026 23:59:08 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-31214-shows-sub-agent-progress-without-leaving-the-parent-chat-5a76</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-31214-shows-sub-agent-progress-without-leaving-the-parent-chat-5a76</guid>
      <description>&lt;p&gt;A parent agent can delegate a review and keep working while the child runs. From the parent chat, it is useful to see whether the review is still running and what the child has recorded, especially when several tasks are underway. AIClaw v3.12.14 adds a read-only sub-agent view to the desktop conversation details panel. &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.14" rel="noopener noreferrer"&gt;Release notes&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Follow the task tree from the parent chat
&lt;/h2&gt;

&lt;p&gt;On a desktop viewport at least 1,280 CSS pixels wide, open Conversation Details in an existing chat. If that chat has delegated sessions, the panel lists them by task title and status. A child that delegates work of its own appears with another level of indentation. The renderer builds this tree from session parent IDs. Two sessions in the same workspace can have different task trees. &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.14/apps/desktop/src/renderer/App.vue" rel="noopener noreferrer"&gt;Desktop layout&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.14/apps/desktop/src/renderer/views/SessionAgents.vue" rel="noopener noreferrer"&gt;Sub-agent panel&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Selecting a child opens its transcript inside the panel. The renderer requests that child's saved history and combines it with live timeline entries by entry ID, giving the live copy precedence when an ID appears in both. A live turn can show a running or interrupted state while the parent chat stays open. When there is no live status, the panel can use the status supplied with the session summary. &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.14/apps/desktop/src/renderer/views/SessionAgents.vue" rel="noopener noreferrer"&gt;Panel implementation&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.14/tools/claw-agent/internal/server/server.go" rel="noopener noreferrer"&gt;Session summaries&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What the panel and tests cover
&lt;/h2&gt;

&lt;p&gt;The panel reads history and renders text and expandable steps. Opening it leaves the active conversation in place and does not resume the child. The Electron smoke fixture checks stored history, verifies that no child resume call occurs, and injects turn events to check running and interrupted states. A Go collaboration test separately checks that a completed child can be identified after returning an answer. These checks use fixtures. They cover the read-only interaction and status transitions, while the quality and timing of delegated work depend on the actual run. &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.14/scripts/smoke-work.cjs" rel="noopener noreferrer"&gt;Electron smoke test&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.14/tools/claw-agent/internal/server/collab_test.go" rel="noopener noreferrer"&gt;Go collaboration tests&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/actions/runs/44658852259" rel="noopener noreferrer"&gt;Release workflow&lt;/a&gt;&lt;/p&gt;

</description>
      <category>agents</category>
      <category>ai</category>
    </item>
    <item>
      <title>How AIClaw 3.12.15 Keeps CLI Profiles Separate from the Desktop App</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Sat, 21 Nov 2026 00:03:16 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-31215-keeps-cli-profiles-separate-from-the-desktop-app-1lj6</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-31215-keeps-cli-profiles-separate-from-the-desktop-app-1lj6</guid>
      <description>&lt;p&gt;A terminal agent needs a model and a place to save conversations. If it inherits both from a desktop app, changing providers for a shell experiment can affect the desktop, and picking up a terminal session depends on how the desktop stores its history. AIClaw v3.12.15 ships a standalone &lt;code&gt;aiclaw&lt;/code&gt; binary with its own defaults for both. &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.15" rel="noopener noreferrer"&gt;Release and CLI downloads&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Give the terminal its own profile
&lt;/h2&gt;

&lt;p&gt;The CLI defaults to &lt;code&gt;~/.aiclaw/cli&lt;/code&gt;. It keeps the provider database and configuration there, along with its session store. &lt;code&gt;--data-home&lt;/code&gt; selects another profile so you can keep a separate provider, default model, and history for an experiment. &lt;code&gt;--cwd&lt;/code&gt; selects the workspace within that profile. &lt;code&gt;resume --last&lt;/code&gt; looks for a session in the selected workspace, and &lt;code&gt;resume SESSION_ID&lt;/code&gt; selects a stored session directly. &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.15/tools/claw-agent/internal/cli/config.go" rel="noopener noreferrer"&gt;CLI configuration&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.15/README.md#terminal-cli" rel="noopener noreferrer"&gt;Terminal CLI guide&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The terminal starts the Go agent kernel in the same process and talks to it over JSON-RPC through &lt;code&gt;net.Pipe&lt;/code&gt;. It starts the kernel in models-only mode, which skips desktop plugins and channels. You can explicitly pass &lt;code&gt;--app-db&lt;/code&gt; to reuse the desktop model database. Session storage still follows the CLI profile. &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.15/tools/claw-agent/internal/cli/rpc.go" rel="noopener noreferrer"&gt;RPC connection&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.15/tools/claw-agent/internal/server/server.go" rel="noopener noreferrer"&gt;Kernel startup&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Run once, then pick up the session
&lt;/h2&gt;

&lt;p&gt;After configuring a provider and default model in a profile, run these commands from the same project directory:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;aiclaw &lt;span class="nb"&gt;exec&lt;/span&gt; &lt;span class="s2"&gt;"Summarize the current project"&lt;/span&gt; --json
aiclaw resume --last
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;exec --json&lt;/code&gt; emits one JSON event per line on stdout, so a script can process events as they arrive. If a turn requests approval or asks for input, &lt;code&gt;exec&lt;/code&gt; exits with an error. Use the interactive terminal to answer those prompts. &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.15/tools/claw-agent/internal/cli/turn.go" rel="noopener noreferrer"&gt;Turn handling&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What the tests cover
&lt;/h2&gt;

&lt;p&gt;The regression tests use a local fixture model endpoint to exercise JSON output, session persistence and resume, profile isolation, approval, and interruption. The release workflow passed for the tagged commit. Those tests establish CLI behavior against a controlled endpoint. Compatibility with a particular hosted model depends on its API. &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.15/tools/claw-agent/internal/cli/cli_test.go" rel="noopener noreferrer"&gt;CLI tests&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/actions/runs/44713327303" rel="noopener noreferrer"&gt;Release workflow&lt;/a&gt;&lt;/p&gt;

</description>
      <category>agents</category>
      <category>ai</category>
    </item>
    <item>
      <title>How AIClaw 3.12.13 Loads Selected Skills Before the First Model Request</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Fri, 20 Nov 2026 00:05:40 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-31213-loads-selected-skills-before-the-first-model-request-4ee0</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-31213-loads-selected-skills-before-the-first-model-request-4ee0</guid>
      <description>&lt;p&gt;A skill catalog is useful when the agent needs to discover a workflow. The timing matters when the user already picked one. If the instructions arrive through a tool call, the first model request still has to decide to make that call from the catalog and the user's message alone.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.13" rel="noopener noreferrer"&gt;AIClaw v3.12.13&lt;/a&gt; gives an explicit selection a different path. This behavior ships in the tagged release, and the source links below point to that version.&lt;/p&gt;

&lt;h2&gt;
  
  
  Put the selected instructions in the first request
&lt;/h2&gt;

&lt;p&gt;Imagine a mounted skill named &lt;code&gt;release-check&lt;/code&gt; and a request like “$release-check summarize these changes.” The relevant instructions can shape the model's first response or tool choice. There is no prerequisite &lt;code&gt;load_skill&lt;/code&gt; round trip for the excerpt. If the user just asks for a summary, the model can discover an applicable skill from the catalog and call &lt;code&gt;load_skill&lt;/code&gt; as needed.&lt;/p&gt;

&lt;p&gt;The kernel matches complete &lt;code&gt;$skill-name&lt;/code&gt; references against mounted skills. It appends the selected text to the outgoing request in memory. The stored user message keeps its original text. A retry after context compaction can still carry the selection, and the next turn starts with fresh selection state. See the &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.13/tools/claw-agent/internal/agent/turn.go" rel="noopener noreferrer"&gt;request assembly&lt;/a&gt; and &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.13/tools/claw-agent/internal/agent/skill_prompt.go" rel="noopener noreferrer"&gt;skill prompt code&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Give the catalog its own budget
&lt;/h2&gt;

&lt;p&gt;The catalog uses an estimated budget of up to 2,000 tokens, reduced to 2% of the configured context window when that yields a smaller budget. AIClaw shortens descriptions to retain more names. If names alone exceed the budget, it can omit entries. An exact reference to a mounted skill still works even if the catalog leaves it out.&lt;/p&gt;

&lt;p&gt;Selected text has a separate limit of 8 KiB per skill excerpt and 32 KiB across selected blocks. An excerpt shortened by the byte limit directs the model to &lt;code&gt;load_skill&lt;/code&gt; for more detail. These are prompt assembly limits. The catalog uses a token estimate, and supplying instructions gives no guarantee that a model will follow them.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the tests establish
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.13/tools/claw-agent/internal/agent/skill_prompt_test.go" rel="noopener noreferrer"&gt;kernel regressions&lt;/a&gt; inspect requests captured by a test model. They cover first-request inclusion, turn scoping, a compaction retry, catalog limits, and UTF-8 truncation. Those checks establish what the kernel sends. They do not measure live-model instruction following, latency, or provider token usage.&lt;/p&gt;

</description>
      <category>agents</category>
      <category>ai</category>
    </item>
    <item>
      <title>How AIClaw 3.12.10 Keeps Scratch Files Out of Project Changes</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Thu, 19 Nov 2026 00:04:56 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-31210-keeps-scratch-files-out-of-project-changes-1n9o</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-31210-keeps-scratch-files-out-of-project-changes-1n9o</guid>
      <description>&lt;p&gt;A helper script can be useful for an agent turn and still be noise in a project review. If an agent writes a small script to check a calculation, the script may be worth keeping in the execution trace. A user reviewing the project usually wants to see the files they asked to create or change.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.10" rel="noopener noreferrer"&gt;AIClaw 3.12.10&lt;/a&gt; gives each session a scratch directory and uses that location to decide which file-tool writes belong in the change list.&lt;/p&gt;

&lt;h2&gt;
  
  
  Give the session one place for temporary work
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.10/tools/claw-agent/internal/agent/session.go" rel="noopener noreferrer"&gt;session implementation&lt;/a&gt; creates a directory under the OS temp location on first execution. Later turns in that session reuse it. The agent is told to put helper scripts and intermediate files there and to keep requested deliverables in the workspace or at the user's requested destination.&lt;/p&gt;

&lt;p&gt;Both one-shot commands and persistent shells receive the directory through &lt;code&gt;AICLAW_TMPDIR&lt;/code&gt;, &lt;code&gt;TMPDIR&lt;/code&gt;, &lt;code&gt;TMP&lt;/code&gt;, and &lt;code&gt;TEMP&lt;/code&gt;. The command still starts in the project working directory. A tool that writes relative to its working directory can therefore still write to the project. It has to use the scratch path or honor a temp environment variable to put a file there.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keep the execution trace useful
&lt;/h2&gt;

&lt;p&gt;For file-tool writes, the check uses the resolved path. A write into the session's scratch directory can still return its path in the execution result. AIClaw skips the project change snapshot and artifact registration for that write. Workspace changes and deliverables continue through the usual recording path. The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.10/tools/claw-agent/internal/tools/paths.go" rel="noopener noreferrer"&gt;tool path rules&lt;/a&gt; also keep an escaping symlink subject to the rules for its resolved destination.&lt;/p&gt;

&lt;p&gt;Scratch storage lasts for the live session. Closing it schedules cleanup, waiting for active work when needed. Reopening saved history allocates a fresh directory on the next execution. An old path may still be readable in the trace after the file itself has been removed. The scratch directory is a place to put temporary work. Command access still depends on the normal execution policy.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the tests cover
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.10/tools/claw-agent/internal/agent/scratch_test.go" rel="noopener noreferrer"&gt;session regression&lt;/a&gt; checks that a scratch path remains in the tool result without becoming an artifact or change snapshot. It also checks reuse, cross-session classification, symlink handling, and cleanup. The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.10/tools/claw-agent/internal/tools/shellsession_test.go" rel="noopener noreferrer"&gt;shell regression&lt;/a&gt; checks the four environment variables and writes a temporary file in both execution modes. The release notes report passing Go race checks for the added tests. Those checks cover the application's own behavior. Third-party programs can choose their own temporary locations.&lt;/p&gt;

</description>
      <category>agents</category>
      <category>ai</category>
      <category>automation</category>
      <category>tools</category>
    </item>
    <item>
      <title>How AIClaw 3.12.5 Keeps Original Attachments Readable Beyond a Preview</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Wed, 18 Nov 2026 00:03:48 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-3125-keeps-original-attachments-readable-beyond-a-preview-k84</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-3125-keeps-original-attachments-readable-beyond-a-preview-k84</guid>
      <description>&lt;p&gt;An attachment preview can be useful and still be incomplete evidence. If an upload is reduced to a bounded text extraction and the original is discarded, the agent cannot return to a later page or a missing worksheet when a follow-up question needs it.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.5" rel="noopener noreferrer"&gt;AIClaw 3.12.5&lt;/a&gt; changes that boundary. It retains the uploaded file and gives the agent a read-only tool for requesting relevant portions. This is shipped behavior in 3.12.5; the source links below are pinned to that release, rather than to subsequent changes on master.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keep the original separate from model context
&lt;/h2&gt;

&lt;p&gt;The preceding &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.4" rel="noopener noreferrer"&gt;3.12.4 release&lt;/a&gt; introduced PDF, Office and archive uploads with bounded text extraction. Its 128 KiB text limit protected message size, but a truncated extraction could not substitute for the original file.&lt;/p&gt;

&lt;p&gt;The new &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.5/apps/desktop/src/main/attachment-store.ts" rel="noopener noreferrer"&gt;attachment store&lt;/a&gt; saves the original bytes alongside metadata: an identifier, filename, byte count and SHA-256 digest. Sending adds a file description and reference to the message instead of inserting the entire extraction into the prompt. The visible bubble hides the reference identifier.&lt;/p&gt;

&lt;p&gt;Retention does not mean the whole document is silently sent to the model. File content enters a tool result when the agent requests it. Images and audio continue through their existing input paths.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bind access when the message is sent
&lt;/h2&gt;

&lt;p&gt;Selecting a file first creates a staged upload. A random claim token allows the host to associate it with its initial conversation at send time. The stored token is hashed, and the claim token is excluded from message text and public tool metadata. An upload that has not been sent is unavailable to the attachment-reading tool.&lt;/p&gt;

&lt;p&gt;Session restoration reuses the on-disk association. A fork adds another association to the same original rather than copying its bytes. The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.5/apps/desktop/src/main/session.ts" rel="noopener noreferrer"&gt;host request handler&lt;/a&gt; also follows a child agent's actual stored parent chain when resolving inherited access.&lt;/p&gt;

&lt;p&gt;These are application access rules, not a claim that the operating-system account cannot inspect its own files. Deleting a conversation removes associations; this implementation does not automatically garbage-collect unsent or unassociated originals.&lt;/p&gt;

&lt;h2&gt;
  
  
  Ask for an index, then the relevant content
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.5/tools/claw-agent/internal/agent/attachments.go" rel="noopener noreferrer"&gt;read_attachment tool&lt;/a&gt; is registered as a read operation. Its handler supplies the session identifier from the execution environment, rather than trusting a model-supplied session identifier.&lt;/p&gt;

&lt;p&gt;Omitting attachmentId lists accessible files. For a selected file, mode=index exposes numbered PDF pages, Word parts, Excel sheets, PowerPoint slides or archive members. An archive member containing a supported document can itself be indexed.&lt;/p&gt;

&lt;p&gt;In mode=read, section is one-based and defaults to 1. Archive reads also take the exact member name. Content is returned in bounded chunks: 16 KiB by default and at most 32 KiB per read. In read mode, offset is a UTF-8 byte offset; in index mode it is an entry position. A truncated result supplies nextOffset for continuation.&lt;/p&gt;

&lt;p&gt;That distinction matters for Chinese text and other multibyte characters. Guessing a character count as a byte offset can start inside a code point. Continuing with the returned offset avoids that mismatch and lets a follow-up reach text beyond the former preview limit.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bound the parser without claiming free random access
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.5/apps/desktop/src/main/document-parser.ts" rel="noopener noreferrer"&gt;parser&lt;/a&gt; returns the requested logical section. That does not guarantee constant-time access to the underlying file: Office and archive formats may require expansion and indexing, and some legacy readers scan the document.&lt;/p&gt;

&lt;p&gt;Parsing runs in a separate, time-limited process. The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.5/apps/desktop/src/main/document-reader.ts" rel="noopener noreferrer"&gt;reader queue&lt;/a&gt; serializes work and admits up to four active or waiting requests. Parsed results are cached by query and cache version, while every read still checks the original's size and digest before using a result.&lt;/p&gt;

&lt;p&gt;The release also fixes content fidelity. PDF.js ships with matching worker, CMaps and standard fonts for selectable Chinese text. Excel preserves formatted dates, percentages and booleans, and labels formula caches separately from missing cached results without evaluating formulas. Word retains tabs and line breaks; PowerPoint includes speaker notes.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.5/docs/design/file-attachments.md" rel="noopener noreferrer"&gt;documented limits&lt;/a&gt; remain explicit: 25 MiB per uploaded file, up to 32 files per message, and archive limits of 512 entries and 64 MiB of expanded content. Encrypted archives, unsafe paths and links are rejected. Scanned PDF pages still need OCR, which this path does not perform. Originals discarded by an older version cannot be reconstructed by upgrading.&lt;/p&gt;

&lt;h2&gt;
  
  
  Separate the test evidence from the design
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.5/scripts/test-attachment-store.ts" rel="noopener noreferrer"&gt;store regressions&lt;/a&gt; check retained bytes beyond the old preview boundary, session claims, restoration, fork access, cache reuse, tampering and linked-file rejection.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.5/scripts/test-document-attachments.ts" rel="noopener noreferrer"&gt;document tests&lt;/a&gt; cover content formatting, relationship aliases, notes, CJK PDFs, continuation ranges and archive limits. They also run the bundled worker outside the checkout using staged production dependencies, including a Chinese PDF fixture.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.5" rel="noopener noreferrer"&gt;release notes&lt;/a&gt; report a local make check run with 451 unit tests, 403 work UI checks, Go race tests, and kernel and desktop smoke tests. Those are reported local results, not a performance benchmark or a claim that every real-world document parses correctly. This article reviews the published source and release evidence; it does not claim a new test run.&lt;/p&gt;

&lt;p&gt;The practical improvement is recoverability: a bounded result can stay small while the original remains available for the next question.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.5" rel="noopener noreferrer"&gt;AIClaw 3.12.5 release&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/commit/c54839e9af643c6de29fba27f29f311cee2b1106" rel="noopener noreferrer"&gt;Attachment architecture commit&lt;/a&gt;&lt;/p&gt;

</description>
      <category>opensource</category>
    </item>
    <item>
      <title>How AIClaw 3.12.1 Makes Diagnostics Export Work Outside the Checkout</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Tue, 17 Nov 2026 01:11:13 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-3121-makes-diagnostics-export-work-outside-the-checkout-km5</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-3121-makes-diagnostics-export-work-outside-the-checkout-km5</guid>
      <description>&lt;p&gt;A diagnostics export can work in development and still prevent the packaged app from starting. The code runs inside a checkout with its dependencies installed; the shipped application runs with only the modules copied into its staging directory.&lt;/p&gt;

&lt;p&gt;AIClaw 3.12.1 fixes that boundary for its local diagnostics ZIP. The &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.1" rel="noopener noreferrer"&gt;published release&lt;/a&gt; includes both the export feature and the packaging correction needed to ship it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Build a small archive from an explicit allowlist
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.1/apps/desktop/src/main/diagnostics.ts" rel="noopener noreferrer"&gt;diagnostics builder&lt;/a&gt; creates exactly two ZIP entries: &lt;code&gt;report.txt&lt;/code&gt; and &lt;code&gt;recent.log&lt;/code&gt;. It serializes the report and the in-memory diagnostic log; it does not recursively collect the application data directory, configuration database, or conversation files.&lt;/p&gt;

&lt;p&gt;The report includes version and platform information, runtime state, mount results, and useful directory paths. The diagnostic ring defaults to the most recent 400 nonempty log lines. That is a line-count bound, not a byte limit or a complete execution history.&lt;/p&gt;

&lt;p&gt;Both archive entries pass through credential-pattern redaction. The rules cover shapes such as bearer tokens, secret-like key/value pairs, sensitive URL parameters, URL user information, and cookie headers.&lt;/p&gt;

&lt;p&gt;This is best-effort filtering, not a guarantee that arbitrary log text is safe to publish. Local paths, model names, and other contextual details can remain. Review an exported report before sharing it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keep the handoff local and explicit
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.1/apps/desktop/src/main/index.ts" rel="noopener noreferrer"&gt;main-process export handler&lt;/a&gt; opens a save dialog with a versioned ZIP filename in Downloads. Cancelling returns without writing. Selecting a destination builds the archive and writes it locally, requesting mode &lt;code&gt;0600&lt;/code&gt; when creating the file.&lt;/p&gt;

&lt;p&gt;The export path does not upload the ZIP. It gives the user a file to inspect and choose whether to share. It also stays separate from the network-diagnostics action: exporting the local report does not itself run connection tests.&lt;/p&gt;

&lt;h2&gt;
  
  
  A dependency must exist in the shipped application
&lt;/h2&gt;

&lt;p&gt;ZIP creation uses &lt;code&gt;fflate&lt;/code&gt;, imported by the main-process diagnostics module. Adding the package to the workspace made local development work, but AIClaw's packaging process deliberately constructs a separate runtime directory rather than shipping the repository's entire &lt;code&gt;node_modules&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.1" rel="noopener noreferrer"&gt;3.12.1 release notes&lt;/a&gt; document the missing staging entry: the preceding package omitted &lt;code&gt;fflate&lt;/code&gt;, preventing startup and causing the macOS post-signing smoke test to time out.&lt;/p&gt;

&lt;p&gt;The fix adds it to &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.1/scripts/stage-host-dependencies.mjs" rel="noopener noreferrer"&gt;host dependency staging&lt;/a&gt;. General host modules are staged separately from the native Cua runtime. The same host module set is copied for the supported packaging targets.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.1/scripts/smoke-packaged-computer.mjs" rel="noopener noreferrer"&gt;packaged-app smoke script&lt;/a&gt; also resolves &lt;code&gt;fflate&lt;/code&gt; from the packaged application before waiting for renderer readiness. A missing ZIP module can now produce a direct dependency failure instead of being obscured by a renderer-readiness timeout.&lt;/p&gt;

&lt;h2&gt;
  
  
  Test the archive and the packaging boundary separately
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.1/scripts/test-diagnostics.ts" rel="noopener noreferrer"&gt;diagnostics tests&lt;/a&gt; unzip the result, check the exact entry names, and verify that fixture credentials are absent while useful report information remains. Those tests check the export data; they do not establish that an installer includes the ZIP library.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.12.1/scripts/test-computer-install.ts" rel="noopener noreferrer"&gt;isolated dependency regression&lt;/a&gt; addresses that second question. It stages production dependencies into a temporary directory, writes a probe there, and starts a separate Node process from that directory with &lt;code&gt;NODE_PATH&lt;/code&gt; empty. The probe imports &lt;code&gt;fflate&lt;/code&gt; and completes a ZIP round trip without relying on the checkout's module resolver.&lt;/p&gt;

&lt;p&gt;The release notes report that this test reproduced &lt;code&gt;ERR_MODULE_NOT_FOUND&lt;/code&gt; before the fix. They also report local &lt;code&gt;make check&lt;/code&gt; and a signed macOS arm64 package launched from &lt;code&gt;/tmp&lt;/code&gt; with an isolated profile. The reported package checks covered renderer/preload startup, shipped modules, the embedded driver, and host attribution, without desktop input. That evidence does not mean every platform or real desktop task was exercised locally. This post reviews the public source and release evidence; it does not claim a new build run.&lt;/p&gt;

&lt;p&gt;The useful boundary is concrete: the archive has a fixed content set, the save action stays local, and a production dependency is tested where users will actually need it—outside the development checkout.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.12.1" rel="noopener noreferrer"&gt;AIClaw 3.12.1 release&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/commit/418f779515378d55460977376062dcf574453130" rel="noopener noreferrer"&gt;Packaging fix&lt;/a&gt;&lt;/p&gt;

</description>
      <category>electron</category>
      <category>testing</category>
      <category>opensource</category>
    </item>
    <item>
      <title>How AIClaw 3.11.5 Separates Installed Versions from Published Release History</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 01:35:23 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-3115-separates-installed-versions-from-published-release-history-43h0</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-3115-separates-installed-versions-from-published-release-history-43h0</guid>
      <description>&lt;p&gt;An update screen has to answer two different questions: which version is running here, and what has actually been published? A tag pushed to GitHub is not enough to answer the second question. A failed release workflow can leave a tag behind without producing a GitHub Release.&lt;/p&gt;

&lt;p&gt;AIClaw 3.11.5 adds an About page that brings the installed version, an update check, and recent release notes into settings. The useful part is how it keeps local version information and remote release history independent.&lt;/p&gt;

&lt;h2&gt;
  
  
  Read the installed version locally
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.5/apps/desktop/src/renderer/views/AboutView.vue" rel="noopener noreferrer"&gt;About view&lt;/a&gt; asks the existing Electron bridge for the application version. It separately loads release notes through a read-only IPC endpoint. A failed history request therefore does not prevent the page from showing the local version.&lt;/p&gt;

&lt;p&gt;The Check for updates button uses the existing update action. It does not infer update availability from the list of release notes. That keeps browsing release history separate from deciding whether a newer version is available.&lt;/p&gt;

&lt;h2&gt;
  
  
  Show releases, not every tag
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.5/apps/desktop/src/main/release-notes.ts" rel="noopener noreferrer"&gt;release-notes reader&lt;/a&gt; requests the project’s public GitHub Releases endpoint with a ten-second timeout. It accepts only entries explicitly marked as neither drafts nor prereleases, with a published timestamp and a tag matching the stable &lt;code&gt;vX.Y.Z&lt;/code&gt; form.&lt;/p&gt;

&lt;p&gt;The implementation requests the first ten API results, filters them, and returns at most ten notes. That is a bounded recent history, not a complete archive: if the first page contains prereleases, the resulting list can have fewer than ten entries. A tag with no published release never enters this list.&lt;/p&gt;

&lt;p&gt;Each accepted entry contains the tag, publication time, note body, and a release link. The link is constructed from the fixed AIClaw repository address and validated tag rather than copied from a response-provided URL. Note bodies are capped at 100,000 characters per entry and displayed through the existing Markdown renderer.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keep failure distinct from an empty history
&lt;/h2&gt;

&lt;p&gt;The page has separate loading, failure, and empty states. A failed HTTP request or an invalid top-level response stays an error; it is not converted into an empty list that could misleadingly suggest there are no releases. The failure state provides a retry button. A published entry without a note body gets its own “no release notes” message.&lt;/p&gt;

&lt;p&gt;This is still an online history view. It does not provide an offline archive, paginate through every past release, or prove that a downloaded installer has been exercised on a particular machine.&lt;/p&gt;

&lt;h2&gt;
  
  
  Evidence and scope
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.5/scripts/test-release-notes.ts" rel="noopener noreferrer"&gt;release-note tests&lt;/a&gt; cover stable-release filtering, fixed-repository links, and preservation of HTTP and invalid-response errors. The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.5/scripts/smoke-work.cjs" rel="noopener noreferrer"&gt;desktop smoke suite&lt;/a&gt; also checks that the About page displays the application version and release notes.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.11.5" rel="noopener noreferrer"&gt;3.11.5 release notes&lt;/a&gt; report a passing local &lt;code&gt;make check&lt;/code&gt;, including 381 work UI checks, plus release-note tests under Node 22 in a Linux container. Those checks are distinct from live acceptance of every installer. The GitHub Release itself is now publicly published.&lt;/p&gt;

&lt;p&gt;A small About page can make version support less ambiguous: the installed version comes from the application, the history comes from published releases, and a network failure remains visible as a network failure.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.11.5" rel="noopener noreferrer"&gt;AIClaw 3.11.5 release&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.5/apps/desktop/src/main/release-notes.ts" rel="noopener noreferrer"&gt;Versioned implementation&lt;/a&gt;&lt;/p&gt;

</description>
      <category>electron</category>
      <category>opensource</category>
      <category>softwaredevelopment</category>
      <category>vue</category>
    </item>
    <item>
      <title>How AIClaw 3.11.4 Embeds a Desktop Driver Without Hiding Its Limits</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Sun, 15 Nov 2026 00:03:51 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-3114-embeds-a-desktop-driver-without-hiding-its-limits-22dl</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-3114-embeds-a-desktop-driver-without-hiding-its-limits-22dl</guid>
      <description>&lt;p&gt;A desktop agent needs more than a screenshot and a click. It needs a way to target the intended window, manage an automation session, and explain what happened when an application cannot accept a background action. It also needs a permission model users can actually understand.&lt;/p&gt;

&lt;p&gt;AIClaw 3.11.4 changes the desktop automation integration to use an embedded Cua Driver. The goal is to run the driver under the main application rather than ask users to install a second desktop-control app. That changes the packaging and permission boundary, but it does not make every application safely controllable in the background.&lt;/p&gt;

&lt;h2&gt;
  
  
  One host, separate automation sessions
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.4/apps/desktop/src/main/cua-runtime.ts" rel="noopener noreferrer"&gt;embedded runtime&lt;/a&gt; starts the pinned Cua Driver through the SDK from Electron’s main process. The project &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.4/tools/cua-driver/runtime.json" rel="noopener noreferrer"&gt;pins the driver version and artifact checksums&lt;/a&gt;; its build stages the matching executable and libraries instead of downloading an unpinned latest version at runtime.&lt;/p&gt;

&lt;p&gt;On macOS, the integration checks that permission attribution is to the host and that the driver reports an embedded identity. The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.4/docs/design/cua-driver.md" rel="noopener noreferrer"&gt;design notes&lt;/a&gt; describe screen recording and accessibility permissions as belonging to AIClaw in the packaged app and to Electron in development. Whether an existing macOS permission remains valid still depends on the system’s assessment of the host’s signing identity.&lt;/p&gt;

&lt;p&gt;Each chat turn gets its own connection and driver session. Closing the last connection stops the shared driver; ending a turn should not replay its previous inputs. This separation gives the host a place to manage snapshots and connection lifetime without asking the model to manage a separate desktop application.&lt;/p&gt;

&lt;h2&gt;
  
  
  Background-first, not background-guaranteed
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.4/apps/desktop/src/main/computer.ts" rel="noopener noreferrer"&gt;host controller&lt;/a&gt; targets an explicit process and window. It prefers background delivery and can group known sequential actions into one batch with a final observation. If a single action is explicitly refused as unavailable in the background, the host can fall back to the foreground; the code also tries to restore the previous window without overriding a subsequent user switch.&lt;/p&gt;

&lt;p&gt;That fallback is meaningful behavior, not a promise of silent operation. For turns recognized as explicitly background-only, the host disables batch fallback and stops further desktop calls after a foreground-only refusal. The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.4/tools/claw-agent/internal/agent/computer.go" rel="noopener noreferrer"&gt;turn policy&lt;/a&gt; uses explicit phrase matching to recognize that restriction, so it should not be described as a complete understanding of every possible user request.&lt;/p&gt;

&lt;p&gt;The controller also stops desktop calls after a reported locked screen or repeated empty full accessibility reads. Those signals help avoid continuing an unreliable automation sequence, but an empty tree alone is not proof of a particular cause. An uncertain or partially completed input still needs observation; a batch should not simply be replayed.&lt;/p&gt;

&lt;h2&gt;
  
  
  Platform contracts matter
&lt;/h2&gt;

&lt;p&gt;Even at one driver version, platform schemas are not identical. For example, the Linux and Windows screenshot paths return PNG without the macOS &lt;code&gt;screenshot_format&lt;/code&gt; parameter. AIClaw’s &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.4/apps/desktop/src/main/cua-policy.ts" rel="noopener noreferrer"&gt;argument policy&lt;/a&gt; removes unsupported screenshot options where appropriate and rejects some Linux options when dropping them would change the requested behavior.&lt;/p&gt;

&lt;p&gt;That distinction matters: accepting an option and quietly ignoring it could make an agent believe it created a separate application instance or performed a specific accessibility action when the platform did not guarantee either.&lt;/p&gt;

&lt;h2&gt;
  
  
  What was tested, and what was not
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.11.4" rel="noopener noreferrer"&gt;3.11.4 release notes&lt;/a&gt; report 417 renderer tests under Node 22 in a Linux container and 43 desktop control and watch tests on macOS and Linux. The repository includes &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.4/scripts/test-computer-control.ts" rel="noopener noreferrer"&gt;controller regression tests&lt;/a&gt; for foreground refusal, locked screens, repeated empty reads, and partial batches. Those are distinct from a successful end-to-end task in every real application.&lt;/p&gt;

&lt;p&gt;The same release notes state that a real macOS test verified saved text but did not complete reopening it. Strict background operation can be blocked by macOS menu restrictions, and task latency remains variable. The user and agent also share the target window: background delivery does not create an isolated desktop or prevent concurrent edits.&lt;/p&gt;

&lt;p&gt;Embedding the driver makes ownership and packaging clearer. The practical boundary remains the target application’s actual accessibility and input behavior, and the result still needs to be verified at the point where it matters.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.11.4" rel="noopener noreferrer"&gt;AIClaw 3.11.4 release&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.4/docs/design/cua-driver.md" rel="noopener noreferrer"&gt;Versioned driver design&lt;/a&gt;&lt;/p&gt;

</description>
      <category>agents</category>
      <category>ai</category>
      <category>software</category>
    </item>
    <item>
      <title>How AIClaw 3.11.1 Routes Audio Without Assuming Every Model Can Hear</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Sat, 14 Nov 2026 00:07:02 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-3111-routes-audio-without-assuming-every-model-can-hear-35b2</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-3111-routes-audio-without-assuming-every-model-can-hear-35b2</guid>
      <description>&lt;p&gt;Audio attachments look simple at the interface: attach a clip and ask a question. The routing decision behind that interaction is less simple. A model endpoint may accept text while rejecting audio, and even an audio-capable endpoint may expose a different wire format.&lt;/p&gt;

&lt;p&gt;AIClaw 3.11.1 makes that decision from the selected model’s declared capability and service protocol. When native audio is unavailable or unknown, it uses the configured speech-to-text route instead of silently sending audio bytes to a text-only request.&lt;/p&gt;

&lt;h2&gt;
  
  
  The routing decision
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.1/tools/claw-agent/internal/agent/audio.go" rel="noopener noreferrer"&gt;audio preparation code&lt;/a&gt; enables native input only when &lt;code&gt;AudioInput&lt;/code&gt; is explicitly marked &lt;code&gt;supported&lt;/code&gt; and the selected protocol is Chat Completions or Gemini. WAV and MP3 attachments can follow this path; other formats go through the transcription fallback.&lt;/p&gt;

&lt;p&gt;That is a deliberately narrow claim. A provider being compatible with a protocol does not establish that every model or endpoint accepts audio. The capability setting needs to match the actual service. Responses and other protocols are not treated as native audio routes by this version of the code.&lt;/p&gt;

&lt;p&gt;For native input, the protocol adapters format the same audio differently:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.1/tools/claw-agent/internal/llm/chat_completions.go" rel="noopener noreferrer"&gt;Chat Completions&lt;/a&gt; sends an &lt;code&gt;input_audio&lt;/code&gt; content part with a format and base64 data.&lt;/li&gt;
&lt;li&gt;
&lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.1/tools/claw-agent/internal/llm/gemini.go" rel="noopener noreferrer"&gt;Gemini&lt;/a&gt; sends inline data with the appropriate audio MIME type.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;When a route is not explicitly capable, AIClaw prepares a transcription instead. That depends on a working configured transcription service; it is not a guarantee that any arbitrary attachment will be understood.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keep the request bounded
&lt;/h2&gt;

&lt;p&gt;Native audio is subject to an 8 MiB limit per file and a 180-second request budget. For WAV files, the implementation estimates duration from the data size and byte rate. When it cannot determine duration, it conservatively charges the entire budget. This also matters for MP3 in this implementation: compressed file size is not used as a duration estimate.&lt;/p&gt;

&lt;p&gt;When conversation history is assembled for another model call, the code walks from the newest messages backward and includes clips within the duration budget. Missing files and clips outside the budget are represented by an omission note rather than silently treated as audio the model received. A stored SHA-256 is also checked before reuse when present, so a changed local file is not silently substituted for the original attachment.&lt;/p&gt;

&lt;h2&gt;
  
  
  A rejection is evidence, not a reason to replay
&lt;/h2&gt;

&lt;p&gt;If a service returns one of the recognized audio-specific HTTP 400 codes, the agent records a rejection against the model route only when the request contained exactly one clip. With multiple clips, the response cannot identify which clip caused the failure, so the code does not attribute it to one of them. The corresponding &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.1/tools/claw-agent/internal/agent/audio_test.go" rel="noopener noreferrer"&gt;agent tests&lt;/a&gt; cover duration and fallback behavior, durable rejection, and the no-retry path. The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.1/tools/claw-agent/internal/llm/audio_test.go" rel="noopener noreferrer"&gt;adapter tests&lt;/a&gt; cover native wire formats and unsupported protocols.&lt;/p&gt;

&lt;p&gt;Those are repository tests, not evidence that every provider has been exercised with live audio. In particular, the rejection tracking described here applies to later requests; it should not be read as an automatic replay of the failed request.&lt;/p&gt;

&lt;p&gt;The result is a clearer boundary between capability configuration, protocol serialization, and the evidence the agent actually has. It is a small architectural distinction, but it prevents an attachment UI from promising more than the selected model route can deliver.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.11.1" rel="noopener noreferrer"&gt;AIClaw 3.11.1 release&lt;/a&gt; · &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.11.1/tools/claw-agent/internal/agent/audio.go" rel="noopener noreferrer"&gt;Versioned audio implementation&lt;/a&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>api</category>
      <category>go</category>
      <category>llm</category>
    </item>
    <item>
      <title>How AIClaw 3.10.1 Stops File Names from Becoming Controls Inside Sentences</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Fri, 13 Nov 2026 00:01:40 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-3101-stops-file-names-from-becoming-controls-inside-sentences-35mf</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-3101-stops-file-names-from-becoming-controls-inside-sentences-35mf</guid>
      <description>&lt;p&gt;A file name in an agent answer can mean two different things: an output the user should open, or a detail the answer is discussing. Turning both into file controls makes prose harder to read. It is especially distracting in a heading, where a directory path can become a short filename with a dropdown arrow.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.10.1" rel="noopener noreferrer"&gt;AIClaw 3.10.1&lt;/a&gt; narrows automatic file-card rendering to standalone references. The release is published; the code and tests linked here are pinned to that version.&lt;/p&gt;

&lt;p&gt;The earlier article about opening generated documents described file rows and their opening menu. This update addresses a different decision: when that control should appear at all.&lt;/p&gt;

&lt;h2&gt;
  
  
  Mentioning a file is different from delivering it
&lt;/h2&gt;

&lt;p&gt;Consider this illustrative Markdown:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;The results are in &lt;span class="sb"&gt;`report.md`&lt;/span&gt;; compare them with yesterday's run.

&lt;span class="sb"&gt;`report.md`&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the first paragraph, the filename stays inline code. In the second, the standalone reference becomes a file card. A heading containing &lt;code&gt;~/Library/Caches/go-build&lt;/code&gt; also retains its complete code text instead of becoming an opening control labeled only go-build.&lt;/p&gt;

&lt;p&gt;The distinction applies to local Markdown links too. A link embedded in a sentence keeps its visible label without a file-opening action. A standalone local file link can still produce a card. Titles and table cells do not become attachment rows just because they contain a path.&lt;/p&gt;

&lt;p&gt;This does change how an answer should deliver several files: each intended attachment needs its own standalone paragraph, or a list item containing only that reference. Putting two links in one sentence does not make an attachment list.&lt;/p&gt;

&lt;h2&gt;
  
  
  Use Markdown structure before path recognition
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.1/apps/desktop/src/renderer/markdown.ts" rel="noopener noreferrer"&gt;Markdown renderer&lt;/a&gt; already has a path-shape check. It recognizes plausible extensions and explicit path prefixes while excluding command lines, URLs, and several ambiguous forms. That check remains useful, but path shape alone cannot tell whether the surrounding text is a title, explanation, or delivery.&lt;/p&gt;

&lt;p&gt;The new core rule runs after Markdown inline parsing. It checks whether the inline token belongs to a paragraph and whether, after ignoring whitespace-only text, it contains exactly one inline-code token. Only that candidate receives the standalone-file marker. The inline-code renderer requires both that marker and a recognized path before producing a card.&lt;/p&gt;

&lt;p&gt;Local Markdown links follow a similar context check. When a link has surrounding content, or belongs to a heading or table cell, the rule removes its opening and closing link tokens while retaining its label tokens. An eligible standalone link instead goes through the shared card generator.&lt;/p&gt;

&lt;p&gt;This is a deliberately narrow structural rule. It does not scan every bare word for filenames or classify every visually separate line as an attachment. The code works with parsed paragraphs, so blank lines matter.&lt;/p&gt;

&lt;h2&gt;
  
  
  Preserve actual deliveries and explicit images
&lt;/h2&gt;

&lt;p&gt;The change does not remove the existing open and preview actions for standalone cards. Their visible names can remain compact while the exact path is retained for the existing action route.&lt;/p&gt;

&lt;p&gt;Explicit Markdown image syntax still follows the image renderer. A supported local image can therefore remain visible inline even though an ordinary filename mentioned in prose no longer becomes a file control. This update does not add an extra generated-image gallery.&lt;/p&gt;

&lt;p&gt;The renderer also does not check whether a recognized file exists. Card eligibility is a presentation decision. Actual file access still goes through the application's existing host validation; recognizing a path is not permission to open arbitrary content.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the regression evidence covers
&lt;/h2&gt;

&lt;p&gt;For this article, I verified the renderer and rendering-test files against GitHub's public 3.10.1 source and ran the renderer test suite from a clean checkout at the release commit. &lt;strong&gt;412 tests passed, one was skipped, and none failed.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.1/scripts/test-renderer.ts" rel="noopener noreferrer"&gt;rendering tests&lt;/a&gt; cover complete paths in headings, filenames inside sentences and parentheses, local links in prose, table references, standalone references and list items, multiple inline filenames, command recognition, and explicit image handling. They also retain checks for escaped filenames and exact paths in generated cards.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.10.1" rel="noopener noreferrer"&gt;release notes&lt;/a&gt; separately report successful desktop build and type checks and 376 passing work-interface checks. I did not rerun that Electron suite for this article. Its public &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.1/scripts/smoke-work.cjs" rel="noopener noreferrer"&gt;smoke script&lt;/a&gt; uses controlled host responses to check that sentence references remain code while standalone cards still open and preview through the expected route. That is not a claim of real application launches on every platform.&lt;/p&gt;

&lt;p&gt;The practical result is less surprising prose: discussing a file leaves the sentence intact, while presenting a file on its own still gives the user an explicit next action.&lt;/p&gt;

</description>
      <category>vue</category>
      <category>ux</category>
      <category>opensource</category>
    </item>
    <item>
      <title>How AIClaw Keeps Conversation Search from Rearranging the Sidebar</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Thu, 12 Nov 2026 00:06:08 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-keeps-conversation-search-from-rearranging-the-sidebar-15fb</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-keeps-conversation-search-from-rearranging-the-sidebar-15fb</guid>
      <description>&lt;p&gt;Searching for an old conversation should not change how the rest of the workspace is organized. A project tree answers where work belongs; a search result answers where a particular piece of work can be found. Treating both as the same list makes switching between them harder than it needs to be.&lt;/p&gt;

&lt;p&gt;AIClaw introduced a centered search-and-command panel in &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.9.2" rel="noopener noreferrer"&gt;3.9.2&lt;/a&gt;. The published &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.10.0" rel="noopener noreferrer"&gt;3.10.0 release&lt;/a&gt; retains that interaction and moves its search button into the sidebar header. This article covers that shipped behavior, using source pinned to 3.10.0.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keep the project tree in place
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.0/apps/desktop/src/renderer/views/SessionCommandPalette.vue" rel="noopener noreferrer"&gt;command panel&lt;/a&gt; is a separate Vue component, teleported to the document body. Its backdrop and dialog sit above the workspace instead of replacing project groups with matching conversations.&lt;/p&gt;

&lt;p&gt;With an empty query, it offers actions for the current context: start a conversation, rename or archive the selected conversation, create a project, or navigate to a settings category. Rename and archive appear only when there is a current conversation; starting another conversation is disabled while the runtime is unavailable.&lt;/p&gt;

&lt;p&gt;Typing filters those command labels and descriptions locally. Conversation results are added separately after the session search returns. Each result includes a workspace label, with extra directory detail when the existing grouping helper provides it. Selecting a result uses the normal conversation-opening action.&lt;/p&gt;

&lt;p&gt;The panel does not rebuild project assignments or introduce a second grouping system. Closing it leaves the sidebar available in its existing organization.&lt;/p&gt;

&lt;h2&gt;
  
  
  Debounce the request, not the local commands
&lt;/h2&gt;

&lt;p&gt;The query watcher clears the previous timer and resets the active selection. For a nonempty query, it schedules the session search after 200 milliseconds. Locally available commands can still match while the conversation search is pending.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.0/apps/desktop/src/renderer/store.ts" rel="noopener noreferrer"&gt;renderer store&lt;/a&gt; forwards the query through the existing session-search bridge. It only applies returned results, errors, and loading changes when the stored keyword still equals the keyword associated with that request.&lt;/p&gt;

&lt;p&gt;This keeps a response for a different, older keyword from replacing the current results. It is a keyword check, not a unique request-generation check: it does not distinguish two overlapping requests for the same text. Nor does clearing the query cancel an IPC request that has already started.&lt;/p&gt;

&lt;p&gt;When the component unmounts, it clears its pending debounce timer and resets session-search state. Those are concrete cleanup guarantees; they should not be described as transport-level cancellation.&lt;/p&gt;

&lt;h2&gt;
  
  
  A modal interaction needs a return path
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.0/apps/desktop/src/renderer/views/SessionSidebar.vue" rel="noopener noreferrer"&gt;sidebar shortcut handler&lt;/a&gt; opens the same panel for Command-K and Control-K. It ignores composing input, already-handled events, and the shortcut when another modal dialog is present.&lt;/p&gt;

&lt;p&gt;Opening from the search button records that button as the return target. Opening from the keyboard records the element that had focus. The panel focuses its search input on mount. On unmount, it restores the previous element only if that element remains connected and focus is still within the closing panel or has fallen back to the document body. It does not deliberately take focus away from an unrelated control the user has reached.&lt;/p&gt;

&lt;p&gt;Arrow keys move the selected row while focus stays in the input, and Enter executes that row. The markup exposes the dialog, combobox, listbox, and active option relationship. Tab handling wraps the dialog's eligible input and buttons at its boundaries.&lt;/p&gt;

&lt;p&gt;Escape closes the panel and stops propagation. This matters because the sidebar also handles Escape: dismissing search should not immediately collapse the navigation underneath it. Clicking the backdrop also dismisses the panel when no command is being executed.&lt;/p&gt;

&lt;p&gt;These are keyboard behaviors implemented by the component, not a claim of comprehensive assistive-technology certification.&lt;/p&gt;

&lt;h2&gt;
  
  
  Reuse the existing actions and failure states
&lt;/h2&gt;

&lt;p&gt;Command execution uses a busy flag to block duplicate execution. Failures remain visible inside the panel instead of being treated as a successful navigation. While a command is running, its controls are disabled and the ordinary dismissal paths are blocked.&lt;/p&gt;

&lt;p&gt;Rename delegates to the existing rename form. Archive delegates to the existing archive action and remains a recoverable archive, rather than becoming a new deletion operation. The panel is an entry point to application actions, not a shell-command launcher or a natural-language agent task.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the checks establish
&lt;/h2&gt;

&lt;p&gt;For this article, I checked a clean checkout at the public 3.10.0 commit, verified the panel's bytes against GitHub's tag-pinned source, rebuilt the desktop app, and ran the release's &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.0/scripts/smoke-work.cjs" rel="noopener noreferrer"&gt;desktop work UI smoke script&lt;/a&gt;. All &lt;strong&gt;375 checks passed&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;The relevant checks exercise opening from the header and both keyboard shortcuts, arrow selection, Tab wrapping, Enter into rename, returning focus after cancellation, Escape dismissal, workspace labels in search results, opening a conversation, and backdrop dismissal without changing the workspace groups.&lt;/p&gt;

&lt;p&gt;The suite runs an Electron renderer with controlled host responses. It provides interaction regression evidence, not a real-model workflow, a large-history search benchmark, or a screen-reader acceptance test. The broader local validation in the &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.10.0" rel="noopener noreferrer"&gt;release notes&lt;/a&gt; is separate evidence; it was not all rerun for this article.&lt;/p&gt;

&lt;p&gt;The improvement is a clear separation of jobs: the sidebar keeps the workspace organized, while a temporary panel helps the user find a conversation or invoke a known action.&lt;/p&gt;

</description>
      <category>vue</category>
      <category>ux</category>
      <category>opensource</category>
    </item>
    <item>
      <title>How AIClaw 3.10.0 Builds an Activity Calendar Without Inventing Usage History</title>
      <dc:creator>chowyu</dc:creator>
      <pubDate>Wed, 11 Nov 2026 00:07:07 +0000</pubDate>
      <link>https://dev.to/chowyu12/how-aiclaw-3100-builds-an-activity-calendar-without-inventing-usage-history-6bd</link>
      <guid>https://dev.to/chowyu12/how-aiclaw-3100-builds-an-activity-calendar-without-inventing-usage-history-6bd</guid>
      <description>&lt;p&gt;An activity heatmap looks simple: one square per day, darker colors for more activity. The harder question is what an empty square actually means. Was nothing recorded, did collection start later, or did the request fail?&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.10.0" rel="noopener noreferrer"&gt;AIClaw 3.10.0&lt;/a&gt; adds a welcome screen with separate session and usage calendars. The release is published, and the implementation discussed here is pinned to that tag. The useful change is more specific than the new layout: the screen keeps the meaning and availability of its underlying records visible.&lt;/p&gt;

&lt;h2&gt;
  
  
  Two tabs, two different measurements
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.0/apps/desktop/src/renderer/views/WorkspaceWelcome.vue" rel="noopener noreferrer"&gt;welcome component&lt;/a&gt; starts on the sessions tab. It groups the current session list by each session's creation timestamp. The accompanying caption explicitly says that this is based on the current conversation list.&lt;/p&gt;

&lt;p&gt;That is a creation calendar, not a count of messages, completed agent turns, or time spent working. Resuming an old conversation does not create another session-creation event. A record absent from the current list cannot contribute to this view. This is useful for orientation, but it is not a permanent audit log of all historical activity.&lt;/p&gt;

&lt;p&gt;The usage tab answers a different question. It requests 365 days through the existing desktop usage bridge, then maps each daily record to input tokens plus output tokens. It does not turn those tokens into a currency balance or estimate credits.&lt;/p&gt;

&lt;p&gt;Keeping those measurements separate avoids suggesting that a busy-looking conversation list and heavy model usage must tell the same story.&lt;/p&gt;

&lt;h2&gt;
  
  
  Load usage when it is requested
&lt;/h2&gt;

&lt;p&gt;The component watches the selected metric. Selecting usage calls window.aiclaw.usage.summary(365) when no summary has been loaded. It guards against overlapping loads and retains a successful summary in the component for subsequent tab switches.&lt;/p&gt;

&lt;p&gt;Opening the welcome screen therefore does not itself require a usage-history request. This is a small implementation choice, but it keeps a secondary visualization from adding an eager request to the default view.&lt;/p&gt;

&lt;p&gt;There is also a boundary: this is component-local caching. The code shown here does not implement polling or automatically refresh a successful summary whenever another model request completes.&lt;/p&gt;

&lt;h2&gt;
  
  
  Unknown and zero are different values
&lt;/h2&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.0/apps/desktop/src/renderer/activity-calendar.ts" rel="noopener noreferrer"&gt;calendar helper&lt;/a&gt; takes daily values and an optional first-recorded date. For usage, dates before collection began receive a null value. If there is no first recorded timestamp, the calendar remains unknown rather than inventing a year of zero usage.&lt;/p&gt;

&lt;p&gt;Once the recorded range begins, a missing daily entry is represented as zero. That is the helper's interpretation of the available summary; it cannot independently prove that every request was collected.&lt;/p&gt;

&lt;p&gt;The rendering keeps unknown cells visually subdued and gives them a distinct tooltip. A failed request has an explicit error and retry control. Its total is shown as a dash, so an unavailable result is not presented as a successful zero-token measurement.&lt;/p&gt;

&lt;p&gt;Those states matter even when the chart is decorative. A pale square should not silently make a stronger claim than the storage behind it can support.&lt;/p&gt;

&lt;h2&gt;
  
  
  Calendar arithmetic follows local dates
&lt;/h2&gt;

&lt;p&gt;The helper constructs the last 365 local calendar dates, including today, and pads the grid into complete Sunday-first weeks. Padded dates outside the visible interval are hidden. Future records do not enter the visible-year total.&lt;/p&gt;

&lt;p&gt;It advances dates with calendar operations rather than treating every day as an identical millisecond interval. Session timestamps are grouped into local date keys, and month labels use the selected interface language.&lt;/p&gt;

&lt;p&gt;Color intensity is relative to the largest daily value in the visible interval, with four nonzero levels. It is not a fixed threshold or a normalized comparison across different users and time periods. Two equally dark squares in separate calendars can represent different absolute values; the tooltip supplies the daily count.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the tests establish
&lt;/h2&gt;

&lt;p&gt;For this article, I downloaded the public, tag-pinned helper and its &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.0/scripts/test-activity-calendar.ts" rel="noopener noreferrer"&gt;calendar tests&lt;/a&gt; into a temporary directory and ran them with Node's test runner. All &lt;strong&gt;four tests passed&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;They check the 365-date interval and complete-week padding, future-value exclusion from totals, grouping of real creation timestamps, invalid-timestamp handling, unknown-versus-zero usage, and leap-day coverage without duplicate dates.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://github.com/chowyu12/aiclaw/releases/tag/v3.10.0" rel="noopener noreferrer"&gt;release notes&lt;/a&gt; separately report 411 passing renderer tests with one skipped, 375 passing desktop UI checks, and successful local build and type checks. I did not rerun that broader suite or perform real-provider usage collection for this article. The published &lt;a href="https://github.com/chowyu12/aiclaw/blob/v3.10.0/scripts/smoke-work.cjs" rel="noopener noreferrer"&gt;desktop smoke script&lt;/a&gt; uses controlled fixtures for the welcome screen's request, failure, and retry behavior.&lt;/p&gt;

&lt;p&gt;The calendar is part of the released workspace redesign, not a proposal for an unreleased analytics system. Its practical value comes from showing the records it has, naming the measurement, and leaving missing evidence visible.&lt;/p&gt;

</description>
      <category>vue</category>
      <category>testing</category>
      <category>opensource</category>
    </item>
  </channel>
</rss>
