---
title: Agent self-archive
---

# Agent self-archive

## What it is

When an AI agent finishes its work with nothing left for you to do, it can **archive its own session** — the session drops off the active list into the **Archived** section on its own, exactly like a manual archive, and is fully reversible. This is why you'll sometimes see a finished session tidy itself away instead of piling up as a stale "ended" row you have to clear by hand.

It's the agent-driven twin of pressing **Ctrl+W** yourself. At the very end of its turn an agent decides between two moves:

- **Self-archive** — the task is genuinely done and there's nothing for you to receive, decide, or worry about (a fix landed, a question fully answered). The session archives itself.
- **Stay on the board** — the turn left you something real: a deliverable to collect, a decision only you can make, bad news, or news that changes your next move. The session stays visible so it can get your attention.

Every self-archive is stamped with an **"Agent (self-archived)"** attribution chip in the Archive view, so when a session "disappears" you can tell at a glance that the agent ended it itself — not you, and not a recipe.

Self-archive is **non-destructive**, exactly like every other archive: the conversation, attachments, and metadata are all preserved, the row just moves into the collapsible Archived section, and you can bring it back any time. Its scheduled wake-ups switch off while it is archived and switch back on when you unarchive it, unless someone turned one off in the meantime. It is NOT delete, and it is NOT pause (which only freezes a session in place).

## Where to find it

### Settings you control

Two settings govern self-archive, both under **Settings → CLI Control**:

1. **Session self-archive** — the master on/off switch (**default ON**). Turn it off and both triggers stop working: the CLI route refuses and the `[[OMNISCIO_SELF_ARCHIVE]]` marker becomes a no-op. Nothing can self-archive while this is off.
2. **Let finished sessions archive themselves without approval** (**default OFF**). This one only matters if you've also turned on **"require approval for CLI session actions"**:
   - With that approval requirement **off** (the default), a self-archive just applies immediately — nothing lands in your inbox.
   - With approval **on**, a self-archive normally queues an approval row in your inbox like any other lifecycle action. Flip this toggle **on** to let a session's *own* self-archive apply immediately with nothing to approve — **while approval still gates every other action**, including archiving a *different* session. Only the self-bound archive is exempted.

Turning that "without approval" toggle on is **itself** an approval-gated settings change, so an agent can never grant the bypass to itself — only you can.

### CLI control

One route on `127.0.0.1:19519` (bearer-gated):

- `POST /session/self-archive` — archives the **calling** session (resolved from its provenance, never a body/URL id). Honors the approval setting (applies immediately or queues an inbox row) unless the without-approval toggle is on; returns `403` when the **Session self-archive** kill-switch is off, `400` with no source session, `404` for an unknown source, `409` if the session is already archived, and `429` (with `Retry-After`) past 30 calls a minute from one session — the session's own budget, so other agents' traffic can never refuse it. There is deliberately no route to self-archive *another* session — use `POST /session/:id/archive` for that (always approval-gated).

## How it behaves

### How it works — two triggers, one action

An agent can self-archive in **two equivalent ways**, and both do exactly the same thing:

1. **The `[[OMNISCIO_SELF_ARCHIVE]]` marker (the reliable path).** The agent writes the marker `[[OMNISCIO_SELF_ARCHIVE]]` on its own line in its final message. Omniscio spots it the moment the turn ends and archives the session automatically — no command to run. This is the dependable path because agents reliably forget to make a literal API call, but they don't forget to write a line of text. The marker only fires when it's **alone on its own line** — a mid-sentence or code-fenced mention (an agent *explaining* the feature, exactly like this page) never triggers it — and the marker line is stripped out of the message you actually see. Wrapping it in a single pair of backticks (`` `[[OMNISCIO_SELF_ARCHIVE]]` ``) is fine: a line whose *entire* content is the marker is the signal whether or not it is quoted, and a weaker model that copies the formatting of the instruction it was handed would otherwise be ignored silently.
2. **The `POST /session/self-archive` CLI route.** The agent calls the local control server directly. Same result.

Both triggers run through one shared dispatch, so they can never drift apart — same attribution, same settings, same approval behavior.

**A session can only ever archive ITSELF.** The target is always resolved from *who is calling* (the session's own identity), never from an id in the request — so there is no way for one session to archive another through this path. Archiving a *different* session over the CLI is a separate action that is always approval-gated.

**Running sessions keep their summary.** If an agent self-archives as its final act, Omniscio finalizes its in-flight message first and *then* stops the process — so the closing summary it just wrote is preserved, not cut off.

### When a self-archive is held back

A self-archive is the agent saying "my work is done" — a judgement it can only make from what it has actually *seen*. In a few situations it is about to sign off without the full picture, so Omniscio holds the sign-off instead of honouring it. For the two narrower cases below the session comes back to **Needs You** with a short note explaining why, and the agent can finish normally once the matter is dealt with. The most common one puts nothing in your inbox at all:

- **Messages are queued for it that it never saw.** If someone (you, or another agent) [queued a message](queue-a-message.md) while it was mid-step, that message is waiting for exactly the moment the agent is now trying to leave. Archiving would throw it away, so the archive is held, the queued messages are delivered, and the agent signs off afterwards — having actually read them. The session does **not** come to your inbox for this: it is not finished, it is about to be handed mail, so a card would only be raised and then cleared by that delivery a moment later. If the delivered message turns out to need nothing — the agent answers it with only its "nothing to do" line, or folds the exchange away — the held sign-off still stands and the session archives, rather than landing in your inbox with no message to read. (This covers Claude sessions today; on another AI engine, a held sign-off still brings the session back to your board.)

There are two narrower holds for the same reason: a session that still owes you an answer to a question it asked, and a bug-report session that hasn't sent the reporter their closing update yet. In every case the hold is temporary and self-clearing — nothing gets stuck on your board permanently.

### When a background nudge wakes a finished session

Plenty of things poke a session after it has finished: the auto-lander saying its branch merged, a
gate or land watch reporting back, a scheduled wake. Any of those starts a fresh turn — which means
the session leaves **Needs You**, and the card holding its final report disappears from your inbox
before you ever opened it. The agent then reads the nudge, sees there is nothing left to do, and
archives itself. Your report goes with it, unread.

So before that turn starts, Omniscio tells the agent one thing it has no other way to know: **whether
you have actually seen its last message.**

- **You haven't** (no reply, not marked read) — the agent is told not to archive, so its report stays
  on your board waiting for you.
- **You have** (you replied, or marked it read) — the agent is told it is safe to finish, so a session
  you are already done with does not linger.

This is advice, not a lock: the agent still decides, and it can still archive when the nudge genuinely
makes its last message obsolete. You will never see the note itself — it goes to the agent, not into
your chat, and the message in your transcript is exactly what the sender wrote.

### When the woken session has nothing worth showing you

A wake that finds nothing still lands in **Needs You** — unless you had already archived the session.
Those are the two opposite cases, and Omniscio tells them apart by where the session was sitting
before the nudge arrived.

- **The session was on your board** — you have not closed it, so the fresh turn is its honest first
  ping and it stays.
- **You had already archived it** — the wake pulled a closed session back on its own, and if that
  turn turns out to have nothing for you, the session goes straight back to the Archive. It never
  appears in your inbox at all.

Nothing worth showing you includes the agent ending its turn with the agent-exchange fold (the
marker that tells Omniscio two agents' routine back-and-forth is not worth your screen) — so a
self-archived session that gets poked, answers another agent briefly, and asks for the exchange to
fold simply stays archived. If that turn *did* carry something you should read — a report, a
question, a link — it renders in full and the session stays on your board; the fold is refused on
exactly those turns, so a real message can never be filed away with the noise.

### When it does ask you — the self-archive card

A self-archive that queues for approval gets its **own inbox card**, not the generic one, so you're never left decoding `Archive session "X" (self)`:

- **The first time**, the card explains in plain English what's being asked: this session has finished its work and is asking to come off your active board; nothing is deleted, it moves to the Archive, and you can bring it back. After you've acted on one of these cards once, that explanation drops away and the card reads like any other approval. It's marked as seen when you **act** — approving, declining, or allowing — so simply noticing the card in passing never spends your one explanation, and a batch of self-archives arriving together all read the same way until you answer one.
- **Every** such card — first or hundredth — carries an **Always allow** button beside Not now / Archive it. One click turns on the "without approval" toggle above, so finished sessions stop asking. It is deliberately not one-shot: if you weren't ready the first time, it's still there later.
- **It also clears the backlog.** Turning that permission on approves the self-archive rows already waiting in your inbox, so you don't say "never ask again" and then hand-approve a stack. This happens however you turn it on — the card, Settings → CLI Control, or an approved command-line settings change.
- **The scope stays narrow.** "Always allow" covers only a session archiving *itself*. An agent archiving a *different* session still asks you every time, as do pause, unpause and snooze.
- The button is hidden while the master **Session self-archive** switch is off, since the permission would do nothing there.

### How to reverse it

A self-archived session behaves like any other archived session:

- **Send it a message** — it silently un-archives and the conversation continues (Omniscio re-spawns the agent for the new turn). You don't need to unarchive first.
- **Unarchive it** — open it from the Archived section (or Archive search) → the **⋯** menu → **Unarchive**. The row returns to the live list.
- **Ctrl+Z** right after it happens undoes the archive, the same as undoing a manual one.

## For agents

### Under the hood

- Both triggers converge on one dispatcher, [self-archive-dispatch.ts](../../src/main/services/cli/self-archive-dispatch.ts) (`dispatchSelfArchive`), which applies the `agent-self` attribution, the kill-switch, and the approval gate identically — so the marker and the route can never behave differently.
- The CLI route lives in [cli-server-lifecycle-routes.ts](../../src/main/services/cli/cli-server-lifecycle-routes.ts); the `[[OMNISCIO_SELF_ARCHIVE]]` marker is detected at turn-end as a disposition gate in [ndjson-auto-disposition.ts](../../src/main/process/ndjson-auto-disposition.ts), and the marker string itself is defined in [agent-content-markers.ts](../../src/shared/agent-content-markers.ts).
- The `agent-self` archive trigger (which renders the "Agent (self-archived)" chip) is in [archive-trigger.ts](../../src/shared/types/archive-trigger.ts); the two settings live in [agent-tools-settings.ts](../../src/shared/types/settings/agent-tools-settings.ts) with the UI toggle in [CliControlSettings-definitions.ts](../../src/renderer/src/features/settings/sections/cli-control/CliControlSettings-definitions.ts).
- The approval card is the generic CLI-pending card for the `session.archive` action kind (its label lives in [action-kind-labels.ts](../../src/renderer/src/features/cli-pending/action-kind-labels.ts)) — the queued row names its own target session id and carries a whitelisted `{trigger: 'agent-self'}` payload that the archive handler reads back (any other trigger value is ignored), never its display text, so an archive of a *different* session can never land on this card. The backlog sweep is `approvePendingCoveredByOverride` in [cli-approval-retroactive.ts](../../src/main/services/cli/cli-approval-retroactive.ts), fired by a settings side effect so it runs from every route into the permission, not just the button.
- Full invariants and edge cases: [session-self-archive-contract.md](../../.claude/memory/contracts/session-self-archive-contract.md).

## Related

- [archive-a-session.md](archive-a-session.md) — the full Archive feature: manual archive, undo, the "Archived by" attribution chips, auto-unarchive on send
- [pause-or-stop-a-session.md](pause-or-stop-a-session.md) — Pause vs Archive: pause freezes a session in place; archive (and self-archive) hides it
- [ask-amc.md](ask-amc.md) — Ask Omniscio, the in-app help agent
- [cli-control.md](cli-control.md) — the local control server the `POST /session/self-archive` route lives on