@flower-f/afk-cli

Command-line AFK development workflow runner for coding agents.

Install

pnpm add -g @flower-f/afk-cli

Quick start

afk config setup
afk init
afk

afk config setup writes user defaults to ~/.config/afk-dev/config.json (or $XDG_CONFIG_HOME/afk-dev/config.json). Credentials are stored separately in ~/.local/share/afk-dev/auth.json (or $XDG_DATA_HOME/afk-dev/auth.json). Shell or .env credentials and native OpenCode/Codex auth are also supported.

For scripted setup:

printf '%s' "$DEEPSEEK_API_KEY" | afk config setup \
  --runtime opencode \
  --model deepseek/deepseek-chat \
  --api-key-stdin \
  --yes

Useful commands

afk config get
afk auth list
afk doctor --json
afk web --open
afk chat
afk sessions
afk status
afk resume

Running a task

afk run "Edit src/math.js so add(a, b) returns a + b" \
  --runtime codex \
  --model openai/gpt-5.5 \
  --session-key math-fix \
  --check "pnpm test" \
  --pipeline-option maxSteps=2

The Web UI is the default interactive surface. CLI commands work best for scripted runs, CI-style checks, session inspection, or headless environments.

Config

afk init creates afk-dev.config.json and installs the default code-review-and-fix plugin assets.

{
  "plugins": [
    {
      "name": "code-review-and-fix"
    }
  ]
}

Core config areas:

• plugins: built-in plugin names or custom plugin paths
• workflow: explicit pipeline, roles, stage prompts, and workflow-local metadata
• pipeline: generic run controls such as maxSteps
• checks: trusted project commands to run during verification
• artifacts: trace behavior, defaulting to failure-only traces
• runtime: agent runtime, command, model, timeout, and skills

Workflow routing lives under workflow.options.flow because the flow pipeline owns that contract:

{
  "workflow": {
    "name": "docs",
    "pipeline": "flow",
    "options": {
      "flow": {
        "start": "draft",
        "nodes": {
          "draft": { "type": "stage", "stage": "draft", "stopReason": "completed" }
        }
      }
    }
  }
}

String checks keep shell behavior:

{
  "checks": ["pnpm test"]
}

Structured checks avoid shell expansion:

{
  "checks": [{ "command": "pnpm", "args": ["test"] }]
}

Config priority is CLI flags, then project config, then global config, then AFK defaults. afk run loads .env from the current directory first, then from the resolved workspace directory; existing shell environment variables win.

afk config path
afk config set runtime.name codex
afk config set runtime.model openai/gpt-5.5
afk config get runtime.model
printf '%s' "$OPENAI_API_KEY" | afk auth set openai --stdin

For OpenCode runs, AFK uses shell or .env credentials first, then AFK auth, then OpenCode's native auth store. For Codex runs, AFK uses CODEX_API_KEY, maps OPENAI_API_KEY or AFK openai auth to CODEX_API_KEY, and otherwise lets Codex use its native auth.

Runtime sandboxing

AFK composes sandboxing with the selected runtime. Codex defaults to AFK runtime.sandbox.level: "none" and uses Codex-native --sandbox read-only|workspace-write --ask-for-approval never; other runtimes default to AFK's OS sandbox. The OS sandbox uses bwrap on Linux and sandbox-exec on macOS. If the OS backend is unavailable, AFK fails closed.

{
  "runtime": {
    "name": "opencode",
    "command": "opencode",
    "sandbox": {
      "level": "os",
      "network": "full"
    }
  }
}

• level: "none" for Codex by default, "os" for other runtimes by default, or explicit "none" only for unsandboxed local debugging.
• network: "none" or "full" (default "full"). network: "none" requires level: "os"; if level is omitted, AFK selects "os" so the network policy is enforced.

Use afk doctor to see the active sandbox backend and whether it is available.

Sessions and chat

Use --session-key to keep separate continuation state for related work:

afk run "Implement auth" --session-key auth
afk run "Implement billing" --session-key billing

When --session-key is omitted, AFK derives a readable key from the task text.

For a conversational loop:

afk
afk chat
afk chat auth
afk run --interactive "Implement auth"

Inspect or continue persisted work:

afk sessions
afk status
afk resume
afk resume auth --task "Continue the auth implementation"

afk resume defaults to the latest run. Its optional target can be a session key or a run id. afk chat records chat turns next to runs so a session can be resumed later. AFK stores session state, default artifacts, turn snapshots, and the run lock in a global workspace store under the user's data/cache/temp directories, not in the project tree. Use afk sessions archive <key> to hide a session, afk sessions --all to include archived sessions, afk sessions restore <key> to restore one, and afk storage gc --dry-run before deleting archived session data.

Web UI

Start the local Web console from a project workspace:

afk
# or
afk web --open

afk web accepts the same workspace/runtime selection inputs as other commands:

afk web \
  --workspace . \
  --runtime codex \
  --model openai/gpt-5.5 \
  --port 4321 \
  --open

By default it binds to 127.0.0.1:4321 and protects the UI/API with a random auth token in the printed URL. The Web server is local-only; stop it with Ctrl-C.

Plugins and pipelines

Plugins provide workflow roles, stage prompts, agents, and skills. The official built-in code-review-and-fix plugin is bundled in @flower-f/afk-plugins-official. Custom plugins use an afk-dev.plugin.json manifest plus resources such as agents/, skills/, and prompts/. Plugin paths are resolved relative to afk-dev.config.json.

Workflow pipelines own execution behavior. The built-in generic pipeline is flow, exported from @flower-f/afk-core and wired by @flower-f/afk-node. Third-party pipelines implement the WorkflowPipeline contract from @flower-f/afk-core. See examples/custom-pipeline-plugin for a minimal plugin-provided pipeline.

Development

Requires Node >=22 and the pnpm version recorded in package.json.

pnpm install
pnpm build
pnpm verify

Use AFK itself for feature work when a real runtime is configured. New feature work should start through dogfood so AFK's own workflow stays under regular product pressure.

pnpm dogfood:quick -- --task "Improve AFK chat status output" --session-key dogfood-chat
pnpm dogfood -- --task "Prepare this change for review" --session-key dogfood-review
pnpm dogfood:doctor

pnpm dogfood:quick runs AFK with format and typecheck checks and allows implement, verify, and judge nodes. pnpm dogfood builds the local CLI and runs it against this repository with pnpm verify as the default check command. Dogfood runs default to a 15 minute per-agent runtime timeout; pass --timeout-ms <milliseconds> after -- to override it.

Use --dogfood-check "<command>" before -- to replace the default dogfood checks. Use --dogfood-print-command to inspect the local AFK command without building or starting the runtime. pnpm verify includes pnpm dogfood:smoke so wrapper argument handling stays covered without calling a real model.

If a sandbox blocks runtime writes under your real home directory, use AFK_DOGFOOD_ISOLATED_HOME=1 pnpm dogfood:quick -- ... to place runtime config, data, and cache files under .afk-dev/dogfood-home.

Release

Changesets manages package versions, changelogs, and npm publishing:

pnpm changeset
pnpm changeset:version
pnpm release:verify
pnpm release

pnpm release:verify runs formatting, lint, typecheck, tests, and the pack smoke test. After publishing, verify the npm install path from a clean shell:

pnpm release:published:verify

For beta packages:

pnpm release:beta:dry
NPM_TOKEN=... pnpm release:beta

See the root README.md for the package index and high-level overview.