fp integrates with Claude Code to keep issues, progress, and commits connected throughout development. Once configured, Claude Code follows the fp workflow automatically.

## Setup

```bash
fp init
```

During setup, fp asks which coding agent is in use. Select **Claude Code**, then confirm to install the integration:

```
Which coding agent are you using?
  1) Claude Code
  2) Other coding agent (Codex, Gemini, Mistral, ...)
  3) Skip

Set up Claude Code project-managed skills and hooks? (Y/n)
```

This installs fp skills and hooks into the project:

- **Skills** - `/fp-plan`, `/fp-implement`, `/fp-review` become available in Claude Code
- **Hook** - a PostToolUse hook tracks file changes back to issues
- **`FP_CLAUDE.md`** - fp workflow rules loaded by Claude Code on every session
- **`CLAUDE.md`** - updated with a reference to `FP_CLAUDE.md`

**Restart Claude Code** after setup to activate the skills.

To run the Claude Code setup on an already-initialized project:

```bash
fp setup claude
```

## The fp workflow: plan, implement, review

fp is structured around three phases:

| Phase | Skill | Description |
|-------|-------|-------------|
| **Plan** | `/fp-plan` | Break a feature into a hierarchy of scoped issues |
| **Implement** | `/fp-implement` | Claim an issue, do the work, log progress, attach commits |
| **Review** | `/fp-review` | Inspect diffs, verify commits are assigned, prepare for PR |

These skills are installed into the project. Invoke them directly in Claude Code, or describe what needs to be done and Claude Code will use them.

### Plan

```
Plan out the authentication feature
```

Claude Code creates an issue hierarchy in fp:

```
FP-abcd [todo] Add authentication
├── FP-efgh [todo] Design auth flow
├── FP-ijkl [todo] Implement OAuth provider
├── FP-mnop [todo] Add session management
└── FP-qrst [todo] Write tests
```


### Implement

```
Work on FP-ijkl
```

fp tracks which commits belong to which issue as work progresses. Claude Code claims the issue, logs progress via comments, and marks it done following the workflow in `CLAUDE.md`.

### Review

Issues and diffs are accessible from the CLI or the [fp Mac app](/docs/mac/overview).

From the CLI:

```bash
fp issue diff FP-ijkl     # Diff for one issue
fp issue files FP-ijkl    # Files changed
fp issue diff FP-abcd     # Parent aggregates all children
fp tree                    # Overview of all progress
fp review FP-ijkl         # Open interactive diff review in the Mac app
```

## Extending the workflow

Plan, implement, and review are the default cornerstones. fp is extensible and every project's workflow is different. See the [Extensions](/docs/extensions/overview) docs for how to adapt fp to fit specific needs.

## How the CLAUDE.md integration works

Accepting the Claude Code setup adds the following to `CLAUDE.md`:

```markdown
@FP_CLAUDE.md
```

`FP_CLAUDE.md` is managed by fp. It instructs Claude Code to:

- Use `fp issue` for task tracking instead of built-in todo tools
- Log progress with `fp comment` at each milestone
- Attach commits with `fp issue assign`
- Commit frequently and before ending a session

These rules are part of the project context and do not need to be repeated in prompts.

To update `FP_CLAUDE.md` after upgrading fp:

```bash
fp setup claude
```

## Tips

- **Review before marking done** - use `fp issue diff` to verify what Claude Code changed
- **Use priorities** - `--priority high` helps Claude Code pick the most important work first
- **Keep issues small** - smaller issues produce tighter diffs and more focused sessions