Run afk without a human at the keyboard

AFK can keep working while you are away, but a background process, a daemon, and an autonomous interactive session have different lifetimes and safety boundaries. Choose the smallest surface that fits the job, tell it what success means, and arrange a way to inspect the result.

Choose the right modeCopy Anchor Link

Autonomous mode is a permission mode, not a process supervisor. It does not make a laptop stay awake, restart a crashed REPL, or turn session-owned background jobs into services.

Leave an interactive session safelyCopy Anchor Link

afk telegram setup
afk telegram start

/afk on

Run the project's test suite. Diagnose failures and make a local fix if needed.
Run the relevant tests again after the final edit. Do not push, publish, or send
messages to third parties. Report Done with the changed files and test results,
or Blocked with the exact dependency that prevents completion.

Autonomous permissions and phone approvalsCopy Anchor Link

In AFK mode, safe and medium-risk operations can proceed without an ordinary keyboard permission prompt. High-risk operations, such as destructive commands, writes outside the trusted workspace, and schedule mutations, require special handling.

For the top-level interactive session, AFK routes an approve or deny this single call request through the phone channel, racing the keyboard fallback. Telegram displays an inline choice with the operation and input preview. Approval permits only that call, not every future operation of the same type.

The default approval window is five minutes, starting when the request is actually shown. Denial, cancellation, no reachable operator, an invalid response, or timeout refuses the call. Subagents cannot obtain their own high-risk approval through this gate; they must report the blocker to the parent.

The daemon has a different contract: it bypasses ordinary interactive permission prompts, but separately applies the autonomous high-risk gate with phone approval disabled. High-risk operations are refused immediately rather than left waiting for a human. A task may disable itself through a narrowly scoped exception; that is not general permission to modify other schedules.

Check what Done meansCopy Anchor Link

Ask for a terminal state and evidence you can inspect:

A successful process exit or an agent saying Done does not certify the task's correctness. For code work, require meaningful tests or checks after the last change.

For REPL-to-Telegram reporting, telegram.verifyDone: true enables an evidence check. It looks for successful evidence-producing tool calls and, when code changed, a recognized successful verification step afterward. An unsupported Done claim is labeled Done (unverified) rather than treated as proven.

Daemon completion notifications use daemon.verifyDone, enabled by default unless explicitly set to false. That daemon check is narrower: it looks for a successful evidence-producing tool name in the turn. It is not equivalent to independently validating the artifact or proving that a test ran after the final edit.

See verification for stronger completion checks and observability for durable traces.

Avoid unresolved commandsCopy Anchor Link

AFK injects an instruction at session start to resolve values before handing you runnable commands, or explicitly flag values it cannot discover. The REPL also has a Stop hook that scans shell-like output blocks for unresolved placeholders such as YOUR_API_KEY, REPLACE_ME, and angle-bracket tokens.

When detected, it injects a correction asking the model to resolve or visibly mark them. This detector is REPL-only, skips subagents, and is bounded to two correction injections per session. It does not block output or guarantee that every placeholder will be caught. Headless chat, daemon, and Telegram receive the prevention instruction, not this rendered-code-block scanner.

Before running any handed-off command, check that it names real resources and that its effect matches your intent.

Set budgets and time boundariesCopy Anchor Link

USD budgeting is opt-in. AFK_MAX_BUDGET_USD is unset by default, not a built-in five-dollar allowance. Where provider cost accounting is available, crossing a configured ceiling aborts the turn. Subscription runs may not report a meaningful dollar cost, so a dollar cap is not a universal spending guarantee.

AFK_MAX_BUDGET_USD=2.00 afk daemon --once \
  --task "Run the test suite and report the outcome without changing files" \
  --timeout-ms 600000

AFK_TASK_BUDGET configures a per-task token budget. AFK_MAX_OUTPUT_TOKENS caps individual responses; the old AFK_MAX_TOKENS variable is inert. For one-shot chat, --max-budget-usd and --task-budget are available as flags. The daemon does not expose those two flags; use its environment configuration instead.

Use --timeout-ms to bound a daemon tick. Use runAt and expiresAt to bound a schedule's window, and a pinned cwd to stop a service-launched task from searching an unintended directory. See usage and cost for provider-specific accounting and limits.

Keep supervision separate from schedulingCopy Anchor Link

A minimal bounded daemon run is:

afk daemon --once --task "Inspect the repository and write a local health report"

--once fires one tick and exits. Without --once, the daemon is a scheduler process, not an interactive conversation that ends when one task reaches Done. A plain afk daemon can load saved schedules; it does not invent a default task.

Create routine work with afk schedule add, inspect it with afk schedule list, and use execution history to verify actual runs. For event-driven submissions, afk queue add feeds a daemon started with --trigger pull. Notification delivery requires configured Telegram routing and the task's notifyOn policy; it is not guaranteed merely because a daemon exists.

RelatedCopy Anchor Link