agentafk

Get started with afk

Install afk, authenticate with a model provider, and start a useful session in your project.

Use this path to ask afk a useful question about a project without changing files. You need a supported Node.js version, npm, and access to a model provider. This example uses an Anthropic API key or an existing Claude credential.

Install

Check Node.js, then install the package:

node --version
npm install -g agent-afk
afk --version

Supported Node.js versions are ^22.22.2 || ^24.15.0 || >=26.0.0. For platform details and shell setup, see Installation.

Authenticate

afk login

On an unconfigured install, this checks for an existing Anthropic credential. If none is found, it prompts for an Anthropic API key or OAuth token without displaying what you type, then saves it in ~/.afk/config/afk.env.

afk login does not open a browser OAuth flow. If you already use Claude Code, afk can reuse a supported credential from claude login. For OpenAI, other providers, or local models, follow API keys and authentication instead.

Open your project and ask a bounded question

In your terminal, change into the project you want afk to inspect. Then run:

afk --permission-mode default "Explain what this project does and where its main entry points are. Do not modify files or run installation commands."

The quoted text is submitted as the first message. The REPL stays open so you can ask follow-up questions. The explicit default permission mode enables path containment and approvals for file access outside granted roots.

New CLI installations otherwise start in bypassPermissions, not approval mode. Even default is not an OS sandbox or a confirmation prompt for every shell command. Start with a trusted project and read Permissions.

Continue, then exit

Try a follow-up such as:

Which test would you run first to check a small change here?

Type /help to see commands, or /exit to leave. Sessions autosave, so you can return with /resume in a later REPL session.

Prefer a single response?

Use chat for one prompt without staying in an interactive session:

afk chat "Explain what this project does. Do not modify files." --permission-mode default

See One-shot chat for piping, output formats, and scripting.

Choose a model

Override the model for a single launch:

afk chat "Explain this project's structure. Do not modify files." --model opus --permission-mode default
afk i --model haiku --permission-mode default

sonnet, opus, haiku, and fable are model aliases. Capability slots such as small, medium, and large let you configure which model each tier uses. In the REPL, /model opens a picker. See Models and providers before switching to a provider that needs different credentials.

If setup fails

Run the environment and configuration checks:

afk doctor

Use Authentication troubleshooting if the first model request fails. A successful afk --version only confirms the executable is installed, not that a provider is authenticated.

Run your first session

Tour slash commands, permissions, interrupting, and resuming.

Install and update afk

Platform requirements, shell completion, and updates.

Choose models and providers

Use a different provider or switch models for your task.

Agent AFK

Use afk to work with an AI agent in your terminal, automate tasks, and supervise work from other surfaces.

Install afk on your computer

Install, update, and remove afk on macOS, Linux, or Windows.

On this page

InstallAuthenticateOpen your project and ask a bounded questionContinue, then exitPrefer a single response?Choose a modelIf setup failsRelated