Install afk on your computer

Install the agent-afk npm package to get the afk command. It runs on macOS, Linux, and native Windows. WSL2 is an alternative if you prefer a Linux environment on Windows.

RequirementsCopy Anchor Link

• Node.js matching ^22.22.2 || ^24.15.0 || >=26.0.0. In plain terms: Node 22.22.2 or newer within 22.x, Node 24.15.0 or newer within 24.x, or Node 26 and later.
• npm, available with a standard Node.js installation. You do not need pnpm to install the published CLI.
• A terminal and access to a configured model provider, or a local model server.
• Git if you want to use repository and worktree workflows.

Install for your platformCopy Anchor Link

node --version
npm --version

npm install -g agent-afk
afk --version

Authenticate and check the installationCopy Anchor Link

On an unconfigured install using Claude, start with:

afk login
afk doctor

afk login reuses an existing Anthropic credential when one is available, or prompts for a key or OAuth token and saves it. It is not a browser sign-in command. See API keys and authentication for other providers and credential sources, then follow the Quickstart for your first model request.

Bring an existing setupCopy Anchor Link

If you have Claude Code or Codex plugins, skills, or MCP configuration, preview an import:

afk migrate --dry-run

Run afk migrate to review and confirm the detected sources. It records a trust grant and live-reads the source directories on later sessions rather than copying the files. MCP servers are excluded unless you pass --mcp, because they can run commands at startup. -y skips the confirmation for a deliberately unattended import. See Migrate an existing setup before granting that trust.

Shell completionCopy Anchor Link

afk completion requires a shell name and prints a completion script. Supported shells are zsh, bash, and fish, not PowerShell. Add the appropriate line to your shell startup configuration to load it in future terminals:

autoload -Uz compinit
compinit
eval "$(afk completion zsh)"

Optional worktree shell integrationCopy Anchor Link

The optional shell-init wrapper lets afk change your parent shell's directory into a preserved worktree after a session exits. Without it, afk can print the directory but cannot change your shell's working directory.

For bash or zsh, add this line to your shell startup configuration:

eval "$(afk shell-init)"

For fish:

afk shell-init fish | source

Update afkCopy Anchor Link

afk update --check
afk update

--check reports whether a newer version exists without installing it. afk update installs the latest published version through npm using the running Node installation. afk upgrade is an alias. Use --pin with a specific published version if you need to install that version instead of the latest.

Automatic update behavior is controlled by updatePolicy:

To disable automatic checks:

afk config set updatePolicy off

Use Editing configuration for other values and configuration scope. For service behavior and all update options, see Run as a service and the CLI reference.

UninstallCopy Anchor Link

If you installed background services, remove them through afk service uninstall before removing the CLI. See Run as a service for service names and removal steps.

Remove the npm package:

npm uninstall -g agent-afk

This does not erase your saved configuration, credentials, or sessions under ~/.afk/. Remove any completion and shell-init lines you added to your shell startup files. Keep or back up the state directory unless you deliberately want to remove that data too.

RelatedCopy Anchor Link