Installation

Get agentful up and running in your project in under a minute.

Prerequisites

Before installing agentful, ensure you have:

Claude Code installed - Get it here
Node.js 18+ installed - Download here
A project directory to work in

Optional (for 24/7 development):

Ralph Wiggum plugin for Claude Code

/plugin install ralph-wiggum@anthropics

Installation Methods

Method 1: Initialize in Existing Project (Recommended)

If you have an existing project:

cd your-project
npx @itz4blitz/agentful init

This creates:

.claude/ - Pre-configured agents, commands, skills
.agentful/ - Runtime state tracking (gitignored)
PRODUCT.md - Your product spec template
CLAUDE.md - Project instructions for Claude

Method 2: Initialize New Project

Starting from scratch? Create a new project first:

mkdir my-app
cd my-app
npm init -y
npx @itz4blitz/agentful init

Method 3: Bare Initialization

If you already have PRODUCT.md and CLAUDE.md:

npx @itz4blitz/agentful init --bare

This skips creating template files and only sets up .claude/ and .agentful/.

What Gets Created

After running npx @itz4blitz/agentful init, you'll see:

✅ agentful initialized successfully!
 
Next steps:
  1. Edit PRODUCT.md with your product specification
  2. Run: claude
  3. Type: /agentful-start
 
For autonomous 24/7 development:
  /ralph-loop "/agentful-start" --max-iterations 50 --completion-promise "AGENTFUL_COMPLETE"

Directory Structure

your-project/
├── PRODUCT.md              # ← Edit this: your product spec
├── CLAUDE.md               # Project instructions
├── .claude/                # agentful configuration
│   ├── agents/             # 7 specialized agents
│   ├── commands/           # 4 slash commands
│   ├── skills/             # Domain skills
│   └── settings.json       # Hooks and permissions
├── .agentful/              # Runtime state (gitignored)
│   ├── state.json
│   ├── completion.json
│   ├── decisions.json
│   └── architecture.json
└── package.json

Verification

Verify agentful is installed:

# Check that .claude directory exists
ls -la .claude/
 
# Check that .agentful directory exists
ls -la .agentful/
 
# Verify state files
cat .agentful/state.json

You should see:

.claude/ directory with agents, commands, skills
.agentful/ directory with state files
Initial state set to idle

Updating .gitignore

agentful automatically adds .agentful/ to your .gitignore:

# agentful runtime state
.agentful/

The .agentful/ directory contains runtime state that shouldn't be committed:

state.json - Current work state
completion.json - Progress tracking
decisions.json - Pending decisions
architecture.json - Detected tech stack

Note: The .claude/ directory should be committed to version control.

Troubleshooting

Issue: "Command not found: npx"

Solution: Install Node.js 18+ from nodejs.org

# Verify Node.js is installed
node --version  # Should be v18+
 
# Verify npx is available
npx --version

Issue: ".claude directory already exists"

If you already have a .claude/ directory, agentful will ask:

⚠️  .claude/ directory already exists!
Overwrite? (y/N)

Type y to overwrite (your existing config will be replaced)
Type N or press Enter to abort

Recommendation: Back up your existing .claude/ before overwriting:

mv .claude .claude.backup
npx @itz4blitz/agentful init

Issue: Permission denied

Solution: Make sure you have write permissions in the directory:

# Check permissions
ls -la
 
# If needed, change ownership (macOS/Linux)
sudo chown -R $USER:$USER .claude .agentful

Issue: "Cannot read properties of undefined"

Solution: Ensure you're running in a valid Node.js project:

# Initialize package.json if missing
npm init -y
 
# Then try again
npx @itz4blitz/agentful init

Next Steps

Now that agentful is installed:

Edit your product spec → Quick Start Guide
Start Claude Code → claude
Begin development → /agentful-start

Uninstallation

To remove agentful from your project:

# Remove agentful directories
rm -rf .claude .agentful
 
# Remove template files (optional)
rm PRODUCT.md CLAUDE.md
 
# Remove .gitignore entry (optional)
# Edit .gitignore and remove the .agentful/ line

Advanced Options

Custom Install Location

By default, agentful installs in the current directory. To install elsewhere:

npx @itz4blitz/agentful init --path /path/to/project

Silent Installation

For automation scripts:

npx @itz4blitz/agentful init --silent

Skips the confirmation prompt and creates a backup if .claude/ exists.

Version Check

Check which version of agentful you installed:

npx agentful --version