Installation

Install

Two ways to bring fp into a project. Pick one — the end state is the same.

Run it yourself

curl -fsSL https://setup.fp.dev/install.sh | sh -s

Downloads the latest fp binary for your platform and adds it to your path. Then cd into your project and run fp init.

Or hand it to your agent

Paste this into Claude Code, Codex, Cursor, Gemini, or any agent that reads AGENTS.md:

Install fp and start the onboarding loop in this project:

1. curl -fsSL https://setup.fp.dev/install.sh | sh -s
2. fp init --yes --agent standard   # use `--agent claude` for FP_CLAUDE.md / CLAUDE.md
3. fp tree, then work the seeded onboarding children one at a time

--agent standard writes FP_AGENTS.md and ensures AGENTS.md @-includes it, so the fp workflow loads into agents that read AGENTS.md. Use --agent claude instead when you want Claude-specific FP_CLAUDE.md / CLAUDE.md files.

Requirements

• macOS (Apple Silicon or Intel) or Linux (x86_64)
• A coding agent like Claude Code, Codex, Cursor, Gemini (optional but recommended)

Verify Installation

fp --version

Initialize a Project

Navigate to your project directory and run:

cd your-project
fp init

fp init does the following:

• Registers the project in ~/.fiberplane/projects.toml so fp commands work from any subdirectory.
• Scaffolds .fp/extensions/ with the extension types and authoring guide.
• Updates .gitignore to ignore .fp/.
• On the first fp project on a machine, seeds an onboarding issue tree so there is something to explore immediately.

In interactive mode, fp init then asks which agent instructions to add. You can answer ahead of time with --agent:

Flag	What it writes
--agent claude	FP_CLAUDE.md and ensures CLAUDE.md @-includes it
--agent standard	FP_AGENTS.md and ensures AGENTS.md @-includes it
--agent codex	alias for standard
--agent skip	no agent instruction files

You can also run the agent step on its own later with fp agent setup.

For non-interactive setup (CI, scripts):

fp init --prefix FP --yes --agent skip             # Skip prompts, no extra agent files
fp init --prefix FP --yes --agent claude  # Skip prompts, also write FP_CLAUDE.md / CLAUDE.md

Workflow Primers for Agents

fp guide prints workflow primers to stdout as markdown. Pipe them into your agent or print them for review:

fp guide plan         # Planning skill
fp guide implement    # Implementation skill
fp guide brainstorm   # Brainstorm authoring (alias: bs)
fp guide extension    # Extension authoring (aliases: extensions, ext)

Pass --references to surface companion material, for example fp guide brainstorm --references mermaid.

What Gets Created

your-project/
└── .fp/
    └── extensions/           # Scaffolding for authoring fp extensions

With --agent standard or --agent codex:

your-project/
├── FP_AGENTS.md              # Agent workflow instructions (managed by fp)
└── AGENTS.md                 # `@`-includes FP_AGENTS.md

With --agent claude (or by selecting Claude Code in the prompt):

your-project/
├── FP_CLAUDE.md              # Claude-specific workflow rules (managed by fp)
└── CLAUDE.md                 # `@`-includes FP_CLAUDE.md

FP_AGENTS.md and FP_CLAUDE.md are managed files. fp owns those files and may overwrite them. AGENTS.md and CLAUDE.md are yours; fp only ensures they @-include the corresponding FP_* file and never touches user-authored content.

Issue data, comments, and sync state are stored locally outside the repo at ~/.fiberplane/projects/<storage-dir>/. The project is registered globally in ~/.fiberplane/projects.toml so fp commands work from any subdirectory of the repo.

Agent Instruction Setup

Already-initialized project? Add or refresh agent files without re-running fp init:

fp agent setup claude     # Write FP_CLAUDE.md + ensure CLAUDE.md @-includes it
fp agent setup standard   # Write FP_AGENTS.md + ensure AGENTS.md @-includes it
fp agent setup codex      # Alias for `standard`

These commands are idempotent — files are only rewritten when their content drifts from the bundled template, and the @-include is only added when it’s missing.

Update the CLI

fp update

fp update installs the latest stable release. Use fp update --latest to opt into prereleases.

Next Steps

Head to the Quick Start to create your first issues and learn the fp workflow.