fork

Build an agent session once, then fork it. A master session is a long context you pay to build a single time — exploration, documentation, domain knowledge. Every child session forks that context instead of rebuilding it.

npm install -g fork-manual-beta-1-0-0
fork --help

Anthropic models are the only ones supported today (vendor: anthropic), though nothing about the CLI is specific to them.

State lives under ~/.fork/<master name>/ by default, overridable with rootDir in the config file. Children are stored under ~/.fork/<master name>/children/.

Master sessions

fork master init <name>

Writes a <name>.fork.yaml config template into the current directory. Whitespace in <name> becomes -. Fails if that file already exists.

fork master init my-project      # → ./my-project.fork.yaml

fork master build [config_path]

Runs the master prompt to build the context, then saves the session. Omit config_path to auto-detect a single *.fork.yaml in the current directory; pass a bare prefix (my-proj) and it resolves to the matching file.

| Flag | Description | | --- | --- | | -y, --yes | Replace an existing master session (otherwise refuses) |

fork master revise [name]

Sends a follow-up prompt to an existing master session and appends it to the prompt history, permanently updating the context.

| Flag | Description | | --- | --- | | -p, --prompt | Prompt to send. Required unless --manual | | -m, --manual | Open an interactive CLI to send updates by hand | | -c, --config | Target by config file instead of [name] | | -r, --root | Root directory to find [name] under |

fork master list

Lists every master session found under the root directory.

| Flag | Description | | --- | --- | | -c, --config | Derive the root directory from this config | | -r, --root | Root directory to search |

fork master delete <names...>

Deletes one or more master sessions and everything under them, including children.

| Flag | Description | | --- | --- | | -r, --root | Root directory to find the sessions under |

fork master delete my-project other-project

Child sessions

All four commands identify the master by either the [name] positional or --config. See Using --config for how that shifts positionals.

fork spawn [name] [identifier]

Starts an interactive session against a master's context. It does one of two things depending on whether you pass [identifier]:

• Omitted — forks the master into a brand new child session, which can be retrieved later with fork list.
• Given — resumes that existing child, picking up its history where you left off. [identifier] is the child's label or ID, as shown by fork list.

| Flag | Description | | --- | --- | | -l, --label | Label the new child. Rejected when resuming | | -p, --prompt | Initial prompt for the model. Works for new and resumed sessions | | -c, --config | Target by config file instead of [name] | | -r, --root | Root directory to find [name] under |

fork spawn my-project -l bugfix               # new child, labeled "bugfix"
fork spawn my-project                         # new child, unlabeled
fork spawn my-project bugfix                  # resume the child labeled "bugfix"
fork spawn my-project bugfix -p "where was I?"  # resume it with an opening prompt

fork list [name]

Lists the child sessions under a master, by label where one is set, otherwise by ID. Use this to find an identifier to pass to spawn, label, or delete.

| Flag | Description | | --- | --- | | -c, --config | Target by config file instead of [name] | | -r, --root | Root directory to find [name] under |

fork label [name] [identifier]

Re-labels a child session. [identifier] is its current label or ID. Labels must be unique within a master and cannot contain |.

| Flag | Description | | --- | --- | | -l, --label | The new label. Required | | -c, --config | Target by config file instead of [name] | | -r, --root | Root directory to find [name] under |

fork label my-project 4849c56e-bbd8-4b2b-a1d3-bf9066a14607 -l bugfix

fork delete [name] [identifiers...]

Deletes child sessions by label or ID. The master itself is untouched.

| Flag | Description | | --- | --- | | -a, --all | Delete every child under the master | | -c, --config | Target by config file instead of [name] | | -r, --root | Root directory to find [name] under |

fork delete my-project bugfix hotfix
fork delete my-project --all

Using --config

--config replaces the [name] positional, so the remaining positionals shift one place left:

fork label my-project bugfix -l fixed                  # by name
fork label -c my-project.fork.yaml bugfix -l fixed     # by config

This applies to spawn, label, and delete. Exactly one of [name] or --config is required.

Global flags

| Flag | Description | | --- | --- | | --help | Show help for the CLI or any command | | --version | Print the version |