Skip to content

Installation

Get Agent Flow up and running with Claude Code in minutes.

Prerequisites

Before installing Agent Flow, ensure you have:

  • Claude Code CLI installed and configured
  • Bash (macOS default 3.2 works; Linux, or WSL on Windows)
  • jq (the hooks and state scripts use it)
  • A project directory where you want to use Agent Flow

Installation Methods

This doc is the comprehensive install reference. For the quick-start path, see the README.

The simplest path — no local clone required:

/plugin marketplace add josix/agent-flow
/plugin install agent-flow@josix-plugins

Claude Code fetches the plugin directly from GitHub. Updates via /plugin update agent-flow@josix-plugins.

Method 2: Local Clone (Development)

Clone Agent Flow anywhere, then reference it when launching Claude Code:

git clone https://github.com/josix/agent-flow.git ~/agent-flow
claude --plugin-dir ~/agent-flow

For project-specific use, clone into your project instead (.claude-plugins/agent-flow) and pass that path to --plugin-dir.

Method 3: Git Submodule

For version-controlled projects:

# Add as submodule
git submodule add https://github.com/josix/agent-flow.git .claude-plugins/agent-flow

# Launch Claude Code with the plugin
claude --plugin-dir .claude-plugins/agent-flow

Directory Structure

After installation, Agent Flow contains:

agent-flow/
├── .claude-plugin/
│   └── plugin.json         # Plugin manifest
├── agents/                  # Agent definitions
│   ├── Riko.md
│   ├── Senku.md
│   ├── Loid.md
│   ├── Lawliet.md
│   ├── Alphonse.md
│   └── Speedwagon.md
├── commands/                # Command definitions
│   ├── orchestrate.md
│   ├── deep-dive.md
│   ├── explain.md
│   ├── analyze.md
│   └── team-orchestrate.md  # deprecated
├── workflows/
│   └── implement-review-verify.js   # Phases 3-5 of /orchestrate
├── hooks/                   # Hook configurations
│   ├── hooks.json
│   └── scripts/
├── scripts/                 # Utility scripts
├── skills/                  # Skill definitions
├── templates/codex/review-rubric.md  # Codex co-review rubric
└── docs/                    # Documentation

Verify Installation

From the plugin directory, run the structural smoke test:

bash scripts/validate-plugin.sh

Expected output: ✓ All tests passed with exit code 0. The script validates plugin manifests, hook scripts, agent/skill/command frontmatter, and several runtime edge cases.

Inside Claude Code, confirm the commands are discoverable by typing / and looking for: - /orchestrate — multi-phase orchestration (review and verification run in parallel) - /team-orchestrate — deprecated; forwards to /orchestrate - /deep-dive — codebase exploration - /agent-flow:explain — interactive HTML explainer for a topic - /agent-flow:analyze — session and subagent analytics

Optional: Graphify Integration

Agent Flow can share a knowledge graph of your codebase across subagents via an MCP server. To enable it, install graphify with the mcp extra (choose one):

# System Python
pip install 'graphifyy[mcp]'

# Isolated via pipx
pipx install graphifyy
pipx inject graphifyy mcp

Then, in your project:

/graphify

This builds graphify-out/graph.json. From the next Claude session onwards, Riko, Senku, and Lawliet can query it via MCP tools. See Using Graphify for the full workflow.

Skip this step to use Agent Flow without the graph — orchestration works either way.

Optional: Personal KB Integration

If you maintain a personal knowledge base (notes, decisions, past project learnings) that has been indexed with graphify, Agent Flow can share it with Riko, Senku, and Lawliet as cross-project memory.

Prerequisites: Your personal KB must already have graphify-out/graph.json built (see the Graphify Integration section above, applied to your personal notes directory).

Quick setup:

  1. Add a personal-kb MCP server entry to ~/.claude.json pointing to your personal KB's graph file.
  2. Export the env var in your shell profile: 
    export AGENT_FLOW_PERSONAL_KB_PATH=~/personal/knowledge-base
  3. Restart Claude Code.

See Using Personal KB for the complete setup guide, including MCP server configuration examples and verification steps.

Skip this step to use Agent Flow without personal KB recall — orchestration works either way.

Optional: AgentsView Integration

Agent Flow can let Riko, Senku, and Lawliet search your prior Claude Code session history to leverage proven past approaches and cross-verify current handling against precedent. To enable it, install the agentsview CLI (see the agentsview project's own installation instructions).

Unlike Graphify and Personal KB, this integration is a plugin-shipped mcpServers entry in .claude-plugin/plugin.json — there is no manual MCP server registration step or env var required. It is auto-detected on the next Claude session once the agentsview binary is on PATH.

See Using AgentsView for the full workflow, including the five granted tools and the AGENT_FLOW_NO_AGENTSVIEW=1 opt-out.

Skip this step to use Agent Flow without prior-session-history search — orchestration works either way.

Configuration

State Directory

Agent Flow creates a .claude/ directory in your project for state files:

your-project/
└── .claude/
    ├── orchestration.local.md   # Created by /orchestrate
    ├── deep-dive.local.md       # Created by /deep-dive
    ├── agent-reports/           # Long subagent reports
    ├── observability/           # Event store and reports
    └── codex/                   # Codex co-review working files

You don't need to edit .gitignore. agent-flow adds a managed block to your project's .gitignore the first time a command runs (.claude/*.local.*, .claude/.verify-completion-pass, .claude/agent-reports/, .claude/codex/, .claude/explain-briefs/, .claude/observability/, graphify-out/, explain-out/). Set AGENT_FLOW_NO_GITIGNORE to any non-empty value to opt out.

Environment Variables

Agent Flow uses these environment variables (set automatically by Claude Code):

Variable Description
CLAUDE_PLUGIN_ROOT Plugin installation directory
CLAUDE_PROJECT_DIR Project root
CLAUDE_ENV_FILE SessionStart only

Project Context Detection

On session start, Agent Flow detects your project type (checked in this order; the first match wins):

Marker File Detected Type
package.json Node.js
pyproject.toml or setup.py Python
Cargo.toml Rust
go.mod Go
pom.xml or build.gradle Java

This is session context for the agents; the Stop hook itself only checks Node.js and Python projects.

Troubleshooting

Commands Not Found

If /orchestrate or /deep-dive are not recognized:

  1. Verify plugin path is correct
  2. Check that commands/ directory exists
  3. Ensure command files have .md extension

Agents Not Responding

If agents don't exhibit specialized behavior:

  1. Check that agents/ directory contains all .md files
  2. Verify agent names match (case-sensitive)
  3. Check for YAML frontmatter syntax errors

Hooks Not Triggering

If hooks don't seem to activate:

  1. Verify hooks/hooks.json exists and is valid JSON
  2. Check script permissions: chmod +x hooks/scripts/*.sh
  3. Verify ${CLAUDE_PLUGIN_ROOT} resolves correctly

State File Errors

If state files cause issues:

  1. Remove existing state files: rm -f .claude/orchestration.local.md .claude/team-orchestration.local.md .claude/deep-dive.local.md .claude/review-baseline-untracked.local.txt (not .claude/*.local.*, which would also delete settings.local.json)
  2. Ensure .claude/ directory exists: mkdir -p .claude
  3. Check disk permissions for writing

Updating

To update Agent Flow:

# If cloned directly
cd ~/agent-flow
git pull

# If using submodule
git submodule update --remote .claude-plugins/agent-flow

Uninstalling

To remove Agent Flow:

  1. Stop using the --plugin-dir flag
  2. Optionally remove the plugin directory: 
    rm -rf ~/agent-flow
# OR
rm -rf .claude-plugins/agent-flow
  3. Remove generated files (keep the rest of .claude/, which may hold your own settings): 
    rm -f .claude/orchestration.local.md .claude/team-orchestration.local.md .claude/deep-dive.local.md .claude/review-baseline-untracked.local.txt
find .claude -maxdepth 1 -name 'research-*.local.md' -delete
rm -rf .claude/agent-reports .claude/observability .claude/codex

Next Steps