Sessions

A session is one agent working in one workspace on the host. It has a transcript, a configuration, and the files it changed. Every client connected to the host sees the same sessions.

Screen

esc on a new session opens the session list. See Moving between screens.

Each row is a session: its status, agent, workspace, branch, and what it is doing now. Sessions waiting on you are counted at the top.

Key
enter	Open the session
n	New session
f	Back to the session that was open
ctrl+f	Filter by title, agent or workspace
right / left	Show or hide the selected session's details
u	Mark it read
a	Archive it
x	Show archived sessions
d, delete	Dispose of it, after you confirm
r	Refresh

Commands

Command		Flags
session list	Sessions, newest first	--archived --limit N --cursor C --json
session show <uri>	What the host says about one	--full --json
session new	Start one	--agent P --cwd DIR --trust --set k=v --json
session history <uri>	Its turns	--all --full --json
session config <uri>	Its config schema and the values in force	--json
session set <uri> <k> <v>	Change one config value
session read <uri>	Mark it read	--unread
session archive <uri>	Archive it	--undo
session export <uri>	The whole session as one document	--json --markdown
session rm <uri>	Dispose of it

ahpc session new --agent claude --cwd /work/api --trust

--set takes keys from the session's config schema, and session config lists them. --trust is explained in trusted folders.

session list --limit N reads one page and ends with More: --cursor <C> when there is another. With --json, the answer is { sessions, nextCursor }.

MCP tools

Always served.

Tool	What it does	Arguments
list_sessions core, read only	The sessions on the connected host, newest first. Start here: every other session tool takes a session URI from this list. Give a limit to read one page and take nextCursor from the answer.	archivedboolean Include archived sessions. Off by default. limitinteger Read at most this many sessions. A positive whole number. Omit to read the whole catalogue. cursorstring The nextCursor of the previous page. Omit to start from the newest session.
show_session core, read only	What the host says about one session: its title, what it is doing, and the directories it works in.	sessionstring, required A session URI from list_sessions.
new_session core	Create a session on the host and return its URI. The agent is not asked anything until send_turn.	providerstring A provider from list_agents. The first one the host serves, if omitted. workingDirectorystring An absolute path on the host for the agent to work in. configobject Configuration values, as a flat object of strings.
dispose_session core	Dispose of a session. The transcript is the host's to keep or drop; the agent behind it stops.	sessionstring, required
session_history core, read only	The turns in a session, oldest first, as text rather than as a tree of parts.	sessionstring, required allboolean Load the whole conversation rather than the window the host opened with.

Host support

Every AHP host has sessions. What session config offers depends on the host and the agent.