AFK

AFK = Away From Keyboard — Autonomous development workflow CLI + Skills system

Cross-platform issue tracking automation (GitLab/GitHub) powered by Claude AI agents and TypeScript.

Architecture

AFK Architecture

Features

Cross-platform — Unified GitLab and GitHub CLI (issues, MRs/PRs)
Skills Suite — 24 Claude Code skills covering the full development lifecycle
TUI Dashboard — Interactive issue tracking dashboard
Background Automation — tmux-based workflow scheduler
TDD Integration — Built-in test-driven development methodology

Quick Start

git clone https://github.com/easyhaloo/afk.git
cd afk
pnpm install && pnpm build
pnpm --dir apps/cli link --global
afk --version

See Getting Started Guide for detailed setup.

Install Claude Code Plugin (Optional)

AFK provides a full Claude Code skill suite that can be integrated as a plugin.

Method 1: In Claude Code Session (Recommended)

Use the slash command directly in Claude Code:

/plugin install afk@afk

Method 2: Using CLI

# Add marketplace
claude plugin marketplace add easyhaloo/afk --scope user

# Install plugin
claude plugin install afk@afk

Method 3: settings.json Configuration

Add to Claude Code's settings.json (global or project-level .claude/settings.json):

{
  "extraKnownMarketplaces": {
    "afk": {
      "source": {
        "source": "github",
        "repo": "easyhaloo/afk"
      }
    }
  }
}

Supported source types:

"github" — Load from GitHub repository
"local" — Load from local filesystem

Method 4: Symlink Skills

Link the skills/ directory to the global skills directory:

mkdir -p ~/.claude/skills
ln -s /path/to/afk/skills/* ~/.claude/skills/

Verify Installation

Run /afk-grill-me in Claude Code to confirm skills are loaded.

CLI Commands

# Backlog Management
afk backlog show --id <id>
afk backlog list --state ready --mode afk
afk backlog create "Title" --description-file ./description.md --tag feature
afk backlog tag add --id <id> --tag bug
afk backlog tag remove --id <id> --tag bug

# Execution & Automation
afk                                  # Interactive TUI panel
afk kanban                           # Kanban board
afk execute --work-item-id github:owner/repo#123 --execution-manifest <path>  # Managed work item: implement → QA → PR
afk observe executions --work-item-id github:owner/repo#123 --json
afk run --backlog-id <id>            # Lower-level implementation-only entry
afk run --backlog-id <id> --project <repo>
afk qa --backlog-id <id>             # Standalone QA
afk loop start --daemon --backlog-id <id> --work-item-id github:owner/repo#123 --execution-manifest <path>

# Infrastructure
afk tmux create-session --name <name> --dir <path>
afk isolate up

# Debug
afk debug reproduce <cmd>

# Signal Management
afk signal goal-complete --summary "<summary>"

Full command reference: afk --help

Skills (Claude Code)

Skill	Purpose	When to Use
`/afk-grill-me`	Requirements interview	Ambiguous requirements or likely gaps
`/afk-grill-me-context`	Gap-fill interview	Existing drafts/docs need verification
`/afk-to-prd`	Generate PRD	After requirements alignment
`/afk-to-issues`	Decompose to issues	After PRD approved
`/afk-do`	Task orchestration	Clear feature or task description
`/afk-research`	Technical research	Need to understand existing implementation before coding
`/afk-prototype`	Validate approach	Need to validate tech approach before committing
`/afk-implement`	TDD implementation	Clear implementation target
`/afk-change-driven-testing`	Change-driven testing	Add focused regression tests for the business flow being changed
`/afk-qa`	Independent verification	MR/PR ready to merge
`/afk-diagnose`	Quick fix	Specific, reproducible failure
`/afk-branch-migrate`	Cross-branch migration	Cherry-pick between divergent branches
`/afk-hand-off`	Work handoff	Transfer task to another developer
`/afk-scheduler`	Background scheduling	Multiple issues with dependency-aware execution
`/afk-skill-craft`	Skill authoring	Create, diagnose, or refactor skills
`/api-workflow`	API testing	Multi-step API chains with browser testing
`/md-to-pdf`	Markdown to PDF	Export docs with Mermaid diagrams
`/reasoning-guard`	Reasoning guard	Multi-turn reasoning degradation in coding agents
`/reasoning-watchdog`	Auto reasoning monitor	Hooks-based automatic reasoning degradation interception
`/afk-ai-prd`	AI-friendly PRD	PRD that an AI can parse, decompose, and verify
`/afk-llm-dev-guide`	LLM app design guide	LLM application architecture and context engineering
`/jev-agent-guard`	Agent checkpoints	Install Jev checkpoints across Claude Code, Codex, OpenCode
`/software-complexity-governance`	Complexity assessment	Measure cyclomatic/cognitive complexity, coupling, debt
`/wiki`	Local knowledge management	Search, read, ingest, and lint project knowledge

See Skills Guide for detailed documentation.

Architecture

AFK uses TrackerProvider interface to abstract GitLab and GitHub differences:

interface TrackerProvider {
  getIssue(id: number): Promise<TrackedIssue>;
  createMR(options: CreateMROptions): Promise<number>;
  mergeMR(id: number, options?: MergeMROptions): Promise<void>;
  // ... more operations
}

Platform auto-detected, no command switching needed. See Architecture Design and Execution Environment Design.

Workflows

Three core workflow patterns:

Issue → Implementation → MR Pipeline — From issue discovery to merge request
Scheduler Workflow — Background dependency-aware execution
Skills Workflow — TDD methodology integration

See Workflow Documentation.

Development

pnpm install
pnpm build                         # Build shared packages and CLI
pnpm test                          # Test shared packages and CLI
pnpm --dir apps/desktop test        # Test Desktop
pnpm --dir apps/cli link --global   # Install CLI globally

Documentation

Getting Started — 5-minute AFK setup
Architecture Design — Cross-platform abstraction + CLI command mapping
Workflows — Issue → MR pipeline, scheduler, Skills integration
Skills Guide — Core skills design and usage
Agent Plugins Compatibility — Portable Agent Plugins v1 package format

License

MIT