Overview

Agentic Forge is a TypeScript/Node.js package that provides YAML-based workflow orchestration for coding agents. It bundles skills, agents, and prompts as package data, enabling autonomous multi-step task execution with parallel execution, conditional logic, and retry mechanisms.

Best for: Autonomous development where you prefer the coding agent works independently.

Supported Runtimes

Claude Code is the primary and recommended coding agent for Agentic Forge. It is the default runtime, has the deepest integration, and supports all features including bundled skills, agent configurations, and worktree isolation.

Codex CLI is supported as an experimental runtime. Its integration is limited compared to Claude Code — it does not support bundled skills or agent configurations, and may have permission issues, particularly on Windows. Use it for secondary tasks like independent code review in mixed-runtime workflows.

| Runtime | CLI | Default | Status | | ----------- | -------- | ------- | ------------ | | Claude Code | claude | Yes | Recommended | | Codex CLI | codex | No | Experimental |

Use --runtime codex on the CLI or set defaults.runtime: codex in config to switch. Per-step runtime: fields always take precedence over the invocation default.

Tool Permissions

Most bundled workflows declare required-tools in their settings, which automatically allows the coding agent to use Read, Edit, Write, Glob, Grep, and Bash without prompting for permission on each call. This means the agent can read, create, modify, and delete files, as well as execute arbitrary shell commands in your repository, without asking for confirmation.

This is by design -- autonomous workflows need these permissions to operate without manual intervention. Additionally, the agent always has access to any permissions configured at the repository level (.claude/settings.json, .claude/settings.local.json, etc.), regardless of the workflow's required-tools setting.

If you want more control, you can:

• Review the workflow YAML before running it (af workflows --verbose or inspect the file directly)
• Use worktree isolation (use_worktree=true, the default for plan-build-review) so changes happen on a disposable copy of your repo
• Remove or modify required-tools in a custom workflow to restrict which tools are auto-approved

See Workflows documentation for details on which workflows declare these permissions.

Getting Started

Prerequisites

• Node.js 20+
• pnpm (recommended) or npm
• Claude Code CLI installed and configured (required for default runtime)
• Codex CLI installed and configured (optional, required for runtime: codex steps)

Installation

npm install -g agentic-forge

Updating

Update to the latest version using npm:

npm install -g agentic-forge@latest

To update the default workflow files to the latest bundled versions, re-run af init --force. This overwrites any changes you made to these files.

# Update global workflows
af init --force

# Update project-local workflows
af init --local --force

Run Your First Workflow

No setup required. Run the demo workflow to verify your installation:

af run claude-demo

Run a real workflow:

af run plan-build-review --var "task=Add dark mode support" --slug "dark-mode"

The --slug flag names the output directory (e.g., dark-mode/ instead of a generated timestamp ID), making it easy to find results later.

Project Setup

Initialize a local agentic/ directory to customize workflows and config for your project:

af init --local

Workflow Builder

Load authoring skills into Claude Code to create and manage workflows interactively:

claude --add-dir $(af authoring-dir)

Then use /af-workflow-builder to create, validate, explain, or debug workflows.

Documentation

| Document | Description | | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | | Getting Started | Installation, quick tour, initialization, and creating your first workflow | | CLI Reference | Complete list of commands with all arguments and options | | Workflows | Bundled workflows, their use cases, variables, and examples | | Coding Agents | Supported runtimes, per-step configuration, and model names | | Configuration | All configuration options, defaults, and layering behavior |

Contributing

• Bug reports and suggestions - Open an issue on GitHub
• Code contributions - See CONTRIBUTING.md for development setup and PR guidelines

Credits

• Original ralph-loop technique: Geoffrey Huntley - Ralph Wiggum as a "software engineer"

License

This project is licensed under the MIT License - see the LICENSE file for details.