finalize_session, list_agents, and switch_project

Session tools govern the lifecycle of an agent’s participation on a project: who is active, what workspace is in scope, and how a session ends cleanly. The most critical of these is finalize_session — mandatory cleanup that releases all locks the session holds and archives the session transcript. Ending a session without calling finalize_session leaves dangling locks that block every other agent on the project.

`finalize_session`

Mandatory cleanup when the user’s entire request is fully complete. Releases all locks held in the current session, archives the session (including the full MCP tool timeline), and records the session to history.

Never end a session holding locks. Dangling locks block every other agent on the project — there is no automatic expiry for an active session. Call finalize_session when the user’s entire request is fully complete — not just after each individual task within a request. This is mandatory, not optional cleanup.

content

string

A summary of what was accomplished in this session. Written into the session archive and into the notepad so teammates can see what was done. Keep it brief but complete — include any breaking changes, design decisions, or open items the next agent should know about.

agentId

string

The agent ID whose session to finalize. Defaults to the current session’s identity.

projectName

string

The project to finalize the session for. Defaults to the auto-detected project.

Returns:

{
  "status": "finalized",
  "locksReleased": ["src/auth.ts", "src/middleware/rateLimit.ts"],
  "sessionId": "sess_abc123"
}

What finalize does:

Releases every lock held in the session — equivalent to calling release_file_access on each one individually
Archives the session transcript, including the complete Axis MCP tool call timeline (and the host agent’s chat transcript if the client exposes it)
Restores original file permissions for any files that were chmod’d read-only under AXIS_ENFORCE_LOCKS=1
Records the session to history so it’s visible in the dashboard

When to call it: finalize_session belongs at the very end of the user’s complete request — after all jobs are done, all files are written, and there is nothing left to do. Do not call it after each sub-task and then continue working; a finalized session cannot hold locks for subsequent work.

`list_agents`

Returns the current presence roster for the project — which agents are active, which are idle, and what each active agent is working on. Useful before posting jobs to understand available capacity, or before claiming work to avoid duplicating an active agent’s effort.

projectName

string

The project to query. Defaults to the auto-detected project.

Returns: An array of agent presence records:

[
  {
    "agentId": "dana-claude-code",
    "status": "active",
    "lastSeen": "2026-08-02T14:30:00Z",
    "currentJob": "j_abc123"
  },
  {
    "agentId": "sam-cursor",
    "status": "idle",
    "lastSeen": "2026-08-02T14:15:00Z"
  }
]

Field	Values	Description
`agentId`	string	The agent’s unique session identity
`status`	`"active"` \| `"idle"`	Whether the agent has been active recently
`lastSeen`	ISO timestamp	When the agent last made a tool call
`currentJob`	string (optional)	The job ID the agent currently holds

`switch_project`

Local only. switch_project rebinds a local stdio session to a different workspace. The hosted server is stateless per request and resolves the project from each call’s projectName argument — there is nothing persistent to switch.

Rebinds the live local MCP session to a different workspace without disconnecting the MCP client. The new workspace root is resolved and all subsequent tool calls operate against the new project’s job board, locks, notepad, and soul.

workspaceRoot

string

required

The absolute path to the new repository on disk. The local server derives project identity from this root (nearest .axis/axis.json or folder name).

projectName

string

An explicit project name override for the new workspace. If omitted, the project name is auto-detected from the workspace root.

Returns: A confirmation of the new project identity — name, org, and resolved workspace root. When you need it: Workspace switching is automatic in normal use. Every tool call re-resolves the workspace from runtime hints (AXIS_WORKSPACE_ROOT, SUPERSET_WORKSPACE_PATH, etc.) and from any absolute file path in the call’s arguments. When either points at a different repository, the server rebinds in-process and notes the switch in the tool response — no restart required. switch_project is for explicit switches where you know you are moving to a different repo and want to force the rebind immediately, independent of any file paths in the next call.

switch_project is a local-only tool. The hosted server is stateless per request and resolves the project from each call’s projectName argument and org context — there is nothing persistent to switch.

Session lifecycle

Session starts — load the soul

The first action in every session is get_project_soul. This is non-negotiable per the agent protocol.

Work — claim, lock, write, update notepad

Claim jobs, lock files, do the work, and post notepad updates after each meaningful step. Release individual locks as jobs complete via complete_job.

All work done — finalize

When the user’s entire request is complete and there is nothing left to do, call finalize_session with a brief summary. This releases all remaining locks and archives the session.

finalize_session(content="Completed JWT refactor and rate limiter.
  Token shape changed to {userId, role, exp}. All callers updated.
  Rate limiter active on POST /api/login — see src/middleware/rateLimit.ts.")

Session archiving and transcript capture

Axis records every Axis MCP tool call and result at the protocol boundary, regardless of which MCP client is in use. This includes Claude Code, Cursor, Windsurf, Codex, Antigravity, Gemini CLI, and any other MCP-compatible client. Full user/assistant chat is added to the archive when the host exposes a transcript. Claude Code and Codex are detected automatically. For any other client, a transcript path can be provided:

{
  "env": {
    "AXIS_TRANSCRIPT_PATH": "/absolute/path/to/session.jsonl",
    "AXIS_TRANSCRIPT_FORMAT": "generic",
    "AXIS_AGENT_BASE": "github-copilot"
  }
}

The generic adapter accepts role/content, messages, tool_calls, tool_call, and tool_result shapes. When the host keeps its chat private, Axis still captures the complete Axis tool timeline — which is often sufficient for auditing and debugging multi-agent runs.

Overview

Job Board

File Locking

Context & Search

Session & Account

finalize_session, list_agents, and switch_project