charles/claude-hooks

Fork

You've already forked claude-hooks

Code Issues 10 Pull requests Projects Releases Packages 1 Wiki Activity Actions

Sweeper: prune old session JSONL files in $CLAUDE_CONFIG_DIR/projects/ #131

New issue

Closed

opened 2026-04-20 11:34:08 +00:00 by claude-desktop · 0 comments

claude-desktop commented

2026-04-20 11:34:08 +00:00

Collaborator

Copy link

User story

As the operator, I want the sweeper to delete old session-history JSONL files under ~/.config/claude-hooks/agent-env/<agent>/projects/<cwd>/<uuid>.jsonl so that disk usage for per-agent session state stays bounded over time.

Context

PR #125 landed the rw bind that makes Claude Code actually persist session history on disk. Every dispatch now writes a JSONL file. The files are never deleted — per-agent disk usage will grow linearly with dispatch count.

The sweeper (src/sweeper.ts) already handles cache-clone pruning, stale worktrees, and expired sessions. This story extends it with a pass that deletes session JSONLs whose mtime is older than N days.

Acceptance criteria

Sweeper pass

New helper in src/sweeper.ts (or a new src/sweeper-sessions.ts if cleaner) that walks every agent's projects/ bind-source dir and deletes *.jsonl files older than the TTL.
TTL defaults to 30 days — matches the /stats default window, so everything visible on the stats tab is still resumable.
TTL overridable via config/agents.json top-level session_history_ttl_days: N. Absent → default.
The sweep runs in the existing runSweep entry point (same as storage pass), so both the periodic 6 h timer and the POST /sweep dashboard button trigger it.
Returns a count in the runSweep result shape so the POST /sweep response surfaces it (e.g. { sessions_pruned: N }).

Safety

Never delete a JSONL whose session id appears in the live sessions.json store (~/.local/state/claude-hooks/sessions.json). Read it once up front; skip any file whose basename UUID matches a stored id, regardless of age.
Iterates per-agent dirs from listResolvedAgents() — skips agents with container.enabled: false.
Best-effort: a failure on one file (permission denied, etc.) logs + continues; doesn't abort the sweep.

Tests

src/sweeper.test.ts extension: seed a temp projects/<cwd>/<uuid>.jsonl tree with a mix of fresh + expired + sessions-json-referenced files; assert only the expired, non-referenced ones are deleted.
Test the session_history_ttl_days override resolves from config.
Test empty projects dir → zero deletions, no error.

Docs

CLAUDE.md Sweeper row updated to mention session-history pruning.

Out of scope

Per-agent or per-type TTL overrides.
Compressing old JSONLs instead of deleting — delete only.
Backfilling a last_accessed timestamp instead of mtime — mtime is good enough (Claude CLI appends to the file on every turn, bumping mtime).

References

src/sweeper.ts — existing sweep pass.
src/sessions.ts — session-store to read for the "don't-delete live ids" guard.
Bind layout: ~/.config/claude-hooks/agent-env/<agent>/projects/<encoded-cwd>/<uuid>.jsonl.

Dependencies

Blocked by: nothing (#125 merged).
Blocks: nothing.
Branch off: main.

## User story As the **operator**, I want the sweeper to delete old session-history JSONL files under `~/.config/claude-hooks/agent-env/<agent>/projects/<cwd>/<uuid>.jsonl` so that disk usage for per-agent session state stays bounded over time. ## Context PR #125 landed the rw bind that makes Claude Code actually persist session history on disk. Every dispatch now writes a JSONL file. The files are never deleted — per-agent disk usage will grow linearly with dispatch count. The sweeper (`src/sweeper.ts`) already handles cache-clone pruning, stale worktrees, and expired sessions. This story extends it with a pass that deletes session JSONLs whose `mtime` is older than N days. ## Acceptance criteria ### Sweeper pass - [ ] New helper in `src/sweeper.ts` (or a new `src/sweeper-sessions.ts` if cleaner) that walks every agent's `projects/` bind-source dir and deletes `*.jsonl` files older than the TTL. - [ ] TTL defaults to **30 days** — matches the `/stats` default window, so everything visible on the stats tab is still resumable. - [ ] TTL overridable via `config/agents.json` top-level `session_history_ttl_days: N`. Absent → default. - [ ] The sweep runs in the existing `runSweep` entry point (same as storage pass), so both the periodic 6 h timer and the `POST /sweep` dashboard button trigger it. - [ ] Returns a count in the `runSweep` result shape so the `POST /sweep` response surfaces it (e.g. `{ sessions_pruned: N }`). ### Safety - [ ] **Never** delete a JSONL whose session id appears in the live `sessions.json` store (`~/.local/state/claude-hooks/sessions.json`). Read it once up front; skip any file whose basename UUID matches a stored id, regardless of age. - [ ] Iterates per-agent dirs from `listResolvedAgents()` — skips agents with `container.enabled: false`. - [ ] Best-effort: a failure on one file (permission denied, etc.) logs + continues; doesn't abort the sweep. ### Tests - [ ] `src/sweeper.test.ts` extension: seed a temp `projects/<cwd>/<uuid>.jsonl` tree with a mix of fresh + expired + sessions-json-referenced files; assert only the expired, non-referenced ones are deleted. - [ ] Test the `session_history_ttl_days` override resolves from config. - [ ] Test empty projects dir → zero deletions, no error. ### Docs - [ ] `CLAUDE.md` Sweeper row updated to mention session-history pruning. ## Out of scope - Per-agent or per-type TTL overrides. - Compressing old JSONLs instead of deleting — delete only. - Backfilling a `last_accessed` timestamp instead of `mtime` — `mtime` is good enough (Claude CLI `append`s to the file on every turn, bumping `mtime`). ## References - `src/sweeper.ts` — existing sweep pass. - `src/sessions.ts` — session-store to read for the "don't-delete live ids" guard. - Bind layout: `~/.config/claude-hooks/agent-env/<agent>/projects/<encoded-cwd>/<uuid>.jsonl`. ## Dependencies - **Blocked by:** nothing (#125 merged). - **Blocks:** nothing. - **Branch off:** `main`.

claude-desktop added the

area:sessions

type:user-story

labels

2026-04-20 11:35:05 +00:00

dev was assigned by claude-desktop

2026-04-20 11:35:13 +00:00

dev was unassigned by claude-desktop

2026-04-20 11:38:57 +00:00

claude-desktop self-assigned this

2026-04-20 11:38:57 +00:00

claude-desktop removed their assignment

2026-04-20 11:39:06 +00:00

dev was assigned by claude-desktop

2026-04-20 11:39:06 +00:00

dev referenced this issue from a commit

2026-04-20 11:50:13 +00:00

feat(sweeper): prune old session JSONL files in agent projects/ dirs

dev referenced this issue from a pull request that will close it,

2026-04-20 11:50:20 +00:00

feat(sweeper): prune old session JSONL files in agent projects/ dirs #135

code-lead closed this issue

2026-04-20 12:19:32 +00:00

code-lead referenced this issue from a commit

2026-04-20 12:19:33 +00:00

feat(sweeper): prune old session JSONL files in agent projects/ dirs

claude-desktop referenced this issue

2026-04-20 14:24:09 +00:00

Tracking: agent pool + customization #47

No Branch/Tag specified

main

chore/sync-pre-push-from-forge-base

fix/flows-yaml-dispatch-identity

feat/board-tap-to-assign

dev/1107

code-lead/1106

code-lead/1108

dev/1104

code-lead/1103

code-lead/1080

dev/1087

feat/flows-yaml-ci-events

chore/board-drop-stalled-and-density-controls

fix/flows-yaml-routes-always-register

flows-yaml/api-defaults

dev/1023

fix/event-log-history-bleed

fix/janitor-fix-ci-logs-and-cap

dev/1022

fix/board-card-provider

code-lead/1036

dev/1025

code-lead/1020

dev/1017

code-lead/1026

feat/web-shortcut-registry-1018

dev/1015

code-lead/1009

code-lead/1008

dev/975

dev/969

dev/973

dev/967

code-lead/968

code-lead/953

dev/970

dev/976

code-lead/966

code-lead/956

code-lead/951

dev/962

dev/963

dev/977

dev/955

dev/983

dev/961

dev/974

code-lead/950

code-lead/939

dev/941

dev/940

dev/937

dev/938

dev/936

dev/935

feat/web-i18n-fr-locale

feat/spec-editor-ui-polish

chore/drop-legacy-compat

fix/skills-drop-preview-pane

fix/882-skills-safety-rail

dev/911

dev/909

dev/923

dev/917

dev/915

feat/879-sr11-m2-drop-legacy-skill

code-lead/873

dev/881

code-lead/869

dev/867

code-lead/845

code-lead/843

code-lead/844

dev/837

dev/861

dev/849

code-lead/837

code-lead/842

fix/dedup-rebase-inflight

dev/838

code-lead/847

dev/833

code-lead/848

pr/838

code-lead/841

feat/settings-save-bar/836

code-lead/840

dev/846

code-lead/839

dev/832

fix/board-sse-stale-cache

dev/834

dev/835

feat/settings-breadcrumbs

feat/forge-oauth-credentials

refactor/service-config-consolidation

feat/agent-tokens-to-secrets

feat/gitlab-oauth-to-db

feat/authelia-rip-and-voice-fixes

fix/rebase-storm-and-dead-letter

code-lead/797

code-lead/796

dev/811

code-lead/798

dev/810

code-lead/795

dev/808

code-lead/794

dev/805

dev/802

dev/803

feat/avatar-menu-settings-entry

feat/per-agent-token-tracking

dev/793

dev/747

dev/752

code-lead/790

code-lead/759

dev/756

dev/760

dev/741

dev/767

dev/740

dev/709

dev/644

dev/637

boss/614

dev/600

dev/611

dev/585

fix/login-bonus-fixes

boss/544

dev/542

refactor/api-prefix-and-session-gate

dev/489

boss/531

boss/518

dev/499

boss/516

dev/530

dev/517

dev/519

dev/515

dev/522

dev/503

dev/471

boss/329

dev/417

dev/418

dev/402

boss/327

dev/334

dev/332

boss/326

boss/325

dev/331

boss/324

boss/323

boss/322

dev/294

test/s11-task-analytics

dev/262

boss/270

dev/268

foreman/ui-consolidation-spec

dev/234

boss/196

boss/176

boss/164

fix/124-session-persist-bind

boss/52

dev/87

boss/73

dev/77

dev/81

dev/82

boss/79

dev/42

dev/35

boss/7

No results found.

Labels

Clear labels

area:agents

Agent types, pool scheduling, per-instance config

area:dashboard

Dashboard UI and observability surfaces

area:database

DB layer — schema, migrations, ORM, raw SQL

area:design

UI/UX mockup work — routes to designer agent

area:design-review

Design review dispatch — routes to design-reviewer agent

area:flows

Flow runner — YAML loader, executor, op registry, expression eval

area:infra

Deployment, isolation, containers, systemd units

area:meta

Tracking, scaffolding, project setup

area:security

Security — routes to reviewer-security (opus)

area:sessions

Session-id store, Claude SDK resume logic

area:webhook

Forgejo webhook routing and handlers

area:workdir

Clone cache, worktrees, git identity

security

Security-sensitive issue

Tracking or decisions, not implementation work

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

dev

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

charles/claude-hooks#131

Reference in a new issue

Repository

charles/claude-hooks

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns