{"id":50628824,"url":"https://github.com/griffinwork40/agent-afk","last_synced_at":"2026-07-04T01:04:36.512Z","repository":{"id":362737697,"uuid":"1260291990","full_name":"griffinwork40/agent-afk","owner":"griffinwork40","description":"Local-first CLI for running, supervising, and resuming coding agents across terminal and chat surfaces. Apache-2.0.","archived":false,"fork":false,"pushed_at":"2026-06-10T21:55:16.000Z","size":4199,"stargazers_count":10,"open_issues_count":20,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T23:22:19.283Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/griffinwork40.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-05T10:42:23.000Z","updated_at":"2026-06-10T21:55:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/griffinwork40/agent-afk","commit_stats":null,"previous_names":["griffinwork40/agent-afk"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/griffinwork40/agent-afk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/griffinwork40%2Fagent-afk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/griffinwork40%2Fagent-afk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/griffinwork40%2Fagent-afk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/griffinwork40%2Fagent-afk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/griffinwork40","download_url":"https://codeload.github.com/griffinwork40/agent-afk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/griffinwork40%2Fagent-afk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34222709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-06T19:00:43.593Z","updated_at":"2026-07-04T01:04:36.505Z","avatar_url":"https://github.com/griffinwork40.png","language":"TypeScript","funding_links":[],"categories":["Harnesses \u0026 orchestration"],"sub_categories":["Session managers \u0026 parallel runners"],"readme":"# Agent AFK\n\n\u003e **Claude Code decides how the agent behaves. Agent AFK lets you edit the rules.**\n\n**Agent AFK** is an open-source coding-agent harness you can actually change. Run long coding tasks while you're away, use any model, and edit the rules that decide what the agent can touch, when it stops, and how it proves the work.\n\n\u003e Agent AFK isn't \"smarter than Claude Code.\" It's *yours* in a way Claude Code can't be.\n\n[![npm version](https://img.shields.io/npm/v/agent-afk.svg)](https://www.npmjs.com/package/agent-afk)\n[![CI](https://github.com/griffinwork40/agent-afk/actions/workflows/ci.yml/badge.svg)](https://github.com/griffinwork40/agent-afk/actions/workflows/ci.yml)\n[![Node](https://img.shields.io/node/v/agent-afk.svg)](https://nodejs.org/)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/griffinwork40/agent-afk?style=social)](https://github.com/griffinwork40/agent-afk/stargazers)\n\n\u003c!-- DEMO GIF GOES HERE ▸ drop a 20–30s screen recording of one autonomous AFK run (e.g. kick off `afk daemon` / `afk mint \"...\"`, walk away, get the Telegram ping, come back done). Drag-and-drop the file into a GitHub issue/PR to host it on GitHub's CDN, then paste the URL as ![demo](URL) right here. This is the single biggest star-conversion lever — keep it above the fold. --\u003e\n\n\u003e ⭐ **Like the idea of an agent loop you fully own? [Star the repo](https://github.com/griffinwork40/agent-afk/stargazers)** — it's the fastest way to help other people find it.\n\n## Claude Code vs. Agent AFK\n\n| | Claude Code | Agent AFK |\n|---|---|---|\n| Harness | Closed binary | Apache-2.0, editable |\n| The loop | You configure *around* it | You edit *the loop* |\n| Behavior | Mostly fixed | Prompts, gates, routing, skills are code |\n| Result | A great default agent | An agent system you own |\n\nThe model isn't the product — the loop is. Agent AFK hands you the loop as code: prompts, gates, routing, skills, traces, providers, terminal states. Edit any of them.\n\n## Install\n\n```bash\nnpm install -g agent-afk\n```\n\nRequires Node ≥ 22.\n\nSmoke test:\n\n```bash\nafk --version    # confirm the install (works before login)\nafk doctor       # environment self-check\nafk chat \"hello\"\n```\n\n**Already using Claude Code or Codex?** Run `afk migrate` — it imports your existing plugins, skills, and MCP servers. It doesn't copy files; it live-reads the source tool's dirs, so anything you install there keeps showing up in AFK with no re-run.\n\n## What you can do with it\n\n- **Chat from your terminal** — `afk chat \"...\"` for one-shot, `afk` for a REPL with full tool access (Bash, file ops, web fetch, grep/glob, subagents).\n- **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.\n- **Read the trace** — every run writes an append-only record of what the agent did. `afk trace show` prints it back as a human-readable receipt — tool calls, gate decisions, subagent lifecycles, cost — so you can audit a run without reaching for `jq`.\n- **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.\n- **Built-in orchestrators** — `/mint`, `/diagnose`, `/spec`, `/research`, `/ship`, `/review` 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.\n\n\u003e **Agent AFK Pro:** Autonomous skill-generation (`/forge`) and the calibrated skill-qualification rubric (`/qualify`) are reserved for Agent AFK Pro and are not part of the open-source build.\n- **Cross-session memory** — Claude remembers preferences, decisions, and procedures across runs. See [Memory](#memory) below.\n- **Background subagent jobs** — dispatch a subagent with `mode:'background'`; results auto-deliver into the model's context when they finish. `/bgsub` lists running and completed jobs, `/bgsub:join \u003cid\u003e` replays a result manually.\n\n## Four surfaces, one session manager\n\n| Command | Surface |\n|---|---|\n| `afk chat \"...\"` | One-shot (fire \u0026 forget) turn — pipe-friendly, scripts well |\n| `afk` (alias of `afk interactive`) | REPL with slash commands, streaming, plan mode, image paste |\n| `afk daemon` | Long-running headless agent, cron-friendly |\n| `afk telegram start` | Telegram bot — same tools, same memory, on your phone |\n\n## Configuration\n\n`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.\n\n**Local-first, no phone-home.** There is no analytics or remote telemetry — Agent AFK never sends your prompts, code, or usage anywhere except directly to the model provider you configure. What telemetry exists is local JSONL under `~/.afk/` that you can read or delete.\n\nOptional, in order of usefulness:\n\n```bash\n# Pick a model — opus | sonnet | haiku | fable (Anthropic) or codex (OpenAI)\nAFK_MODEL=sonnet\n\n# Enable the Telegram bot + send_telegram tool\nTELEGRAM_BOT_TOKEN=1234567890:ABC...\nAFK_TELEGRAM_ALLOWED_CHAT_IDS=12345678\n\n# Per-task safety rails\nAFK_MAX_BUDGET_USD=5.00\n```\n\n**Project-scoped system prompt.** Drop an `AFK.md` at your project root and `afk` appends it to its built-in framework prompt whenever you run from that directory — your instructions layer on top of the base, they don't replace it. No frontmatter needed.\n\n**Check what resolved.** `afk config` dumps the live configuration. `afk doctor` validates keys, paths, and provider connectivity.\n\n## Memory\n\nClaude remembers things across sessions — preferences, decisions, conventions, and reusable procedures — without any manual setup. Memory is local-only and stored under `~/.afk/state/memory/`.\n\n**Two storage tiers:**\n\n- **Hot memory** (`~/.afk/state/memory/HOT.md`) — a small markdown file (≤ ~1,500 tokens) injected into every future session's system prompt automatically. Use it for the facts you want Claude to always carry: your name, working style, standing instructions. Capped at 5,250 characters; overflow is truncated with a sentinel comment.\n- **Fact archive** (`~/.afk/state/memory/memory.db`) — an unbounded SQLite store, full-text-searchable via FTS5. Facts are queried on demand with the `memory_search` tool; they don't bloat every prompt.\n\n**Fact categories** (set when writing to the archive):\n\n| Category | What to put here |\n|---|---|\n| `preference` | Working style, formatting, tool choices |\n| `convention` | Naming rules, file layout, team norms |\n| `decision` | Architecture choices and the reasoning behind them |\n| `learning` | Bugs found, lessons from past runs |\n\n**Tools available inside a session:**\n\n- `memory_search` — full-text search across facts and procedures (supports FTS5: `AND`, `OR`, `NOT`, `\"exact phrase\"`, `prefix*`).\n- `memory_update` — write or supersede a fact in the archive (`target: \"fact\"`) or overwrite hot memory (`target: \"hot\"`).\n- `procedure_write` — save a reusable step-by-step workflow as a named markdown file under `~/.afk/state/memory/procedures/`. Procedures are searchable via `memory_search`.\n\nHot memory is injected at session start; `memory_search` is called explicitly during a run. The session-end hook logs each completed top-level session to the archive automatically — subagent sessions are excluded.\n\nAll four surfaces (REPL, chat, daemon, Telegram) share the same store — memory written in one surface is available everywhere.\n\n## Models\n\nDefault is `sonnet`. Override per-call with `--model`:\n\n```bash\nafk chat \"explain this stack trace\" --model opus_1m\nafk --model sonnet_1m\nafk chat \"refactor this\" --model gpt-5.5\n```\n\n| Model | Best for |\n|---|---|\n| `fable` | Most capable — Claude Fable 5 (Mythos-class), hardest reasoning + long-horizon agentic work (1M context) |\n| `opus` | Complex reasoning, multi-step planning, long contexts |\n| `sonnet` | Day-to-day default — balanced speed and capability |\n| `haiku` | Fast, cheap, meh... |\n\n**Model slots** — rebind any capability tier to any model:\n\n| Slot | Default | Notes |\n|---|---|---|\n| `local` | *(empty — you configure)* | Point at Ollama, LM Studio, or any OpenAI-compatible shim via `AFK_MODEL_LOCAL` + `AFK_MODEL_LOCAL_BASE_URL` |\n| `small` | `claude-haiku-4-5-20251001` | Cheapest/fastest Anthropic tier; `haiku` alias |\n| `medium` | `claude-sonnet-5` | General-use default; `sonnet` alias |\n| `large` | `claude-opus-4-8` | Most capable; `opus` alias |\n\nSee [`docs/model-slots.md`](docs/model-slots.md) for the full configuration reference.\n\nMCP servers (tool-providing plugins over stdio/HTTP) — see [`docs/mcp.md`](docs/mcp.md) for config, transports, OAuth, and security notes.\n\n## Useful commands\n\n```bash\nafk status               # connection, model, bypass-mode state\nafk doctor               # environment self-check\nafk config               # dump resolved config\nafk plugin list          # installed plugins under ~/.afk/plugins/\nafk completion zsh       # shell completion (also: bash, fish)\nafk --help               # full command tree\n```\n\nAliases: `afk c` → `chat`, `afk i` → `interactive`, `afk s` → `status`.\n\n### Queue management\n\n`afk queue` manages the pull-trigger daemon's task queue — tasks are persisted as JSON files and consumed one-by-one by `afk daemon --trigger pull`.\n\n```bash\nafk queue add \"/forge-friction --auto\" --notify-on failure\n                         # enqueue a command; daemon picks it up on next poll\nafk queue list           # print all pending tasks (id, enqueued time, command)\nafk queue remove \u003cid\u003e    # drop a single pending task by id\nafk queue clear          # remove all pending tasks (prompts for confirmation)\nafk queue clear --yes    # clear without prompting (CI / non-interactive)\n```\n\n### Self-improvement pipeline\n\n`afk improve` is a zero-LLM, deterministic pipeline that mines `~/.afk/state/witness/` session traces for ranked failure patterns, without making any model calls.\n\n```bash\n# Scan traces for failure patterns (dry-run; add --write to persist cards)\nafk improve scan [--since 7d] [--write] [--only \u003cdetector,...\u003e]\n\n# Inspect failure cards\nafk improve cards list [--pattern \u003cname\u003e] [--severity \u003clevel\u003e] [--status open|deferred|resolved]\nafk improve cards show \u003cslug\u003e\nafk improve cards triage \u003cslug\u003e --note \"...\" [--status resolved]\n\n# Draft a template-mode improvement proposal for a card (no LLM)\nafk improve propose \u003cslug\u003e [--no-write]\n\n# Generate a replay-mode eval-case from a failure card\nafk improve eval-gen \u003ccardSlug\u003e [--evidence-row \u003ci\u003e] [--no-write]\n\n# Run the deterministic guardrail contract for an eval-case\nafk improve eval-run \u003cevalCaseIdOrCardSlug\u003e [--no-write]\n```\n\nAvailable detectors (run `afk improve scan --help` for thresholds): `repeated-tool-use`, `subagent-block`, `closure-anomaly`, `tool-failure-density`.\n\n### Speculative branch farm\n\n`afk farm` spawns N isolated git worktrees, runs an agent on each in parallel, scores the results (tests + lint + LoC delta), and prints a ranked summary.\n\n```bash\nafk farm \"add retry logic to the queue consumer\" --branches 3\nafk farm \"\u003ctask\u003e\" -n 5 --model sonnet --fail-fast\nafk farm \"\u003ctask\u003e\" -n 3 --no-score    # skip post-run scoring\nafk farm \"\u003ctask\u003e\" -n 3 --labels \"approach-a,approach-b,approach-c\"\nafk farm \"\u003ctask\u003e\" -n 3 --no-memory --no-digest  # skip memory write + Telegram\n```\n\nEach branch gets a dedicated worktree under `~/.afk/state/farm/`. A commit-count escape check confirms each agent did real work. On completion, the winner (branch that passes tests and makes the smallest net change) is surfaced; the rest are left for manual cherry-pick or deletion.\n\n## A note on permissions\n\n`afk` does not prompt before each tool call — there is no per-tool approval flow. Claude runs bash, reads and writes files, fetches URLs, and calls 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.\n\n**New installs default to bypass mode.** `afk chat` and `afk interactive` start in `permissionMode: \"bypassPermissions\"` when `afk.config.json` sets none — the agent reads and writes **anywhere** with no path-approval prompt. This is the equivalent of Claude Code's `--dangerously-skip-permissions`, on by default; use `afk` only on a machine and account you trust. Bypass does not change `ask_question` — that is the model choosing to ask you something, a separate axis.\n\n**To re-enable path containment**, set the mode back any of these ways:\n\n- Persistently: `afk config set permissionMode default` (or `plan`), or `\"permissionMode\": \"default\"` in `afk.config.json`. It stays that way until you change it again.\n- For one session: `/bypass off` in the REPL (the status line clears `⚡ bypass`).\n\nWith containment on (`default`), a file tool (read/write/edit/list/glob/grep) targeting a path *outside* the session's working directory triggers a **path-approval** prompt; pre-authorize paths with `/allow-dir \u003cpath\u003e` (or answer \"persist\" at the prompt to remember them across sessions). Toggle bypass live anytime with `/bypass`. `afk daemon` always runs in bypass (no human to prompt); **Telegram** sessions stay contained (`default`) and rely on hook-based enforcement.\n\n## Troubleshooting\n\n**`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`.\n\n**`Cannot send message: session is closed`** — the session timed out or was closed. Start a new one (`afk i` or a fresh `afk chat`).\n\n**`Maximum turns exceeded`** — safety rail tripped. Bump it with `--max-turns 50` or higher.\n\n**Hit the budget cap** — raise `AFK_MAX_BUDGET_USD` or unset it for the session.\n\n**Telegram bot won't start** — `afk telegram status` then `afk telegram logs`. Most common cause: missing `AFK_TELEGRAM_ALLOWED_CHAT_IDS` after token setup.\n\n## Changelog\n\nRecent releases at [`CHANGELOG.md`](CHANGELOG.md), also viewable in-REPL via `/changelog`.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=griffinwork40/agent-afk\u0026type=Date)](https://star-history.com/#griffinwork40/agent-afk\u0026Date)\n\nIf Agent AFK saves you time, **[⭐ star the repo](https://github.com/griffinwork40/agent-afk/stargazers)** — it's the single best way to help it reach more people.\n\n## License\n\nAgent AFK is **open core**, licensed under **[Apache-2.0](LICENSE)** (SPDX: `Apache-2.0`).\nUse it, modify it, fork it, embed it in commercial or closed-source products — the\nstandard Apache conditions apply (keep the license and [`NOTICE`](NOTICE), note\nsignificant changes, and don't use the \"Agent AFK\" name or marks to imply\nendorsement). No copyleft, no CLA.\n\n**Pro \u0026 Team add-ons** (premium skill packs, team features, priority support) are\nseparate commercial products under their own terms — see [`LICENSING.md`](LICENSING.md).\nThe core harness is, and will stay, free and open.\n\nContributions are accepted under the [DCO](https://developercertificate.org/)\n(`git commit -s`). \"Agent AFK\" is a trademark of Griffin Long. © Griffin Long.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgriffinwork40%2Fagent-afk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgriffinwork40%2Fagent-afk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgriffinwork40%2Fagent-afk/lists"}