---
title: Compaction and handoff — a full context without forgetting
nav: Compaction and handoff
summary: Before a compaction the Agent writes your words, progress, decisions and paths to a handoff file; afterwards Agent J reminds it to read that file and carry on — you don't have to send anything.
order: 28
---
# Compaction and handoff — a full context without forgetting

Long conversations fill the context. Compaction (`/compact`) replaces the earlier conversation with a summary to make
room, and a summary loses detail: exact numbers, file paths, ideas you rejected, attempts that failed. Agent J's rule:
**write a handoff file before compacting, read it first afterwards.** A file on disk is never compacted.

## Where the handoff lives

Fixed, human-readable paths you can copy straight from the phone:

| Situation | File |
|---|---|
| Shared mode (your own Claude Code) before a compaction | `~/.local/state/agentj/handoff/compact.md` |
| Shared mode before `/clear` | `~/.local/state/agentj/handoff/clear.md` (used once; renamed to `clear-used.md` when handed back) |
| Agent J's own main conversation | `<work folder>/.agentj/handover/compact.md` |

No session id or other random string appears in these paths: the phone masks key-like strings, and you could not copy
the path any more.

Switching the AI coding tool (`/switch-harness`) uses the same handoff: the tool leaving writes `switch.md` first (`<work folder>/.agentj/handover/` for an independent session, `~/.local/state/agentj/handoff/` for a shared one), and the one taking over reads it, then carries on — see [Switch AI coding tool](/docs/switch-harness/).

## Before compacting

- You say "compact", tap `/compact`, or pick it in the menu: if the handoff is missing or older than the current turn,
  Agent J first has the Agent write it with the `agentj-handoff` skill, then compacts.
- You tell the Agent the context is past half and ask for a handoff: it writes it and puts the path alone in a code block so you
  can copy it.
- The handoff holds your own words, done / in progress / next, decisions, absolute paths and pitfalls. **Never a key,
  token or password.**
- When you type `/compact` on the computer, or Claude Code compacts by itself, there is no time to write it first; Agent J
  records that and tells the Agent afterwards that there was no handoff this time.
- `/compact` and `/clear` from the phone wait for the computer's current turn to end and for any dialog to be answered, but
  not for background work: with a background command or a background sub-agent running, the phone tells you how many
  background tasks are running and that the foreground is idle, and the command goes in a few seconds while the background work
  carries on. If it still could not go after 30 minutes, the phone says whether a turn never ended or a dialog was never
  answered, and the command is not sent.

## After a compaction or /clear

Before, the Agent only remembered its handoff when your next message arrived; if you sent nothing, it just sat there and
looked like it had forgotten everything.

Now nothing waits on you: if no new message comes within a second or two of the compaction, Agent J sends the session one
[Agent J system note]: "Compaction finished. Read the handoff … first, then carry on with the task you were doing." The
phone shows one line — "Compacted. I'm reading my handover notes to pick up the thread." — and Agent J's reply after reading the
handoff reaches the phone as usual. The note comes from Agent J on your computer; it is not one of your messages and grants
the Agent no new permission.

After `/clear` the same: with a `clear.md`, Agent J reminds the Agent to read it; without one nothing is sent and the new
conversation starts from zero.

If Claude Code compacted by itself in the middle of a turn, it carries on by itself and Agent J stays out of the way.

**Copy to your main Agent:**

> When the context is past half or I say compact, first write the handoff with the agentj-handoff skill (my own words,
> progress, decisions, absolute paths, pitfalls, next step; no credentials) and send me the path alone in a code block;
> after the compaction read it first, then carry on.

While a scheduled task is running, `/compact` and `/clear` show its name and say that the command has not been sent. The remote that requested it can cancel the wait; the command then stays cancelled after the task finishes. Once command execution begins, withdrawal closes. Shared Claude keeps its existing withdrawal option while waiting for desktop idle, until native control is sent.