agent-afk 2.26.0 → 2.26.2

package/README.md

@@ -1,794 +1,133 @@
-# Agent AFK CLI
-
-> A TypeScript CLI, daemon, and Telegram bot for running Claude (via `@anthropic-ai/sdk`) or OpenAI Codex — ships four orchestration skills as built-in subagent dispatchers with cross-session memory, DAG-composed waves, and background-task support.
-
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
-
-## Features
-
-- 🚀 **Provider abstraction** — Anthropic (direct) and OpenAI Codex; native subagents, hooks, elicitations, cost guardrails
-- 🧩 **Four built-in orchestration skills** — `/mint`, `/diagnose`, `/forge`, `/audit-fit`, each dispatched as an isolated subagent
-- 🧠 **Cross-session memory** — `memory_search`, `memory_update`, `procedure_write` tools backed by SQLite + `HOT.md`
-- 🕸️ **DAG-composed parallel waves** — built-in `compose` tool runs subagent nodes with dependency edges and fail-fast
-- ⏱️ **Background tasks** — Ctrl+B detaches the current turn; `/bg`, `/tasks`, `/attach` manage long-running work
-- 📲 **`send_telegram` built-in tool** — agents can push terminal-state notifications to the operator
-- 🔌 **Plugin & marketplace install** — `afk plugin install` / `afk marketplace add` keep everything under `~/.afk/`
-- 🏠 **AFK-scoped config** — `~/.afk/` independent of `~/.claude/`, with sessions, plugins, agents, commands, skills
-- 💬 **Three surfaces** — interactive REPL, daemon, Telegram bot sharing one session manager
-- 📊 **Routing telemetry** — every subagent dispatch appended to `~/.afk/agent-framework/routing-decisions.jsonl`
-- 🤖 **Multiple models** — Opus, Sonnet, Haiku (Anthropic); GPT-5 family via Codex
-- 🧠 **Extended thinking on by default** — controllable via `AFK_THINKING` / `--thinking`
-- 🔓 **Bypass permissions mode** — no prompts, fully automated tool execution
-- 🛡️ **Type-safe** — TypeScript strict mode
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Usage](#usage)
-- [Orchestration Skills](#orchestration-skills)
-- [Scripts](#scripts)
-- [Configuration](#configuration)
-- [Plugins & Slash Commands](#plugins--slash-commands)
-- [Bypass Permissions Mode](#bypass-permissions-mode)
-- [Development](#development)
-- [Troubleshooting](#troubleshooting)
-- [API Reference](#api-reference)
-- [License](#license)
-
-## Installation
-
-### Prerequisites
-
-- **Node.js ≥ 20.0.0** (enforced by `package.json#engines`)
-- **pnpm** — this project's lockfile is pnpm-specific. Running `npm install` will desync it.
-  - Fastest path: `corepack enable` (bundled with Node ≥ 16.9), then use `pnpm` directly.
-  - Or install globally: `npm install -g pnpm@latest`.
-- A valid Anthropic API key ([console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys))
-
-### Install from source
+# Agent AFK
 
-```bash
-git clone https://github.com/griffinwork40/agent-afk.git
-cd agent-afk
-corepack enable            # optional, pins pnpm to the repo's version
-pnpm install
-pnpm build
-```
-
-## Quick Start
-
-1. **Configure your API key:**
-
-   ```bash
-   cp .env.example .env
-   # Edit .env and set ANTHROPIC_API_KEY
-   ```
-
-2. **Build:**
-
-   ```bash
-   pnpm build
-   ```
-
-3. **Run your first command:**
-
-   ```bash
-   pnpm start -- chat "What is 2+2?"
-   ```
-
-4. **Check status:**
-
-   ```bash
-   pnpm start:status
-   ```
-
-> Runtime state (sessions, plugins, SDK settings) lives under `~/.afk/`, not `~/.claude/`. See [Configuration → Config Home](#config-home-afk) below.
-
-## Usage
-
-### Quick Aliases
-
-- `afk c` — alias for `afk chat`
-- `afk i` — alias for `afk interactive`
-- `afk s` — alias for `afk status`
-
-### CLI Commands
-
-The `afk` CLI exposes eleven top-level commands registered in `src/cli/index.ts`:
-
-| Command | Purpose |
-|---|---|
-| `chat` | Single-turn message |
-| `interactive` | REPL with full Agent SDK features (default when invoked without a subcommand) |
-| `status` | Connection, API-key, model, bypass-mode status |
-| `config` | Dump resolved configuration |
-| `daemon` | Long-running headless agent (see `src/agent/daemon/`) |
-| `login` | OAuth flow for `console.anthropic.com` |
-| `plugin` | Manage `~/.afk/plugins/` (install / update / list / remove / enable / disable) |
-| `marketplace` | Add / list / remove plugin marketplaces under `~/.afk/marketplaces/` |
-| `doctor` | Environment self-check (Node version, API keys, paths, config) |
-| `completion` | Print a shell completion script (`zsh`, `bash`, `fish`) |
-| `telegram` | Manage the Telegram bot daemon (start, stop, status, logs, setup) |
-
-#### Chat (single message)
-
-```bash
-pnpm start -- chat "What is the capital of France?"
-pnpm start -- chat "Hello" --model opus
-pnpm start -- chat "Test" --format json
-pnpm start -- chat "Tell me a story" --stream
-```
-
-#### Interactive mode
-
-```bash
-pnpm start:interactive
-pnpm start -- interactive --model haiku
-```
-
-In interactive mode: type messages, Claude responds with full tool access, Ctrl+C exits.
-
-#### Status
-
-```bash
-pnpm start:status
-```
-
-Shows SDK connection, API-key validation, default model, bypass-mode state.
-
-Supports `--format json` for machine-readable output.
-
-#### View configuration
-
-```bash
-pnpm start -- config
-```
-
-Supports `--format json` for machine-readable output.
-
-#### System Health Check
-
-```bash
-npm start -- doctor
-```
-
-Run a self-check on environment, API keys, and configuration. Use `--format json` for machine-readable output.
-
-#### Shell Completion
+> Past the happy path of AI coding.
+>
+> One prompt, one agent, one clean diff is the easy case. **Agent AFK** is the runtime for everything after — multi-session work, nested subagents, verification loops, and traces you can actually read. Local-first. Bring your own model.
 
-```bash
-npm start -- completion <zsh|bash|fish>
-```
+[![npm version](https://img.shields.io/npm/v/agent-afk.svg)](https://www.npmjs.com/package/agent-afk)
+[![Node](https://img.shields.io/node/v/agent-afk.svg)](https://nodejs.org/)
 
-Print a shell completion script. To enable completions, append to your shell rc file:
+## Install
 
 ```bash
-afk completion zsh >> ~/.zshrc
-afk completion bash >> ~/.bashrc
-afk completion fish >> ~/.config/fish/conf.d/afk.fish
+npm install -g agent-afk
 ```
 
-#### Plugin Management
+Requires Node ≥ 20. Then point it at an API key:
 
 ```bash
-npm start -- plugin list
+export ANTHROPIC_API_KEY=sk-ant-...
+# or, for Anthropic OAuth:
+afk login
 ```
 
-Supports `--format json` for machine-readable output.
-
-### Telegram Bot
-
-Run Claude as a Telegram bot with full Agent SDK capabilities:
+Smoke test:
 
 ```bash
-# 1. Get a bot token from @BotFather on Telegram
-#    - Open Telegram, search @BotFather
-#    - Send /newbot and follow instructions, copy the token
-# 2. Add to .env:  TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHI...
-# 3. Build and run
-pnpm build
-pnpm telegram
+afk chat "hello"
+afk doctor       # environment self-check
 ```
 
-**Bot commands:**
-- `/start` — welcome
-- `/reset` — clear conversation
-- `/model opus|sonnet|haiku` — switch model
-
-Send any other message to chat. The bot has full tool access via bypass mode.
-
-Background-service helpers:
-
-```bash
-pnpm telegram:start
-pnpm telegram:stop
-pnpm telegram:status
-pnpm telegram:restart
-```
+## What you can do with it
 
-## Orchestration Skills
+- **Chat from your terminal** — `afk chat "..."` for one-shot, `afk i` for a REPL with full tool access (Bash, file ops, web fetch, grep/glob, subagents).
+- **Hand long work off to a daemon** — `afk daemon` runs headless. Pair it with `send_telegram` and you get pings on your phone when work lands in a terminal state.
+- **Message Claude from Telegram** — `afk telegram setup` walks you through bot token + allowlist. After that you have a private chat surface backed by the same session manager as the REPL.
+- **Built-in orchestrators** — `/mint`, `/diagnose`, `/forge`, `/audit-fit` dispatch subagent waves. `/mint` takes a feature idea and runs spec → research → plan → parallelize → build → verify → ship. `/diagnose` forks parallel root-cause hypotheses for failing tests and bugs.
+- **Cross-session memory** — Claude remembers preferences, decisions, and procedures across runs. Backed by SQLite at `~/.afk/agent-framework/memory/` plus a `HOT.md` that injects into every future session's system prompt.
+- **Background tasks** — Ctrl+B in the REPL detaches the current turn into a tracked task; `/tasks` lists them, `/attach <id>` re-attaches.
 
-agent-afk ships four built-in subagent orchestrators. These are **built-in skills** exposed through the slash registry: typing `/mint add dark mode` in the REPL parses the slash form, resolves it to a TypeScript handler under `src/skills/<name>/index.ts`, and dispatches a fresh subagent via `SubagentManager.forkSubagent()`. Every dispatch is logged to `~/.afk/agent-framework/routing-decisions.jsonl`.
+## Four surfaces, one session manager
 
-The canonical list lives in `src/skills/all.ts`:
-
-| Skill | Purpose |
+| Command | Surface |
 |---|---|
-| `/mint` | End-to-end feature/refactor pipeline: spec → research → plan → parallelize → build → verify → heal → ship |
-| `/diagnose` | Parallel hypothesis generation + validation for bugs and failing tests |
-| `/forge` | Generate new skills autonomously, gated by L1/L2 capability evals (gate-check is inlined; no separate `/forge-gate-check` skill) |
-| `/audit-fit` | Audit `~/.afk` artifacts (skills, commands, agents, hooks) for correct type categorization |
-
-Skills surface in two shapes:
-
-- **Built-in (this repo)** — TypeScript handlers under `src/skills/<name>/`, registered via `src/skills/all.ts` and bridged into the slash registry by `src/cli/slash/builtin-skills.ts`.
-- **Plugin / user** — `SKILL.md` files discovered under `~/.afk/plugins/<plugin>/skills/<skill>/` or `~/.afk/skills/<skill>/`, scanned at session start and auto-exposed as slash commands.
-
-Vendored subagents (`qualify`, `research-agent`, `contract`) live under `src/skills/_agents/` and are kept byte-equal with the upstream copies — drift is caught by tests in `src/skills/_agents/`.
-
-See [`AGENTS.md`](AGENTS.md) and [`CONTRIBUTING.md`](CONTRIBUTING.md) for repo conventions; the workspace-root [`SYSTEM.md`](../SYSTEM.md) covers the broader topology when present.
-
-## Scripts
-
-```bash
-# Build / dev
-pnpm build                  # tsc && node scripts/copy-prompts.js (markdown prompts → dist/)
-pnpm build:dist             # esbuild bundle into dist/ for release artifacts
-pnpm dev                    # tsx watch src/cli/index.ts
-pnpm start                  # node dist/cli/index.js
-pnpm start:chat             # shortcut for `chat`
-pnpm start:interactive      # shortcut for `interactive`
-pnpm start:status           # shortcut for `status`
-pnpm clean                  # rm -rf dist
-
-# Testing
-pnpm test                   # vitest run (all)
-pnpm test:integration       # vitest run tests/integration  (note: dir not yet populated)
-pnpm test:e2e               # vitest run tests/e2e          (note: dir not yet populated)
-pnpm test:coverage          # with coverage report
-pnpm test:watch             # watch mode
-pnpm lint                   # tsc --noEmit (type-check only)
-
-# Telegram daemon
-pnpm telegram               # run in foreground
-pnpm telegram:setup         # interactive setup wizard (bot token, allowed chat IDs)
-pnpm telegram:start         # background service (launchd/systemd-style wrapper)
-pnpm telegram:stop
-pnpm telegram:status
-pnpm telegram:restart
-pnpm telegram:logs          # tail the background-service log
-
-# Release
-pnpm release                # scripts/release.mjs — version bump + publish flow
-pnpm release:dry            # dry-run release flow (no git push / no npm publish)
-```
-
-> Note: `tests/integration/` and `tests/e2e/` directories are not yet populated — the live test suites live under `tests/agent/`, `tests/telegram/`, and colocated `*.test.ts` files in `src/`. The `test:integration` / `test:e2e` scripts are kept as placeholders for the planned split.
+| `afk chat "..."` | One-shot turn — pipe-friendly, scripts well |
+| `afk i` (alias of `afk interactive`) | REPL with slash commands, streaming, plan mode, image paste |
+| `afk daemon` | Long-running headless agent, cron-friendly |
+| `afk telegram start` | Telegram bot — same tools, same memory, on your phone |
 
 ## Configuration
 
-### Config Home (`~/.afk/`)
-
-agent-afk keeps its configuration and user-scope runtime state under `~/.afk/`, fully independent of Claude Code's `~/.claude/`. AFK resolves plugins, agents, commands, skills, and `settings.json` directly from that home:
-
-```
-~/.afk/
-  config/              afk.env, afk.config.json
-  state/               sessions/, todos/, daemon/
-  logs/
-  cache/
-  plugins/             user-installed Claude plugins (starts empty)
-  agents/              user-defined subagents (SDK)
-  commands/            user-defined slash commands (SDK)
-  skills/              user-defined skills (SDK)
-  settings.json        SDK settings (model, permissions, MCP, etc.)
-  agent-framework/     forge telemetry + ceiling ledger + briefs
-```
-
-You can delete `~/.claude/` entirely and agent-afk still runs.
-
-### Environment Variables
-
-Create a `.env` file in the project root:
+`agent-afk` keeps all of its state under **`~/.afk/`** — sessions, plugins, memory, logs, settings. Nothing is shared with `~/.claude/`. You can delete `~/.claude` entirely and `afk` still runs.
 
-```env
-# Required (Anthropic provider)
-ANTHROPIC_API_KEY=sk-ant-api03-...
-
-# Provider / model selection
-AFK_MODEL=sonnet                   # opus | sonnet | haiku (Anthropic) or codex (default sonnet)
-AFK_DEFAULT_SUBAGENT_MODEL=        # override default subagent model
-AFK_THINKING=on                    # on | off | <budget-tokens> — extended thinking (on by default)
-AFK_EFFORT=                        # low | medium | high — reasoning effort (Codex provider)
-AFK_MAX_OUTPUT_TOKENS=             # cap on output tokens per turn
-AFK_TEMPERATURE=                   # numeric override; provider-default if unset
-AFK_TIMEOUT_MS=                    # per-turn timeout
-
-# Cost guardrails (see SDK-native features below)
-AFK_MAX_BUDGET_USD=5.00
-AFK_TASK_BUDGET=100000
-
-# Prompt cache (anthropic-direct provider) — see Prompt Caching below
-AFK_DISABLE_PROMPT_CACHE=          # 1 | true | yes | on disables; unset = enabled
-AFK_PROMPT_CACHE_TTL=1h            # 5m | 1h (default 1h)
-
-# Cross-session memory & system prompt
-AFK_SYSTEM_PROMPT=                 # raw string — highest-priority override of AFK.md
-AFK_HOME=                          # override ~/.afk
-AFK_STATE_DIR=                     # override ~/.afk/state
-AFK_FRAMEWORK_DIR=                 # override ~/.afk/agent-framework
-AFK_AUTO_ROUTING=                  # auto-route bare slash inputs to skills
-
-# Telegram bot (foreground + background daemon + send_telegram tool)
-TELEGRAM_BOT_TOKEN=1234567890:ABC...
-AFK_TELEGRAM_BOT_TOKEN=            # alternative name accepted by setup wizard
-AFK_TELEGRAM_ALLOWED_CHAT_IDS=     # comma-separated chat IDs allowed to push to / receive from
-TELEGRAM_DATA_DIR=                 # override Telegram state dir (defaults under ~/.afk/state)
-TELEGRAM_VERBOSE=                  # 1 to log per-message details
-AFK_TELEGRAM_TRACE=                # 1 to dump raw bridge traffic
-
-# Debug / dev
-AFK_DEBUG=                         # 1 enables verbose logging
-AFK_DEBUG_CLIPBOARD=               # debug bracketed-paste / image-paste handling
-AFK_DUMP_PROMPT=                   # write resolved system prompt to a file
-
-# Color output (per https://no-color.org)
-NO_COLOR=                          # set to disable colors; unset = auto-detect (CI / pipes)
-```
-
-The authoritative list of supported env vars lives in `src/` — search for `process.env.AFK_` or `process.env.TELEGRAM_` for the full surface. `.env.example` mirrors the most common ones.
-
-### System Prompt Auto-Discovery
-
-agent-afk resolves the session system prompt through a 4-tier precedence chain (highest tier wins):
-
-| Tier | Source | Notes |
-|------|--------|-------|
-| 1 | `AFK_SYSTEM_PROMPT` env var | Highest priority — overrides everything |
-| 2 | `afk.config.json` (`systemPrompt` field) | Searched in: `<cwd>/afk.config.json` → `~/.afk/config/afk.config.json` → legacy `~/.afk.config.json` |
-| 3 | `AFK.md` file | Searched in: `<cwd>/AFK.md` → `$AFK_HOME/AFK.md` (default `~/.afk/AFK.md`) |
-| 4 | None | `systemPrompt` is `undefined`; SDK uses its default behavior |
-
-**AFK.md format:** Plain Markdown, no frontmatter. The entire file content (trimmed) becomes the system prompt. Empty or whitespace-only files are treated as absent (tier 4 applies instead).
-
-**Bootstrapping AFK.md:** run `/init` in the REPL to scan the current project and generate a tailored `AFK.md` at the repo root. See `src/cli/slash/commands/init.ts`.
-
-**Provenance tracking:** When using `--dump-prompt`, the `systemPromptSource` field in the dump shows which tier won:
-- `"env:AFK_SYSTEM_PROMPT"` — tier 1
-- `"file:/abs/path/afk.config.json"` — tier 2
-- `"afk-md:/abs/path/AFK.md"` — tier 3
-
-### Prompt Caching (anthropic-direct provider)
-
-The `anthropic-direct` provider stamps two `cache_control` breakpoints per request — one at the end of `system` (which implicitly caches `tools + system` together) and one at the end of the last `messages[]` entry. The end-of-messages marker floats forward each turn; cache lookup walks back over prefix-hash matches up to a 20-block window, so the moving marker still hits prior cache writes within a tool-use loop and across consecutive turns.
-
-Defaults are tuned for `agent-afk`'s long-lived surfaces (daemon, Telegram bot) which often idle past the 5-minute window:
-
-| Variable | Values | Default | Effect |
-|---|---|---|---|
-| `AFK_DISABLE_PROMPT_CACHE` | `1` / `true` / `yes` / `on` (case-insensitive) | unset (cache enabled) | Disables both breakpoints; useful for A/B comparisons and debugging cache-attribution issues |
-| `AFK_PROMPT_CACHE_TTL` | `5m` / `1h` | `1h` | TTL for both breakpoints. Anything other than `5m` or `1h` falls back to the default |
-
-Markers never leak back into stored history — `cache-policy.ts` clones-and-stamps so the canonical `messages` array stays marker-free across iterations (accumulating markers would break prefix-hash matching). Implementation: [`src/agent/providers/anthropic-direct/cache-policy.ts`](src/agent/providers/anthropic-direct/cache-policy.ts).
-
-### Supported Models & Providers
-
-agent-afk speaks to two providers through a single abstraction (`src/agent/providers/`):
-
-**Anthropic (direct)** — default. Selects from:
-- **opus** — most capable, for complex tasks
-- **sonnet** — balanced performance and speed (default)
-- **haiku** — fastest, best for simple tasks
-
-**OpenAI Codex** (`@openai/codex-sdk`) — set `AFK_MODEL=codex` (or pass `--model codex`). Implementation lives in `src/agent/providers/openai-codex.ts`. Tune reasoning effort via `AFK_EFFORT=low|medium|high`.
-
-Per-session overrides: `--model <name>`, `--thinking <on|off|N>`, `--max-output-tokens <n>`, `--temperature <n>`.
-
-## Plugins & Slash Commands
-
-### Installing plugins
-
-The `/plugin` slash command (and marketplace-based install) is a Claude Code CLI feature, not an Agent SDK feature — see [anthropics/claude-code#15071](https://github.com/anthropics/claude-code/issues/15071). Inside an agent-afk session those commands don't exist, and marketplace installs run from Claude Code still land in `~/.claude/plugins/`. AFK ships its own `afk plugin` subcommand that keeps everything under `~/.afk/plugins/`:
-
-```bash
-# Install from a GitHub shorthand (expands to https://github.com/<owner>/<repo>.git)
-afk plugin install anthropics/claude-plugins-official
-
-# Install from an explicit git URL (https or ssh)
-afk plugin install https://github.com/example/my-plugin.git
-
-# Install from a local checkout (symlinks into ~/.afk/plugins/)
-afk plugin install ~/Projects/personal_projects/agent-workspace/agent-framework-private
-
-# Pin to a specific tag, branch, or SHA
-afk plugin install owner/repo --ref v1.2.3
-
-# List, update, and disable without deleting
-afk plugin list
-afk plugin update                                # all plugins
-afk plugin update claude-plugins-official
-afk plugin disable claude-plugins-official
-afk plugin enable  claude-plugins-official
-afk plugin remove  claude-plugins-official
-```
-
-By default `install` picks the highest semver git tag, falling back to the default branch when no tag parses as semver. State lives in `~/.afk/plugins/.index.json` — the scanner reads it at session startup and skips any entry with `enabled: false`.
-
-Advanced: AFK still auto-discovers any plugin dropped into `~/.afk/plugins/<name>/` by hand (git clone, symlink, or copy). The directory just has to contain `.claude-plugin/plugin.json`; the scanner walks up to 5 levels deep so Claude Code's `cache/<marketplace>/<plugin>/<version>/` layout also works.
-
-Plugin state (telemetry, ledger, briefs) writes to `~/.afk/agent-framework/` in the AFK runtime.
-
-### REPL slash commands
-
-The interactive REPL registers slash commands directly in TypeScript (`src/cli/slash/`) — they don't pass through to any external Claude Code subprocess. Categories:
-
-**Core / session control**
-- `/help` — list all available slash commands (built-in + plugin-loaded)
-- `/exit`, `/quit` — leave the REPL
-- `/clear` — clear screen
-- `/compact` — manually compact conversation history
-- `/reset` — start a fresh session, discarding history
-
-**Information**
-- `/cost` — running cost for the session
-- `/tokens` (alias `/ctx`) — SDK breakdown of context usage
-- `/history` — print prior turns
-- `/model` — show or switch active model
-- `/tools` — list registered tools
-- `/mcp` — show MCP server status
-- `/limits` — show rate-limit / budget state
-- `/debug` — toggle verbose debug output
-
-**Planning & state**
-- `/plan` — open the plan editor
-- `/todo` — manage the persistent todo list
-- `/save` — snapshot session state to disk
-- `/resume` — resume a saved session
-- `/init` — scan the current project and write `AFK.md`
-- `/changelog` — render `CHANGELOG.md` paginated
-
-**Background tasks** (Ctrl+B detaches the current turn)
-- `/bg` — list backgrounded tasks
-- `/tasks` — show running/queued tasks with status
-- `/attach <id>` — re-attach to a backgrounded task
-
-**Skills (built-in)** — see [Orchestration Skills](#orchestration-skills)
-- `/mint`, `/diagnose`, `/forge`, `/audit-fit`
-
-**Plugins / marketplaces**
-- `/skills` (alias `/builtin-skills`) — discover skills loaded from plugins & user scope
-- `/agents` — list Task-tool subagents loaded by the SDK
-- `/reload-plugins` — re-scan plugin and user directories after edits
-
-Implementation: `src/cli/slash/index.ts` (`registerAll()`), individual command modules under `src/cli/slash/commands/`. Plugin-discovered skills (`~/.afk/plugins/<plugin>/skills/<skill>/SKILL.md` and `~/.afk/skills/<skill>/SKILL.md`) are registered via `src/cli/slash/builtin-skills.ts` and `src/cli/slash/plugin-skills.ts`.
-
-### Runtime features surfaced in the REPL
-
-agent-afk wires several capabilities on top of the provider abstraction:
-
-- **Cross-session memory** — three built-in tools (`memory_search`, `memory_update`, `procedure_write`) backed by SQLite at `~/.afk/agent-framework/memory/`. `HOT.md` is injected into every future session's system prompt for durable essentials. See `src/agent/memory/` and `src/agent/tools/handlers/memory-*.ts`.
-- **`compose` tool — DAG-based orchestration** — agents (and the main session) can dispatch up to 20 subagent nodes with explicit dependency edges. Independent nodes run in parallel; dependent nodes wait. Fail-fast cancels downstream nodes by default. See `src/agent/tools/compose-executor.ts` and `src/agent/dag.ts`.
-- **Background tasks** — Ctrl+B in the REPL detaches the current turn into a tracked background task. `/bg` lists tasks, `/tasks` shows status, `/attach <id>` re-attaches. Status bar at the bottom of the REPL surfaces running task counts. Implementation: `src/cli/background-status-bar.ts`, `src/cli/commands/interactive/background.js`.
-- **`send_telegram` built-in tool** — agents can push terminal-state notifications to the operator. Recipients are gated by `AFK_TELEGRAM_ALLOWED_CHAT_IDS`; safe to attempt unconditionally (returns an error if Telegram is unconfigured). Handler: `src/agent/tools/handlers/send-telegram.ts`.
-- **Extended thinking on by default** — Anthropic's thinking budget is auto-enabled. Override per-session with `--thinking on|off|<budget-tokens>` or globally with `AFK_THINKING`.
-- **`/tokens`** — authoritative breakdown of context usage: total vs model max, auto-compact threshold, top categories, system tools, MCP tools, agents, skills, slash commands, and the last-turn API usage.
-- **Status-line context %** — sampled every few turns from `session.getContextUsage()`, cached between samples, degrades gracefully on transient failures. See `src/cli/context-sampler.ts`.
-- **Progress banners** — when the provider emits `task_progress` events (long subagent runs, multi-tool flows), they render inline as `◦ description (stats)` with an indented summary when present. Telegram forwards the same lines with edit-throttling, and prompt suggestions trail as `💡` lines below the response.
-- **Cost guardrails** — `--max-budget-usd <n>` / `AFK_MAX_BUDGET_USD` aborts on cost breach. `--task-budget <tokens>` / `AFK_TASK_BUDGET` is an advisory per-task hint surfaced to the model.
-- **MCP elicitations** — when an MCP server requests OAuth consent (e.g. Supabase re-auth), the REPL prints the server name, message, and URL, then asks `Continue? [y/N]`. Empty cancels; `n` declines; `y` accepts. Form-mode elicitations are auto-declined in v1. Handler: `src/agent/elicitation-router.ts`.
-- **Clipboard image paste** — paste images directly into the REPL (macOS pasteboard; bracketed-paste-aware). See `src/cli/input/clipboard-image.ts`.
-- **Auto-update check** — startup checks for a newer published version and prints a notice. Suppress with `afk --no-update-check`. Policy field `updatePolicy` (`notify`|`auto`|`off`) lives in `afk.config.json`. Implementation: `src/cli/update-checker.ts`.
-
-## Bypass Permissions Mode
-
-### What is it?
-
-By default, the Claude Agent SDK asks for permission before executing tools like:
-- Running bash commands
-- Reading/writing files
-- Making web requests
-- Etc.
-
-**Agent AFK CLI enables `bypassPermissions: true`** which:
-- ✅ Skips all permission prompts
-- ✅ Allows fully automated workflows
-- ✅ Perfect for CLI/scripting use cases
-- ⚠️ **Requires trust** — Claude has full tool access
-
-### Security Considerations
-
-When bypass mode is enabled:
-- Claude can execute bash commands
-- Claude can read and write files in accessible directories
-- Claude can make web requests
-- Claude can use grep, glob, and other system tools
-
-**Use in trusted environments only.** This mode is designed for:
-- Personal CLI tools
-- Automation scripts
-- Development environments
-- Trusted agent workflows
-
-### Default Allowed Tools
-
-From `src/agent/session/query-options.ts`:
-
-```typescript
-[
-  'Bash',
-  'Read',
-  'Write',
-  'Edit',
-  'Glob',
-  'Grep',
-  'WebSearch',
-  'WebFetch',
-  'LS',
-  'Task',
-  'BashOutput',
-]
-```
-
-Override per-session by passing `config.tools.allowedTools` to `AgentSession`, or disable individual tools via `config.tools.disallowedTools`.
-
-## Development
-
-### Project Structure
-
-```
-agent-afk/
-├── src/
-│   ├── cli/
-│   │   ├── index.ts                # CLI entry (commander)
-│   │   ├── commands/               # chat, interactive, status, config, daemon,
-│   │   │                           # login, plugin, marketplace, doctor,
-│   │   │                           # completion, telegram, etc.
-│   │   ├── slash/                  # REPL slash registry + commands/
-│   │   │                           # (help, plan, todo, bg, tasks, attach,
-│   │   │                           #  init, changelog, builtin-skills, …)
-│   │   ├── input/                  # raw-mode, bracketed paste, clipboard images
-│   │   ├── background-status-bar.ts
-│   │   ├── context-sampler.ts
-│   │   ├── update-checker.ts
-│   │   └── config.ts, shared-helpers.ts
-│   ├── agent/
-│   │   ├── session.ts              # AgentSession barrel
-│   │   ├── session/                # agent-session, query-options, …
-│   │   ├── subagent.ts             # SubagentManager barrel
-│   │   ├── subagent/               # forkSubagent implementation
-│   │   ├── subagent-hooks.ts
-│   │   ├── routing-telemetry.ts    # appends routing-decisions.jsonl
-│   │   ├── daemon/                 # long-running headless agent
-│   │   ├── plugins/                # afk plugin install / update / remove
-│   │   ├── marketplaces/           # marketplace install / resolve / manifest
-│   │   ├── providers/              # anthropic-direct, openai-codex
-│   │   ├── memory/                 # cross-session memory + HOT.md loader
-│   │   ├── tools/                  # built-in tool dispatcher + handlers
-│   │   │                           # (compose, subagent, skills, memory_*,
-│   │   │                           #  send_telegram, …)
-│   │   ├── elicitation-router.ts
-│   │   ├── hook-registry.ts, hooks.ts, default-hook-registry.ts
-│   │   ├── permissions.ts, abort-graph.ts, dag.ts, message-queue.ts
-│   │   ├── output-extractor.ts, plugins-scanner.ts, timeout.ts
-│   │   ├── shadow-verify-nudge.ts
-│   │   └── types.ts, types/
-│   ├── skills/
-│   │   ├── all.ts                  # canonical skill registry
-│   │   ├── mint/                   # /mint
-│   │   ├── diagnose/               # /diagnose
-│   │   ├── forge/                  # /forge (gate-check inlined)
-│   │   ├── audit-fit/              # /audit-fit
-│   │   ├── _agents/                # vendored subagents (qualify,
-│   │   │                           #  research-agent, contract)
-│   │   ├── _lib/                   # prompt-loader, shared helpers
-│   │   ├── example-template/       # scaffold for new skills
-│   │   └── user-skills.ts          # lazy scan of ~/.afk/skills + project skills
-│   ├── telemetry/                  # shared telemetry schemas
-│   ├── telegram/                   # telegram bridge (setup wizard, push, etc.)
-│   ├── telegram.ts                 # telegram bot entry
-│   ├── utils/
-│   ├── paths.ts
-│   └── index.ts
-├── tests/
-│   ├── agent/                      # cross-cutting integration suites
-│   └── telegram/                   # telegram bridge tests
-├── scripts/
-│   ├── copy-prompts.js             # bundles src/**/*.md into dist/ after tsc
-│   ├── build-dist.mjs              # esbuild release bundle
-│   ├── release.mjs                 # version bump + publish flow
-│   ├── generate-changelog.mjs
-│   ├── audit-sdk-dependency.ts     # (not yet wired into package.json)
-│   ├── colocate-tests.mjs
-│   ├── telegram-manager.sh
-│   └── verify-install.sh
-├── docs/                           # design notes, audits, failure geometry
-├── landing/                        # marketing site assets
-├── AGENTS.md
-├── CHANGELOG.md
-├── CLAUDE.md
-├── CONTRIBUTING.md
-├── afk.config.json.example
-├── verify.sh
-├── pnpm-lock.yaml
-├── package.json
-├── tsconfig.json
-├── vitest.config.ts
-└── README.md
-```
-
-### Build Process
+Minimum viable config is one env var:
 
 ```bash
-pnpm clean && pnpm build    # full clean rebuild
-pnpm dev                    # auto-rebuild (tsx watch)
-pnpm lint                   # type-check without emitting
+ANTHROPIC_API_KEY=sk-ant-...
 ```
 
-`pnpm build` runs `tsc` and then `scripts/copy-prompts.js`, which copies every `src/**/*.md` file into `dist/` at matching relative paths. Skills read their prompts via `readFileSync` at import time, so those markdown files must live next to the compiled `.js` output.
-
-### Testing
+Optional, in order of usefulness:
 
 ```bash
-pnpm test                   # all (vitest run)
-pnpm test:coverage          # with coverage
-pnpm test:watch             # watch mode
-pnpm test:integration       # vitest run tests/integration  (dir not yet populated)
-pnpm test:e2e               # vitest run tests/e2e          (dir not yet populated)
-```
+# Pick a model — opus | sonnet | haiku (Anthropic) or codex (OpenAI)
+AFK_MODEL=sonnet
 
-Tests are colocated as `*.test.ts` next to the implementation under `src/`, plus cross-cutting suites under `tests/agent/` and `tests/telegram/`.
-
-## Troubleshooting
-
-### API Key Issues
-
-**Error: `invalid x-api-key`**
-
-Your API key is invalid or expired. Get a new one at [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys).
+# Enable the Telegram bot + send_telegram tool
+TELEGRAM_BOT_TOKEN=1234567890:ABC...
+AFK_TELEGRAM_ALLOWED_CHAT_IDS=12345678
 
-```bash
-# Test your API key
-node -e "
-import('@anthropic-ai/sdk').then(async (Anthropic) => {
-  const dotenv = await import('dotenv');
-  dotenv.config();
-  const client = new Anthropic.default({ apiKey: process.env.ANTHROPIC_API_KEY });
-  const message = await client.messages.create({
-    max_tokens: 10,
-    messages: [{ role: 'user', content: 'Hi' }],
-    model: 'claude-3-5-sonnet-20241022',
-  });
-  console.log('✓ API Key works!');
-}).catch(e => console.error('✗ API Key error:', e.message));
-"
+# Per-task safety rails
+AFK_MAX_BUDGET_USD=5.00
 ```
 
-**Error: `ANTHROPIC_API_KEY not found`**
+**Project-scoped system prompt.** Drop an `AFK.md` at your project root and `afk` reads it as the system prompt whenever you run from that directory. No frontmatter needed.
 
-Check that:
-1. `.env` file exists in project root
-2. Contains `ANTHROPIC_API_KEY=sk-ant-...`
-3. No quotes around the key value
-4. No trailing spaces
+**Check what resolved.** `afk config` dumps the live configuration. `afk doctor` validates keys, paths, and provider connectivity.
 
-### Build Issues
+## Models
 
-**TypeScript errors:**
+Default is `sonnet`. Override per-call with `--model`:
 
 ```bash
-pnpm clean
-rm -rf node_modules
-pnpm install
-pnpm build
+afk chat "explain this stack trace" --model opus
+afk i --model haiku
+afk chat "refactor this" --model codex
 ```
 
-**Module not found:**
-
-```bash
-pnpm build
-```
-
-### Runtime Issues
-
-**`Cannot send message: session is closed`** — the session was closed or timed out. Create a new one.
+| Model | Best for |
+|---|---|
+| `opus` | Complex reasoning, multi-step planning, long contexts |
+| `sonnet` | Day-to-day default — balanced speed and capability |
+| `haiku` | Fast, cheap, one-shots |
+| `codex` | OpenAI's GPT-5 family via `@openai/codex-sdk` |
 
-**Timeout errors** — increase max turns:
+## Useful commands
 
 ```bash
-pnpm start -- chat "complex task" --max-turns 50
+afk status               # connection, model, bypass-mode state
+afk doctor               # environment self-check
+afk config               # dump resolved config
+afk plugin list          # installed plugins under ~/.afk/plugins/
+afk completion zsh       # shell completion (also: bash, fish)
+afk --help               # full command tree
 ```
 
-**`Maximum turns exceeded`** — the conversation hit the turn limit (a safety feature). Raise `--max-turns` if needed.
-
-## API Reference
+Aliases: `afk c` → `chat`, `afk i` → `interactive`, `afk s` → `status`.
 
-### AgentSession
+## A note on permissions
 
-```typescript
-import { AgentSession } from './agent/session.js';
+`afk` runs with **bypass permissions** by default: no per-tool prompts. Claude can run bash, read and write files, fetch URLs, and call MCP servers without asking each time. This is intentional — `afk` is built for unattended work, where a permission prompt with no human in front of it is just a wedged session.
 
-const session = new AgentSession({
-  model: 'sonnet',
-  apiKey: process.env.ANTHROPIC_API_KEY!,
-  maxTurns: 100,
-  systemPrompt: 'You are a helpful assistant.',
-  tools: {
-    allowedTools: ['Bash', 'Read', 'Write'],
-  },
-});
+Use `afk` on a machine and account you trust. Override per-session with `--permission-mode` if you want stricter behavior.
 
-// Single message
-const response = await session.sendMessage('Hello!');
-console.log(response.content);
-
-// Streaming (async iterator)
-for await (const event of session.sendMessageStream('Tell me a story')) {
-  process.stdout.write(event.text ?? '');
-}
-
-// Runtime control
-await session.interrupt();                       // cancel in-flight turn
-await session.setModel('opus');                  // hot-swap model
-await session.setPermissionMode('acceptEdits');  // switch permission mode
+## Troubleshooting
 
-// State accessors
-session.state;                    // 'idle' | 'processing' | 'streaming' | 'closed'
-session.sessionId;                // string | undefined
-session.abortSignal;              // AbortSignal
-const history = session.getHistory();
+**`invalid x-api-key` / `ANTHROPIC_API_KEY not found`** — run `afk doctor`. Confirm the key is set in your shell or in `~/.afk/config/afk.env`.
 
-// Cleanup
-await session.close();
-```
+**`Cannot send message: session is closed`** — the session timed out or was closed. Start a new one (`afk i` or a fresh `afk chat`).
 
-### Types
-
-```typescript
-interface AgentConfig {
-  model: 'opus' | 'sonnet' | 'haiku';
-  apiKey: string;
-  maxTurns?: number;
-  systemPrompt?: string;
-  tools?: {
-    allowedTools?: string[];
-    disallowedTools?: string[];
-  };
-}
-
-interface Message {
-  role: 'user' | 'assistant';
-  content: string;
-  timestamp?: Date;
-}
-
-type SessionState = 'idle' | 'processing' | 'streaming' | 'closed';
-```
+**`Maximum turns exceeded`** — safety rail tripped. Bump it with `--max-turns 50` or higher.
 
-## Contributing
+**Hit the budget cap** — raise `AFK_MAX_BUDGET_USD` or unset it for the session.
 
-Contributions welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md) for repo conventions. Standard flow:
+**Telegram bot won't start** — `afk telegram status` then `afk telegram logs`. Most common cause: missing `AFK_TELEGRAM_ALLOWED_CHAT_IDS` after token setup.
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes (add or update tests alongside)
-4. Run `pnpm test && pnpm lint`
-5. Open a pull request
+## Changelog
 
-New orchestration skills, CI gate changes, and ceiling-ledger conventions are documented in [`AGENTS.md`](AGENTS.md). A change log is maintained in [`CHANGELOG.md`](CHANGELOG.md) (also viewable in-REPL via `/changelog`).
+Recent releases at [`CHANGELOG.md`](CHANGELOG.md), also viewable in-REPL via `/changelog`.
 
 ## License
 
-MIT © Griffin Long
-
-## Acknowledgments
-
-- Anthropic API client: [@anthropic-ai/sdk](https://www.npmjs.com/package/@anthropic-ai/sdk)
-- OpenAI Codex client: [@openai/codex-sdk](https://www.npmjs.com/package/@openai/codex-sdk)
-- CLI framework: [Commander.js](https://github.com/tj/commander.js)
-- Telegram: [Telegraf](https://telegraf.js.org/)
-- Testing: [Vitest](https://vitest.dev/)
-
----
+Proprietary. © Griffin Long. All rights reserved.
 
-**Note:** This tool uses bypass permissions mode. Only use in trusted environments where you're comfortable giving Claude full tool access.
+The `agent-afk` package on npm is provided as-is for use; the source is not licensed for redistribution, modification, or derivative works. See [`LICENSE`](LICENSE).