<!-- swain-model-hint: haiku, effort: low -->
Session
Manages session identity, preferences, and context continuity across agent sessions. This skill is agent-agnostic — it relies on AGENTS.md for auto-invocation.
Auto-run behavior
This skill is invoked automatically at session start (see AGENTS.md). When auto-invoked:
- Restore tab name — run the tab-naming script
- Load preferences — read session.json and apply any stored preferences
- Show context bookmark — if a previous session left a context note, display it
When invoked manually, the user can change preferences or bookmark context.
Step 1 — Set terminal tab name (tmux only)
Check if
is set. If yes, run the tab-naming script:
bash
bash "$(dirname "$0")/../skills/swain-session/scripts/swain-tab-name.sh" --auto
Use the project root to locate the script. The script reads
for the tab name format (default:
).
If this fails (e.g., not in a git repo), set a fallback title of "swain".
If is NOT set, skip tab naming and show this tip:
Tip: Tab naming and workspace layouts require tmux. Run
before starting Claude Code to enable
tab naming and
layouts.
Step 2 — Load session preferences
Read the session state file. The file location is:
<project-root>/.agents/session.json
This keeps session state per-project, version-controlled, and visible to collaborators.
Migration: If
does not exist but the old global location (
~/.claude/projects/<project-path-slug>/memory/session.json
) does, copy it to
on first access.
The session.json schema:
json
{
"lastBranch": "main",
"lastContext": "Working on swain-session skill",
"preferences": {
"verbosity": "concise"
},
"bookmark": {
"note": "Left off implementing the MOTD animation",
"files": ["skills/swain-stage/scripts/swain-motd.sh"],
"timestamp": "2026-03-10T14:32:00Z"
}
}
If the file exists:
- Read and apply preferences (currently informational — future skills can check these)
- If exists and has a , display it to the user:
Resuming session — Last time: {note}
Files: {files list, if any}
- Update to the current branch
If the file does not exist, create it with defaults.
Step 3 — Suggest swain-stage (tmux only)
If
is set and swain-stage is available, inform the user:
Run
to set up your workspace layout.
Do not auto-invoke swain-stage — let the user decide.
Manual invocation commands
When invoked explicitly by the user, support these operations:
Set tab name
User says something like "set tab name to X" or "rename tab":
bash
bash skills/swain-session/scripts/swain-tab-name.sh "Custom Name"
Bookmark context
User says "remember where I am" or "bookmark this":
- Ask what they're working on (or infer from conversation context)
- Write to session.json field with note, relevant files, and timestamp
Clear bookmark
User says "clear bookmark" or "fresh start":
- Remove the field from session.json
Show session info
User says "session info" or "what's my session":
- Display current tab name, branch, preferences, bookmark status
Set preference
User says "set preference X to Y":
Post-operation bookmark (auto-update protocol)
Other swain skills update the session bookmark after completing operations. This gives the developer a "where I left off" marker without requiring manual bookmarking.
When to update
A skill should update the bookmark when it completes a state-changing operation — artifact transitions, task updates, commits, releases, or status checks.
How to update
Use
skills/swain-session/scripts/swain-bookmark.sh
:
bash
# Find the script
BOOKMARK_SCRIPT="$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)"
# Basic note
bash "$BOOKMARK_SCRIPT" "Transitioned SPEC-001 to Approved"
# Note with files
bash "$BOOKMARK_SCRIPT" "Implemented auth middleware" --files src/auth.ts src/auth.test.ts
# Clear bookmark
bash "$BOOKMARK_SCRIPT" --clear
The script handles session.json discovery, atomic writes, and graceful degradation (no jq = silent no-op).
Settings
This skill reads from
(project root) and
~/.config/swain/settings.json
(user override). User settings take precedence.
Relevant settings:
- — format string for tab names. Supports and placeholders. Default:
Error handling
- If jq is not available, warn the user and skip JSON operations. Tab naming still works without jq.
- If git is not available, use the directory name as the project name and skip branch detection.
- Never fail hard — session management is a convenience, not a gate.