Sessions & Connect
List your sessions, connect from another machine, or reattach after detaching.
Session Types
AFK has two types of sessions:
Detached Sessions
When you detach from a session (via ~. escape sequence or an SSH disconnection),
the wrapped command keeps running in the background on the local machine. Detached sessions can be reattached
to from the same machine using afk connect.
Remote Sessions
Any session started with afk stream is also streamed to the AFK backend,
making it a remote session. Remote sessions can be accessed from your phone, another computer, or any device
with the AFK app — from anywhere.
A session can be both detached and remote at the same time. For example, if you
start afk stream claude on your desktop and then detach, the session appears
as a detached session on that machine and as a remote session accessible from all your other devices. You can
reattach locally with afk connect, or continue interacting from your phone.
Listing Sessions
Use afk sessions to see your detached and remote sessions.
$ afk sessions
Detached sessions:
COMMAND DIRECTORY LOCATION STARTED SESSION ID
bash myproject pid:12346 3h ago 550e8400-e29b-...
Remote sessions:
COMMAND DIRECTORY HOST STARTED SESSION ID
claude myproject macbook-pro 8h ago a1b2c3d4-e5f6-...
bash myproject pop-os 3h ago 550e8400-e29b-...
Detached sessions are running on this machine but no longer attached to a terminal.
Reattach with afk connect.
Remote sessions are streamed to the AFK backend and accessible from any device (requires login).
A detached session may also appear here if it was started with afk stream.
Connecting to Sessions
Run afk connect to launch an interactive picker showing all your sessions —
both local and remote. Select one to connect.
# Launch the interactive session picker
afk connect
# Connect directly to a specific session
afk connect --session-id abc12345-...
Picker Controls
j/kor arrow keys — navigate sessionsEnter— connect to selected sessionq/Esc— cancel
When you connect, your terminal enters raw mode and you get full interactive access to the session.
The escape sequence ~. (newline, tilde, period) detaches again.
If the backend is unreachable (e.g., no internet), the picker shows only local sessions so you can still reconnect to sessions on this machine.
SSH Resilience
AFK sessions survive SSH disconnections. If you're running afk stream inside an
SSH session and your connection drops, the wrapped command keeps running in the background — similar to
tmux or screen.
# SSH in and start a long-running session
ssh dev-server
afk stream claude
# ... SSH connection drops ...
# Reconnect and pick up where you left off
ssh dev-server
afk connect
The session will appear as "detached" in the picker. Select it to reattach with full interactive access.
Account
# Show login status and token info
afk status
# Show who you are logged in as
afk whoami
# Logout and delete stored tokens
afk logout
Authentication tokens are stored locally. Use afk logout to remove them.
You can also force re-login on any command with the --login flag.