AFK.md — Project Prompt Overlay

AFK.md is plain-markdown file that agent-afk appends to its built-in framework prompt whenever you run from a directory that contains one. It's the simplest way to give the agent project context — just a Markdown file, no env vars or JSON config needed.

What goes in AFK.md

Anything you would tell a collaborator before they start working in your repo:

• Project conventions (language, style, tooling)
• Commands to run before editing (build, test, lint)
• Directories to avoid or treat carefully
• Key architectural facts the agent should know upfront
• Links or summaries of internal documentation

There is no required structure and no frontmatter. Plain Markdown is all that is parsed.

Resolution order

loadConfig() checks both locations and loads whichever are present — the tiers are additive, not first-found-wins:

1. $AFK_HOME/AFK.md (default ~/.afk/AFK.md) — user-scope global: cross-project preferences that apply on every run.
2. <cwd>/AFK.md — project-scope: loaded when you run afk from inside a directory that contains one.

When both exist they are concatenated user-scope first, project-scope second, each under a heading naming its source path, with the project section explicitly marked as taking precedence on conflict. Broadest context lands first; the most specific instructions land closest to the conversation.

When only one exists — by far the common case — its content is used verbatim with no added headings, byte-identical to the previous single-tier behavior.

If both paths resolve to the same file (for example AFK_HOME pointed at your project directory, whether directly or through a symlink) it is loaded once, not twice.

If neither file exists, the framework prompt runs alone with no overlay. An empty or whitespace-only AFK.md is treated as absent — evaluated per file, so a blank project file still lets a populated personal one through.

How it layers with the framework prompt

The framework base prompt (prompts/system-prompt.md, baked in at publish time) is always present. AFK.md content is appended to it under an # Operator configuration header — it augments, never replaces, the base. Every overlay appends; there is no full-replace mechanism.

The same append behavior applies to all three operator overlay tiers (AFK_SYSTEM_PROMPT env, afk.config.json systemPrompt, AFK.md). Only one tier is used per session (highest priority wins). If AFK_SYSTEM_PROMPT is set, or afk.config.json has a systemPrompt field, AFK.md is not loaded.

Per-project vs. global

Use <cwd>/AFK.md when instructions are specific to one repo. Commit it alongside your code so every teammate gets the same context when they run afk.

Use ~/.afk/AFK.md for cross-project preferences — your coding style, default tool preferences, or a standing instruction you want in every session regardless of directory.

Generating an AFK.md with /init

In the REPL, /init scans the current project and writes a starter AFK.md with discovered conventions, test commands, and directory layout. Edit it afterward to add or remove context.

Inspecting the resolved overlay

afk --dump-prompt /tmp/resolved-prompt.txt

The output file includes a systemPromptSource header showing which tier was active (e.g. framework+afk-md:/path/to/AFK.md) and the full composed prompt. Use this to verify that your AFK.md is being picked up correctly.

Example

# My Project

TypeScript monorepo. Always run `pnpm install` before editing.

## Commands

- `pnpm build` — compile + copy prompt files to dist/
- `pnpm test` — vitest (Node 22+)
- `pnpm lint` — tsc --noEmit (strict; no unused vars/params)

## Conventions

- All env vars are declared in `src/config/env.ts`. Direct `process.env.*` reads outside that file fail CI.
- pnpm only — never npm or yarn.