跪拜 Guibai
← Back to the summary

Agent Session Sync 1.3.2: visual triage for the AI sessions eating your disk

App name: Agent Session Sync (desktop edition) Current version: 1.3.2 Download: GitHub Releases v1.3.2 Same-source CLI / MCP package: cross-agent-sync (command ass)

The previous Juejin post covered the npm package / MCP: how to carry context over when switching between Claude, Codex, and Cursor. This post only covers the desktop app: the same local session data behind a visual interface — see disk usage, browse history by project, open sessions, optionally clean up.

The screenshots in this post come from a local 1.3.2 build; if you exchange images when republishing, replace the files under docs/desktop-shots/, or substitute your own.


1. Why build an App at all?

The CLI and MCP solve "picking up where you left off inside an Agent conversation". Daily work has another class of problems the CLI is not handy for:

Scenario Pain point
Many agents installed locally No way to know who eats how much disk, which project talks the most
Want to review a past question Must remember ass list / ass inputs; paths and references are tedious
Disk running out Cursor / Codex session directories grow to GB scale; want to safely clear old sessions
Demoing to colleagues Want to open a window and see, not type a string of commands
Extending non-built-in agents Want to edit customAgents without hand-editing JSON

So the desktop edition has clear goals:

  1. See: local agents, session counts, disk usage, aggregated by project.
  2. Open: click into a project → click a session → see user input / full info / agent conclusions.
  3. Touch little: original agent sessions are read-only; writes only go into the tool's own directory, and every one is confirmed.
  4. Clean (optional): file-typed sessions can be moved to the trash; shared SQLite stores are not touched.

In one sentence: CLI/MCP handle "handoff"; the desktop app handles "inspection and review".


2. Design

2.1 Relationship with the CLI

The desktop does not reimplement a parser. The architecture is:

Electron window (native HTML/CSS/JS)
        │  preload narrow API
        ▼
Main process IPC + short-lived cache
        │ ELECTRON_RUN_AS_NODE=1
        ▼
Child process runs runtime/cli.js (the same set of adapters as the npm package)
        │ consumes JSON only
        ▼
Local agent session directories (read-only)

Trade-offs:

2.2 Information architecture (five entry points)

Page What it does
Overview KPI + agent data-source table + session count / disk usage charts
Project A given repo: session list, tasks, project notes, right-side session drawer
All Projects Card browsing of repos with local sessions; can rename display name
Cleanup Pick file-typed sessions per agent, move to trash
Settings Paths / version / extended agents (customAgents) / read-only notes

2.3 Hard principles

  1. Source data read-only and self-verifying Never modify Claude / Codex / Cursor session files; writes of decisions, tasks, aliases go only to ~/.local/share/agent-session-sync.

  2. Suggestion ≠ authorization; tool process ≠ conclusion Same as the CLI: notes carry authorization/review concepts; the drawer hides tool turns like ▸ Bash: in agent answers, leaving conclusions front and center.

  3. Cleanup has boundaries Only sources where "one file/dir = one session" are cleaned; shared-SQLite sources like Cursor / OpenCode / Trae / Lingma are not deleted from the desktop, to avoid corrupting the whole database.

  4. Display names only affect this app The ✎ on projects/sessions writes desktop-aliases.json, does not rename disk directories, and does not change agents' native titles.


3. UI tour

3.1 Overview

Which agents are on this machine, whether readable, whether MCP is wired in, how much disk each takes. Below: session-count distribution and disk usage (both aligned in the same agent order). image.png

If it still says "scanning…", refresh and wait a few seconds; Cursor's first full scan is slower.

3.2 All Projects

Browse by repo cards with agent badges; click a card to enter the Project page. Use ✎ to set a display name.

image.png

3.3 Project

After selecting a repo: session / task / decision counts, a session table, and tasks and project notes below. Click a session to open a right-side drawer.

image.png

image.png

Session drawer:

3.4 Cleanup

Pick an agent → list cleanable sessions → clean individually or all (moved to trash, recoverable).

image.png

3.5 Settings

Paths, version, and extend agents: a form to add/remove/edit customAgents, written to ~/.config/agent-session-sync/config.json, shared with the CLI. Dialog height adapts to window; bottom buttons stay visible.

image.png

image.png


4. How to use

4.1 Download and install

Download from Releases · v1.3.2:

Platform File
macOS Apple Silicon Agent-Session-Sync-1.3.2-arm64.dmg (or .zip)
Windows x64 Agent-Session-Sync-1.3.2-setup-x64.exe (or portable zip)

macOS (no Developer ID signature)

  1. Open the DMG, drag to Applications
  2. Eject the DMG, then in Applications right-click → Open
  3. If it says "unidentified": System Settings → Privacy & Security → "Open Anyway"
  4. If "damaged" is falsely reported: xattr -cr "/Applications/Agent Session Sync.app" then right-click open again

Details in the repo desktop/安装说明.md.

Windows Unsigned; SmartScreen → "More info → Run anyway".

4.2 Recommended workflow

  1. Open the app → Overview, refresh, look at local agents and disk.
  2. All Projects locate the target repo, click into Project.
  3. Click a session, switch the right tabs between "user input / full info / agent answer", search keywords if needed.
  4. Disk tight → Cleanup, remove only confirmed file-typed sessions; only emptying the trash truly frees space.
  5. Non-built-in agent → Settings → Extend Agent, fill mapping per jsonl / json / sqlite; save and refresh Overview.

4.3 How it teams with CLI / MCP

You want to… Use
Say "continue that task" in a conversation and auto-resume context Install MCP: ass install, use inside Claude / Codex etc.
Glance at the machine, review history, clean disk Desktop app
Batch handoff in scripts / CI / terminal ass brief / ass inputs / ass task

Data is shared: the app reads the same local sessions; notes and tasks write to the same data directory. The desktop app will not run ass install for you (to avoid writing Electron paths into MCP config).


5. Notes from outside the design

Before building the desktop, I thought the hard part was "drawing the CLI's output". What actually ground on:

These share one product view with the MCP package: guess as little as possible, say plainly what you cannot read, confirm before writing.


6. Related links

Comments

Top 1 of 4 from juejin.cn, machine-translated. The original thread is authoritative.

组合搭配函数

That hard rule about read-only source data is spot-on. Agent session files are each vendor's own territory; the tool only writes in its own directory, so when something goes wrong, responsibility is clear. That counting-consistency pitfall bit me too — the card says 31, clicking in shows only 9, and the default limit truncates without a peep. Explicitly pulling the full set and then aligning by keys really fills the hole. One question: for the shared-SQLite vendors that can't be deleted in the desktop app, how does the cleanup page tell the user — does it just hide the option, or grey it out with an explanation?

code_Bo

Greyed out.

组合搭配函数  → code_Bo

I'll accept the grey-out. For those shared-SQLite vendors, you can't delete in the desktop app anyway; being clickable but non-deletable would be the real trap. But grey-out alone isn't enough — better to write plainly next to the button, "shared libraries aren't deleted in the desktop app," otherwise the user's first reaction is that the UI froze and they'll keep clicking. Are you only greying it out now, or is the reason included as well?