Let the AI work while you're away from the keyboard!

A tool-agnostic CLI for autonomous AI-driven software development. afk runs your AI coding tasks in a loop, spawning a fresh agent instance for each iteration - so context never overflows and the AI stays sharp.

AI coding agents are powerful, but they have a fatal flaw: context window exhaustion. The longer an AI works on a problem, the more context it accumulates - past attempts, dead ends, outdated information. Eventually, it becomes bloated and confused, making worse decisions the longer it runs.

afk solves this with the Ralph Wiggum pattern - a kanban-style approach where each task gets a fresh AI instance with clean context. Think of it like a well-organised team: each developer picks up one ticket, completes it, and moves on. No cognitive overload. No stale context.

The result? AI that can work autonomously for hours without degrading.

The technique is named after Ralph Wiggum from The Simpsons - a character who approaches each moment with fresh-eyed obliviousness, unburdened by what came before.

In AI terms, it works like this:

1. Fresh start every iteration - Each loop spawns a brand new AI instance
2. One task at a time - Kanban-style: pick up a task, complete it, move on
3. Memory through files, not context - Progress persists via git commits, not the AI's memory

This means the AI never runs out of context, never gets confused by old attempts, and can work indefinitely without degradation.

• 📝 Git history - Commits from previous iterations
• 📋 progress.json - Task status and per-task learnings (short-term memory)
• 📖 AGENTS.md - Project-wide conventions and patterns (long-term memory)

• 📰 The Ralph Wiggum Technique by Geoffrey Huntley (the originator)
• 🔧 snarktank/ralph by Ryan Carson (inspiration)
• 📚 Effective harnesses for long-running agents by Anthropic

Create a requirements document describing what you want to build. This can be high-level or as detailed as you'd like. You don't need to break it down into granular tasks yourself:

# Weather Dashboard

A simple web app that shows current weather for a given city.

Users should be able to enter a city name and see the temperature, conditions, and a 5-day forecast. Use the OpenWeather API.
The UI should be clean and mobile-friendly.

afk import requirements.md

This runs your AI CLI to analyse the PRD and break it down into small, AI-sized tasks. The output goes to .afk/tasks.json.

afk tasks     # Review the tasks it generated
afk go        # Start the autonomous loop

That's it. afk works through the tasks one by one, committing as it goes.

If you've already got tasks in a structured format, skip the import:

afk go TODO.md           # Markdown with checkboxes: - [ ] Task name
afk go tasks.json        # JSON with `afk-`style tasks array
afk go 20                # Run 20 iterations
afk go -u                # Run until all tasks complete

Note: These expect task lists, not raw PRDs. Use afk import to parse requirements into tasks.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/m0nkmaster/afk/main/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/m0nkmaster/afk/main/scripts/install.ps1 | iex

Installs a standalone binary - no dependencies required. Updates with afk update.

git clone https://github.com/m0nkmaster/afk.git && cd afk
cargo build --release
# Binary at target/release/afk

cargo install --git https://github.com/m0nkmaster/afk

GitHub source: Requires the GitHub CLI (gh) to be installed and authenticated. Fetches open issues and converts them to tasks. Priority is inferred from labels (P0/critical → 0, P1/high → 1, etc.).

OpenSpec source: Reads tasks from OpenSpec change proposals in openspec/changes/<change-id>/tasks.md. Enriches task context with spec deltas, proposals, and design docs.

Gherkin source: Parses .feature files (Given/When/Then). Each Scenario becomes a task with steps as acceptance criteria. Supports single files or directories.

Tip: When you switch git branches, afk go detects the change and prompts to archive the previous session automatically.

afk works with any CLI that accepts prompts as the final argument:

On first run, afk go auto-detects installed CLIs and prompts you to select one.

Each task must complete in a single AI context window. Tasks that are too large cause context overflow and poor code quality.

Right-sized ✓

• Add a database column
• Create a UI component
• Write tests for a module
• Fix a specific bug

Too large ✗

• "Build the dashboard"
• "Add authentication"
• "Refactor the API"

When in doubt, split. Five small tasks are better than one large task.

Each iteration:

1. Load tasks from configured sources (json, markdown, beads, github, openspec, gherkin)
2. Check completion — if all tasks done, exit
3. Generate prompt with next task, context files, and session learnings
4. Spawn fresh AI — a brand new CLI instance with clean context
5. AI works autonomously:
   • Implements the task
   • Runs afk verify (quality gates: lint, test, typecheck)
   • Fixes issues until verify passes
   • Commits changes
   • Marks task complete in .afk/tasks.json
   • Records learnings
6. Loop — repeat from step 1

The key point: afk is an orchestrator, not an AI itself. It spawns your chosen AI CLI, gives it a task, and lets it work. Each iteration gets a fresh instance that reads state from files, does the work, and writes state back. No context accumulation, no degradation.

• docs/user-guide.md - Complete command reference and workflow examples
• docs/architecture.md - Technical overview for contributors
• CONTRIBUTING.md - How to contribute

• Ralph Wiggum pattern by Geoffrey Huntley
• snarktank/ralph by Ryan Carson
• Effective harnesses for long-running agents by Anthropic
• Beads by Steve Yegge

MIT