Resume any harnext conversation — from the CLI or the SDK

The problem: context died with the process#

Close the terminal, finish a script, restart a crashed run — and the whole conversation was gone. The agent forgot the plan, the files it had already read, the decisions you'd made together. harnext Desktop felt it most acutely; it shipped with a blunt caveat:

Core has no session-resume API yet — restored conversations are read-only; start a new chat to continue working.

That's fixed. harnext now records every run as a durable transcript and gives you two first-class ways to continue one: the --resume flag on the CLI, and resume options on createAgentSession in the SDK.

harnext --resume#

Run harnext --resume (or -r) in any project and you get an interactive picker of that directory's past sessions, newest first. Each row shows the first thing you asked, how long ago it was, the message count, and the model — enough to find the one you want at a glance.

Hit enter and the prior transcript replays into the terminal — your messages, the tool badges and their output, the rendered markdown — so you land back in the conversation instead of staring at a blank prompt. Already know the id? Skip the picker:

# Pick from a list
harnext --resume

# Resume a specific session directly
harnext --resume 3f9c1b2a

# Scripted resume in print mode
harnext -p --resume 3f9c1b2a "now add tests for it"

How it's stored#

Sessions are append-only JSONL transcripts under ~/.harnext/agent/sessions/<cwd-hash>/<sessionId>.jsonl. The <cwd-hash> is derived from the absolute working directory, so sessions are scoped per project— the picker only ever shows runs from the directory you're standing in. The first line is a session-meta record; every line after it is one full agent message. Because the full message is kept (not a lossy summary), the API usage survives — which is exactly what the resume flow reads to measure how full the context window is. harnext keeps the 100 most recent sessions per directory and prunes the oldest as new ones appear.

The SDK angle#

@harnext/coreexposes the same capability with more control. The simplest path is to resume by id from harnext's local store:

import { createAgentSession } from '@harnext/core';

const { session, sessionId, resumed } = await createAgentSession({
  cwd: process.cwd(),
  resumeSessionId: '3f9c1b2a-…',
});

await session.prompt('continue where we left off');

Or hold the transcript yourself and hand it back — useful when the history lives in your own database, not on the local disk. initialMessages takes precedence over resumeSessionId, and pairing it with an explicit sessionId controls the id the continued run persists under:

import { createAgentSession, type AgentMessage } from '@harnext/core';

const history: AgentMessage[] = await loadFromMyDatabase(userId);

const { session } = await createAgentSession({
  initialMessages: history,  // full control over the seeded context
  sessionId: 'my-id',        // and the id it continues under
});

Long conversations: summarize on the way back in#

Resume a conversation that's already near the model's context window and harnext offers to compact it first — running the same compactNow pipeline a live session uses, with a before/after token estimate so you can see what it reclaimed. You pick up where you left off without immediately blowing the budget.

What this unblocks#

The most immediate beneficiary is harnext Desktop: a restored conversation is no longer read-only. Seed it with initialMessages and its original sessionId, and a viewed transcript becomes a live one you can keep working in. The next step is moving the "list sessions by working directory" surface to the cloud so the same history follows you across machines.

Read the docs#

← All posts