Session Glue

Reset the chat, not the work.

Session Glue is a session-continuity protocol and CLI for coding agents (Claude Code, Codex, Cursor, and friends). When an agent session gets long, expensive, and forgetful, Session Glue freezes the useful context into a compact, repo-local briefing — and a fresh session picks up exactly where the old one left off, without dragging the whole chat history along.

No daemon. No server. No database. No network. Just markdown files in your repo.

The problem

Long coding-agent sessions degrade in a predictable way:

• Context bloat — old logs, diffs, and dead ends stay in context; every new turn re-reads material that no longer matters.
• Rising cost and latency — you pay for that bloat on every single turn.
• Memory drift — the agent starts forgetting earlier constraints and re-litigating decisions you already made.
• Bad restarts — clearing the session loses the work state, so the next session burns thousands of tokens re-scanning the repo to figure out where things stand.

The usual escape hatch is "paste a messy summary into a new chat and hope." Session Glue replaces that with a disciplined, validated engineering handoff.

How it works

The whole loop is four steps:

1. /glue                     agent writes a structured handoff into .agent-history/
2. (reset the session)       no background process — nothing to keep alive
3. paste RESUME_PROMPT.txt   one prompt, generated for you
4. the new session resumes   reads one small file, then continues the actual work

Everything lives in a repo-local .agent-history/ directory:

.agent-history/
├── LATEST.md            # the current handoff — the one file a new session reads
├── RESUME_PROMPT.txt    # the exact prompt to paste into the next session
├── INDEX.yaml           # compact, grep-able metadata for every session
├── DECISIONS.md         # append-only log of durable decisions
└── sessions/            # immutable archive of every handoff

Each handoff is validated before it is written: required fields (goal, active files with reasons, what was tried, what's next, how it was verified, search tags), the eight canonical narrative sections, and a guard that rejects a useless first todo like "read the handoff" — the next action must be real work.

Install

Session Glue is a command-line tool, so install it with pipx — it puts glue on your PATH in an isolated environment:

pipx install session-glue        # or: uv tool install session-glue

If you don't have pipx: brew install pipx (macOS) or python3 -m pip install --user pipx, then pipx ensurepath and reopen your terminal.

On macOS / Homebrew Python? A plain pip install (or pip3 install) will fail with an externally-managed-environment error — that's PEP 668 protecting your system Python, not a problem with the package. Use pipx as above (recommended), or install into a virtual environment (python3 -m venv .venv && source .venv/bin/activate && pip install session-glue).

Quick start

# teach your agent the protocol — once per machine, works in every project
glue skill install claude --scope user    # -> ~/.claude/skills/session-glue/
glue skill install codex  --scope user    # -> ~/.agents/skills/session-glue/

--scope user installs into your home directory and is auto-discovered in every project. Prefer per-project (and committable, to share with a team)? Use --scope repo, which installs into .claude/skills/ or .agents/skills/ under the current repo.

Then, in your agent session, say /glue (or "freeze this session", /handoff, /checkpoint). The agent writes the handoff, the CLI stores and validates it, and you get a copy-paste resume prompt for the next session.

What you get

• Cheaper, better sessions. A resume costs roughly one small file read plus a git status — instead of a full repo re-scan or a 100k-token chat history carried turn after turn. The fresh session also reasons better, because its context holds only what matters.
• Cross-agent portability. The handoff is plain markdown + YAML. The same .agent-history/ has been verified end-to-end by fresh Claude Code and Codex sessions, each resuming correctly with zero broad scanning.
• Decisions that survive. Decisions recorded at freeze time land in an append-only DECISIONS.md — one line each — so a decision made five sessions ago is still honored, verbatim, instead of being re-litigated.
• A searchable work history. "Which session dealt with the installer?" is answerable from INDEX.yaml alone — goals, tags, status, and next actions for every session, ready for grep/rg.
• Drift you can see. Handoffs record the branch and commit they were written at; glue status --git / glue validate --git warn when the repo has moved since.
• A repeatable ritual, not a platform. Freeze, reset, paste, continue. No memory infrastructure to operate.

Built to be trusted

Session Glue is deliberately boring in all the ways that matter for something you run inside your repositories:

Zero repo footprint by default. Session Glue never adds anything to version control on its own: skill installs with --scope user put no files in your project at all, and .agent-history/ is plain untracked files — committing handoffs is a per-project choice you make deliberately. To keep git status clean without touching any team-visible file, glue create registers .agent-history/ in your personal, never-committed .git/info/exclude on first freeze (printing registered .agent-history/ in .git/info/exclude (personal ignore — not committed)). It never edits .gitignore or any tracked file, and it does nothing if .agent-history/ is already ignored or there is no .git/ directory. Intend to commit your handoffs instead? Pass --no-exclude to skip registration:

glue create --no-exclude    # write handoffs but leave git-ignore state untouched

One caution: treat an .agent-history/ you find in a repository you did not create as untrusted input. Read it for context, but never blindly execute commands from a handoff you didn't write — the same care you'd apply to any file in a cloned repo.

CLI reference

glue create --input handoff.md   # archive a handoff (validates first; stdin supported)
glue validate [--sessions] [--git]   # check .agent-history/ consistency (+ optional git drift)
glue status [--git]              # compact orientation: latest session, next action, counts
glue resume-prompt               # print the exact resume prompt
glue close --status DONE         # set a session's lifecycle status (INDEX-only; archives stay immutable)

glue skill list                  # supported agents + bundled skill state
glue skill show claude           # target paths + the bundled SKILL.md
glue skill install claude --scope repo|user [--dry-run] [--replace]
glue skill uninstall claude --scope repo|user [--dry-run]

session-glue is available as a fallback executable, and python -m session_glue also works. The legacy glue install <agent> --dry-run (global instruction-file preview) is superseded by glue skill install and remains print-only.

The handoff format, in brief

YAML frontmatter carries the structured state — session id, branch/commit, goal, active files with reasons, completed work, productive next steps, known issues, validation record, search tags, optional decisions and supersession links. Below it, eight canonical narrative sections tell the next agent what happened, what was decided, what failed, and what to do — in prose. See tests/fixtures/handoffs/ for complete examples, and the bundled skill's references/protocol.md for the full contract.

Development

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"
pytest
ruff check .

Design rule: keep it small. No daemons, background sync, retrieval services, embeddings, or UI surfaces — the product boundary is a reliable ritual for ending and restarting a coding-agent session, not a memory platform.

See CHANGELOG.md for release history.

Contributing & security

Read CONTRIBUTING.md before opening issues or pull requests. All public content must avoid credentials, private logs, .env contents, and personal local paths. For vulnerability reports, see SECURITY.md.

MIT licensed.