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(commandass)
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:
- See: local agents, session counts, disk usage, aggregated by project.
- Open: click into a project → click a session → see user input / full info / agent conclusions.
- Touch little: original agent sessions are read-only; writes only go into the tool's own directory, and every one is confirmed.
- 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:
- No
distimport: config paths are fixed at module load time; a child process is the cleanest. - Zero frontend framework: vanilla UI, smaller package size and mental overhead.
- Electron + electron-builder: lands faster than SwiftUI or Tauri when there is no full Xcode / no Rust; macOS arm64 DMG + Windows x64 installer/zip.
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
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.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.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.
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).
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.
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.
Session drawer:
- Tabs: user input · full info · agent answer (summary / full)
- Each tab searchable, hits highlighted
- Recent messages on top; assistant answers collapse to two lines by default
- Agent side filters tool/thinking process, conclusions first
3.4 Cleanup
Pick an agent → list cleanable sessions → clean individually or all (moved to trash, recoverable).
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.
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)
- Open the DMG, drag to Applications
- Eject the DMG, then in Applications right-click → Open
- If it says "unidentified": System Settings → Privacy & Security → "Open Anyway"
- 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
- Open the app → Overview, refresh, look at local agents and disk.
- All Projects locate the target repo, click into Project.
- Click a session, switch the right tabs between "user input / full info / agent answer", search keywords if needed.
- Disk tight → Cleanup, remove only confirmed file-typed sessions; only emptying the trash truly frees space.
- 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:
- Scan cost: Cursor's store is large; the first screen cannot just wait 15s — hence
--fast, caching, background warmup. - Count accounting: a card says 31 but clicking in shows 9, often because of the default
limit=15; the desktop must explicitly pull full data and align withkeys. - Honest display: tool-turn spam drowns conclusions; "damaged" is usually bad signing timing (must sign afterPack before entering the DMG).
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
- Desktop installer: https://github.com/lhbDesign/cross-agent-sync/releases/tag/v1.3.2
- Source repo: https://github.com/lhbDesign/cross-agent-sync
- npm CLI/MCP: https://www.npmjs.com/package/cross-agent-sync
- Previous post (MCP/CLI direction): same repo
掘金-跨Agent会话同步实践.md(if you have it locally)
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?
Greyed out.
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?