Connect a session

What you need

• A working @gent setup from Getting started. The runner must be running and ready.
• A persisted Claude Code or Codex session in a project folder from your config.
• The setup uses the local MCP server and the native identity hooks below.

You do not need a website account. The CLI, MCP server and email work without the dashboard.

Add the MCP server

Register the local server with your agent. The server runs on your computer over stdio and opens no network port.

If your runner uses a config outside the default location, add --config /absolute/path/config.json before mcp. The server offers attach_session, list_sessions, session_status and email_session.

Turn on the identity hooks

The MCP server alone cannot identify the conversation calling it. The hooks give the agent its exact session ID and project, so the agent never guesses from the newest transcript.

Without --output, the command prints the hooks and changes nothing. With it, @gent adds its hooks and keeps your existing ones. If you use CLAUDE_CONFIG_DIR or CODEX_HOME, write to that profile's file. Trust the new hooks if your agent asks, then restart or resume the session.

Ask for the email

In the session, ask: email me this session. The agent connects the session and @gent queues an opening email in a new thread. No second agent starts.

> email me this session

atgent · attach_session (MCP)

Connected as task 7c41e2d0. The opening email is queued. Replies wait until you close this session and run atgent handoff 7c41e2d0.

$ atgent handoff 7c41e2d0
Task 7c41e2d0: queued (email ownership)

Hand it off

After you connect a session, the terminal still controls it. You can reply from your phone at once, but email replies wait. Close the local session, then run:

Use your own task ID from the opening email. The handoff tells @gent that the local session is closed. @gent cannot see every agent process, so it never releases a session on a timer. Do not keep working in the local session after the handoff.

Connect a session without hooks

If your agent version or an admin policy blocks hooks, connect the session with its exact session ID and project alias:

A session ID alone is not enough. @gent checks that the session exists in the configured agent profile and belongs to that project folder. Deleted, unsaved and ephemeral sessions cannot be connected.

Optional: list new sessions automatically

Add --auto-register to also install a Stop hook. After each completed turn, it lists that session in atgent list, the email directory and a paired dashboard. It sends no email.

The hook covers only sessions in projects and profiles from your config. It does not import older sessions, and it never releases a session from the terminal. To stop it, remove only the @gent Stop handler from your agent's hooks.

If something waits

• A reply does nothing. The session is still held locally. Close it and run atgent handoff TASK_ID.
• Handoff refuses. A session opened with atgent open is still running. Close it first.
• No opening email. Check that the runner is ready with atgent status --human. A queued email is not proof of delivery.
• Commands refuse an older runner. Run atgent start after upgrading.

The computer must stay awake and online with the runner active. See Troubleshooting for runner messages.

Checked against @gent 0.5.0.