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

The session list is the first screen. See Screen.

Key
ctrl+n	New session
ctrl+f	Filter by title, agent or workspace
x	Show archived sessions
right / left	Show or hide the selected session's details
s	Session settings, in an open session

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.