Sessions and project timeline

A native agent session gives repeated commands a common identity for locks, jobs and dirty ownership. The project timeline records activity and stores notes/checkpoints that an agent can read after losing its conversational context.

Session lifecycle

Use the same --agent across related commands. The proxy stores the accepted session beside its instance registry, scoped by project and agent, and offers it again on later connections. --session new requests a fresh session; --session <id> explicitly requests resume. Resume depends on the backend accepting that record and is not an unlimited lifetime guarantee.

claudus.exe who --json --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant
claudus.exe session info --json --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant
claudus.exe session begin --json --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant --launch-headless
claudus.exe session end --json --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant

begin requests a fresh connection session unless an explicit session was selected; it does not silently end a previous session. A normal one-shot process exit closes the connection while allowing session resume during the backend's retention window. session end explicitly ends the session and removes its local resume file. Ending a session is not a substitute for saving intended package changes.

CLAUDUS_AGENT, CLAUDUS_ROLE and CLAUDUS_SESSION provide defaults; explicit command options take precedence. Do not share one identity between independent agents merely to bypass ownership checks.

Leave a checkpoint

claudus.exe timeline note "Material parameters updated; visual verification pending" --package /Game/Materials/M_Demo --tag todo --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant
claudus.exe timeline checkpoint "Material pass" --body '@checkpoint.md' --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant
claudus.exe timeline context --budget 2000 --project-path "C:\Projects\MyProject\MyProject.uproject"

Write what changed, what was actually verified, remaining uncertainty and the next action in checkpoint.md. Notes and checkpoints use the backend when available and can append locally when it is unavailable. --offline explicitly keeps note/checkpoint writing local. These operations do not need an AI service.

Query the journal without Unreal

claudus.exe timeline list --since 2h --kind mutation,save --project-path "C:\Projects\MyProject\MyProject.uproject"
claudus.exe timeline search "verification" --project-path "C:\Projects\MyProject\MyProject.uproject"
claudus.exe timeline walk --package /Game/Materials/M_Demo --project-path "C:\Projects\MyProject\MyProject.uproject"
claudus.exe timeline status --project-path "C:\Projects\MyProject\MyProject.uproject"
claudus.exe timeline index repair --project-path "C:\Projects\MyProject\MyProject.uproject"

show <id>, diff <checkpoint-a> <checkpoint-b>, sessions, asset-history <package> and export provide other views. Use help timeline for filters and exact syntax.

Events are ordered by ULID. A writer's IDs increase monotonically; different writers in the same millisecond are ordered by ID entropy, not guaranteed invocation order. Checkpoint boundaries follow that same order. Prefer event IDs over writer-local sequence numbers when referring to a specific event.

The context budget is approximate: text is trimmed by a character budget derived from the requested tokens, and a checkpoint's body is retained even when it exceeds that budget. A compact context is not a complete audit export.

Storage and retention

The default store is <Project>/.claudus/timeline/:

File	Contents
events-YYYYMMDD.ndjson	Append-only event lines for the UTC day.
checkpoints/<id>-<slug>.md	Authored checkpoint body.
index.json	Rebuildable query index.
summaries/	Compacted summaries and retained notes/checkpoints.
archive/	Raw days archived by an explicit purge operation.

--timeline-dir <absolute-directory> or CLAUDUS_TIMELINE_DIR selects another store. --no-timeline or CLAUDUS_TIMELINE=0 disables timeline recording/injection for that proxy. compact, compact --purge and prune change retained data; inspect their help and choose a retention policy before using them in automation.

The timeline records bridge activity and authored notes; it is not an asset backup, a full version-control history, or proof that an arbitrary external mutation was captured. Keep source control and explicit save/reload verification for the project itself.