Getting started

Install fx, connect your team’s manifest, and work with repositories and coding agents.

See the version history for release changes. Check fx <command> --help and the Skill bundled with your installed executable for the features it supports.

Choose the section for your task:

• New workspace: install, then quick start.
• No manifest yet: set up companion tools.
• Keep current: update tools and Skills.
• Large workspace: choose repositories before downloading.
• Interrupted setup: read the result and recover.
• Coding agent: use structured results and the bundled Skill.

Requirements

• Node.js ≥22 (development uses Node 24), or Bun as an alternative runtime.
• Git on PATH. Companion CLIs can be installed afterward through fx tool install.
• A manifest source for a workspace: use your team's repository or create your own. Setting up companion tools alone needs none.
• npm for global installation and fx self update, including when using Bun.

macOS and Linux are supported. Native Windows adapters are implemented, but Windows execution and real host activation remain unverified. Windows targets PowerShell 5.1/7 and cmd on local NTFS, without requiring WSL, Git Bash, administrator privileges or Developer Mode. See platform support.

Bitbucket Git authentication

When bitbucket-cli git --help is available, fx uses that companion's existing login for HTTPS Git during manifest initialization, repository cloning and sync. A Data Center PAT with repository read permission is sufficient when the server permits HTTPS Git; no SSH key is required, even if the manifest uses SSH URLs. The companion converts URLs for each invocation and preserves stored remotes. fx never reads or stores the token. Push additionally requires write permission.

Before the first manifest clone, configure the companion's service and login. For multiple accounts, select the intended context with BITBUCKET_CONTEXT; workspace operations use the manifest's declared context when present. Verify actual Git reading with bitbucket-cli git -- ls-remote <clone-url>. Missing or older companions retain ordinary Git authentication; upgrade the companion to use this bridge. Rejected credentials remain errors. Standalone git fetch needs its own authentication, or use bitbucket-cli git -- -C <dir> fetch upstream. Recursive submodules are outside this bridge's supported scope.

Install

Public package

The public distribution uses @angelmsger/fx from npmjs. It does not require your team's private Registry.

npm install -g @angelmsger/fx --registry=https://registry.npmjs.org/ --@angelmsger:registry=https://registry.npmjs.org/
fx --version

In PowerShell, use npm.cmd and fx.cmd if the execution policy blocks .ps1 shims.

Run from source

In the fx-devkit checkout, using the development versions in package.json:

npm ci
npm run build
node bin/fx.js --help
node bin/fx.js --version

In the examples below, replace fx with node /absolute/path/to/fx-devkit/bin/fx.js when running from source. Building is required because the launcher loads dist/.

Updates

For a source installation, update your checkout and run npm ci and npm run build again. fx self info --format json shows the running version and configured package registry. See the update guide.

Quick start

You need two things: the manifest source supplied by your team and a directory for the workspace. You can ask your coding agent: “Use fx to prepare this manifest in this directory.” If you are running the commands yourself:

fx init ./work --from <manifest-repository> --dry-run
fx init ./work --from <manifest-repository>

fx checks the source, prepares authorized local tools and configuration, clones the selected repositories, and prepares the Agent guides and Skills. The name is derived from the directory and avoids existing registrations. Existing files and completed work are preserved. Review the displayed commands before approving new manifest actions.

When fx reports Ready to work, you can start. If it needs personal sign-in, access or approval, it reports the remaining items together. Complete those items and use the printed continuation command:

fx init --resume --workspace work

The terminal output prints each personal sign-in command and a continuation command. Run personal sign-in in your own terminal, then use the continuation after the listed prerequisites change.

A continuation verifies current state and skips completed preparation. It does not reimport a directory source or rebuild checkouts. You do not need to choose internal stages or run a separate diagnostic sequence to finish initialization.

New workspaces select all shared repositories. To limit the first download, choose repositories and add --repos to the initial preview and apply. Existing directories are adopted automatically. For everyday updates use fx sync; fx status shows repository state.

Set up companion tools without a manifest

Without a team manifest, fx init with no directory sets up the companion CLIs fx knows on this machine. It lists them and asks which ones you want; press Enter for all of them. Name them instead to skip the question:

fx init
fx init --tools bitbucket-cli,jira-cli --dry-run
fx init --tools all

fx installs the tools you do not have yet, has each one install its Skill into your coding agents next to fx's own Skill, and checks whether you are signed in. For a tool that is not set up yet, fx offers to start that tool's own setup, such as bitbucket-cli config init, which asks for the service address and your credentials. If you decline, pass --yes or run without a terminal, fx lists those commands for you instead; run fx init --tools <names> again afterwards to check. Tools you already have are kept as they are; updating is a separate step.

This registers no workspace and presets nothing. With a manifest, fx init <dir> --from <manifest> decides the tools and fills in each service's address for you.

Keep tools and Skills up to date

fx self update --yes   # fx, then the copies of its Skill you have installed
fx tool update --all   # every companion tool you have installed, then its Skill

fx tool update --all updates the companion tools that are already installed and installs nothing new; fx tool install does that. Each tool fx installs or updates then installs its Skill again for your coding agents, so they read the instructions of the version you now have. fx self update ends by having the new fx refresh the copies of its own Skill that are older than it, as fx skill update does on its own. Inside a workspace the same commands update the tools the workspace uses, and fx sync refreshes Skills too.

Find and manage workspaces

fx workspace list works from any directory, including when no default is set or a registered workspace has a missing root or manifest. fx workspace show <name> reports its identity, source, health and selection context without requiring a healthy manifest. Use fx status --workspace <name> to inspect one explicitly; otherwise the containing workspace takes precedence over default_workspace.

fx workspace list
fx workspace show work
fx status --workspace work
fx config set default_workspace work

When a directory has already moved, use workspace relocate <name> <new-dir> to update its registration. It does not move or clone the checkouts. Use workspace rebind <name> --from <source> to change the manifest source while preserving that workspace's identity and personal selections. A second name for the same physical directory is not a migration.

workspace unregister <name> ends management while retaining business checkouts. Preview lifecycle changes with --dry-run and inspect any owned resource cleanup or conflict before applying. Foreign files are preserved.

Choose repositories before downloading

Limit the initial download by passing --repos to init. The selected names must exist in the inspected manifest. --no-repos starts with an empty repository selection. Repeating init without either flag retains an existing selection.

fx init ./work --from <manifest-repository> --repos example-api --dry-run
fx init ./work --from <manifest-repository> --repos example-api

For an existing workspace, select replaces the collection; pick adds names and unpick removes them. Selection changes do not delete files, and changing selection alone does not download a checkout. Run sync when ready to obtain or update selected repositories.

fx repo select example-api
fx repo pick example-web
fx sync --dry-run
fx sync
fx repo select --all
fx env select dev
fx env select --none
fx env select --all

Manifests using explicit Git URLs without a code-host binding need no code-host username to synchronize repositories.

The catalog remains available even when a repository has not been downloaded. Ask your Agent to work on that repository, or run fx repo show <name>: its next_steps select the missing repository and synchronize checkouts in the correct workspace. Then continue in the reported path.

--all follows the team's full shared collection, including future additions. An explicit list containing every current name remains a fixed list. --none selects no shared entries. Machine-local repositories and the manifest checkout remain separately managed. Lists and selection results identify the active mode, so an empty selection cannot be confused with an unset default.

Only these commands change the environment selection. fx login never asks for it: with none set it covers every declared environment and says how to narrow it, and --env limits one invocation without changing the selection.

Read repository status

fx status identifies the workspace and includes untracked-file counts. fx status --dirty finds both tracked modifications and newly created, untracked files. JSON preserves dirty for tracked/index modifications and adds uncommitted for either kind of work. Ignored files are not untracked work. An empty result explains whether no repositories are selected or no selected repositories match the filter.

The workspace root is not a Git repository, so fx status also returns stray_entries: files and directories at the root that are not a checkout, a derived guide, the Go workspace fx keeps, agent or service configuration, or the workbench. fx doctor lists each one in its root group as a warning that does not affect readiness.

Sync preserves working files and branches. Read the planned action: tracked modifications can cause skip_dirty, while a checkout on another branch can update only the tracked branch reference. An empty upstream is skipped with nothing to fast-forward; one that lacks the tracked branch is skipped too, and reported for review. When an update would replace a local file the branch does not track, ignored files such as .env included, sync leaves that checkout as it is, reports outcome local_files_in_the_way and lists the files in files_in_the_way; move them aside, then sync again. A status report does not itself run fetch; add --fetch explicitly when remote comparisons must be refreshed.

In a terminal, sync and init print a repository or Skill row only when it needs a look; what succeeded is counted on the status line. Both close with one line per stage, then the blockers grouped by what resolves them: a sign-in, access the service refused, or a server this machine cannot reach, which gets the command that checks it again. --verbose prints every row, and a pipe or --format json still receives them all.

Concepts

The workspace and the manifest

A workspace is a registered plain directory containing independent checkouts and managed agent resources. The manifest lives separately under ~/.fx/workspaces/<name>/source. fx never runs Git at the managed workspace root. Sync preserves dirty, diverged and off-branch work rather than checking out, resetting or stashing it.

Output that belongs to no repository goes under .workbench/ at the workspace root: one dated directory per task for reports, plans and evidence, worktrees/ for git worktree add targets, and tmp/ for anything disposable. The derived guide gives agents the same rules. fx never writes inside it.

The root AGENTS.md is the one guide fx derives, and agents read it on their own. Claude Code does from 2.1.277, provided no CLAUDE.md or CLAUDE.local.md sits at the workspace root or above it. One that does is read in place of the guide, so start it with @AGENTS.md.

The manifest's workspace, environments, tools and members documents describe shared facts; optional harness declarations describe MCP resources and rules. Use fx manifest explain '<path>' or fx manifest schema --kind <kind> to inspect fields.

Your personal layer

Configuration registers roots and preferences. Agent selection is shared by all workspaces registered in the same FX_HOME. Per-workspace local layers select repositories and environments and carry personal overrides. repo add registers a local reference; repo remove removes that reference, never its files. A profile export carries settings to another machine without copying credentials, trust records or manifest checkouts.

Capabilities and providers

A capability describes an intent such as code hosting, CI, logs or error tracking. A provider implements it through its companion CLI. The manifest binds capabilities to providers and environment-specific coordinates. Use can for readiness, where for service coordinates, and release check for the declared release checklist.

A workspace binds code-host, issue-tracker, knowledge-base, im, channel, calendar, meeting, task and worklog once; an environment binds error-tracker, log-store, metrics, ci and cluster per platform instance. fx can without a target lists them with what serves each one in this workspace; fx manifest providers lists what is bound and what each capability accepts. calendar is where schedules and availability live; meeting is the conferencing system that holds online meetings, their recordings and minutes, so a team that schedules in one product and meets in another binds both. On WeCom, wecom-calendar lists the schedules its bot can see through the WeCom CLI, while wecom-calendar-cli searches a local mirror of each member's own calendars, history included; each member signs in and fills the mirror with wecom-calendar-cli sync themselves.

Bind the workspace capability channel to wecom-channel-cli to install the CLI and its Skill. Readiness runs doctor through the agent socket. Channel observations exclude messages authored by the same bot, including another client using that identity. Upgrade the broker together with the CLI and reconcile older watch checkpoints or relay queues using the companion's migration guide.

For smart-bot conversations, bind im to wecom-chat-cli only inside a restricted worker workspace. fx can im checks access to the current task and returns its read command without exposing the conversation. Installation is available through fx tool install wecom-chat-cli; the packaged Skill needs manual installation through the isolated host. See worker setup.

metrics is served by prometheus-cli. Its coordinate is a service's scrape job: where prints an up{job="..."} query that returns the label set of that service's targets, the starting point for writing further selectors. A selector that matches nothing still succeeds, so metrics offer no existence probe and where --probe reports unknown for them rather than a guess.

Companion tools and trust

tool list/show explains requirements; tool install/update uses available installers; login guides setup. Companions own authentication, including which service a stored credential may reach. Commands fx defines for bundled tools run without confirmation; command vectors your team's tools.yaml adds or overrides require trust once, and a changed vector requires new trust. Acknowledging a manual step never substitutes for a successful verification.

Tool definitions combine the bundled catalog with the selected workspace's tools.yaml patch, and the workspace's toolchain is the part of that the workspace actually uses: the tools its bound providers drive, plus the tools its patch names. fx tool list reports which of the two put each tool there, and --catalog also lists the tools fx knows that nothing selects. Workspace selection is --workspace, FX_WORKSPACE, the registered root containing the current directory, then default_workspace. Without a resolved workspace there are no bindings to read, so tool commands list the bundled catalog. The package manager owns installation locations; tools are shared across workspaces.

tool install and tool update require names or --all, never both. Install's --all selects enabled tools missing from PATH; update's --all selects the enabled tools of the selected toolchain that are on PATH, and inside a workspace a TOOLS_NOT_INSTALLED notice names the ones it left out. Named operations can explicitly select a disabled tool. No-argument invocations fail before package operations. After the package operation, each tool it installed or updated installs its Skill for the selected agents; the row's skill reports the result.

Doctor checks tools declared by the workspace and dependencies of providers active in the selected environments. Bundled tools the workspace does not use are still checked on request with doctor --tool <name>; their absence does not make an unrelated workspace unhealthy. The toolchain itself spans every environment the manifest declares, because installation is machine-wide, while doctor narrows its checks to the environments in scope. A disabled dependency of an active provider remains an incomplete requirement, not a passing check. Init and sync use the same relevant tool scope. Missing optional tools remain visible without blocking preparation. An enabled install_on_init tool must be verified; a disabled optional tool does not become required merely because that installation flag is set.

The bundled Sentry tool can be installed with npm (sentry), including during init when the manifest opts in.

Shared service settings and personal credentials

A manifest can declare public service settings such as URLs, contexts, organizations and authentication methods. init, explicit sync and login prepare them through the companions' own commands; background hooks only check. The declared authentication method is the default for a context fx creates. If your own context already reaches the declared service, it is ready however you signed in. Preview service changes with fx sync --only services --dry-run.

Configuration and authentication are separate. Each member obtains and stores credentials through the companion CLI. Existing conflicting settings are preserved and reported for review; sync never signs in or activates another context. It does associate a login you already have for the same service with the workspace's context, on every run, so there is nothing to remember after you sign in elsewhere. Sentry uses public workspace .sentryclirc defaults and preserves foreign files.

In sync results, inspect stages.services and stage_details.services.items (sync.* for init). Default JSON retains blocked/failed rows; --details also shows successful rows. See service presets for the declaration format and response contracts for recovery details.

Tool installation history

fx tool history --format json
fx tool history bitbucket-cli --format json
fx tool inventory --format json

init, tool install and tool update record attempts in $FX_HOME/tool-history.json. installed means the package manager succeeded; version verification can still fail. A lone started record does not establish success. Dry runs and init's skipped existing tools create no records.

Inventory separates installation origin from the definition source shown by tool list/show:

Requirements cover all workspaces registered in this FX_HOME, including enabled optional tools and bundled defaults. Only a confirmed fx installation with no remaining requirement can be unused. The suggestion is advisory: unregistered projects and other FX_HOME directories are outside this check. sync and doctor never uninstall packages. Unreadable manifests or incomplete evidence cannot establish that removal is safe.

Inspection does not adopt PATH tools or reconstruct older installation history. See inventory fields and local data for details.

Skills

The bundled fx-workspace Skill teaches agents to use fx. It can be read without installation or a registered workspace:

fx self info --format json   # bundled_skill and bundled_skill_version
fx skill show               # print the bundled SKILL.md
fx skill status             # installed copies and their versions

To make a copy discoverable by a host, use fx skill install --agent codex. --project targets the current directory; --dir ./custom-skills targets an independent directory and excludes --agent and --project. Standalone Skill commands choose their own targets, independently of workspace agent selection. See the Skill reference for detection, replacement and uninstall behavior.

Explicit skill install refreshes recognized copies to the invoking CLI version, including same-version repair or replacement of a newer copy. skill update refreshes only recognized copies older than the invoking CLI, in every agent's directory, and installs none; self update runs it from the newly installed fx. init/sync reuse same-version copies and never downgrade newer ones. Foreign replacements require confirmation and backup. Uninstalling a copy does not unselect its host, so later sync may install it again.

skill status reports installation versions and activation: unverified. An installed file is not proof that the host loaded it. Read the bundled guide when needed.

Team Skills live in the manifest's skills/ tree. Init/sync link that tree into selected hosts and generate a catalog in the root AGENTS.md. Start at the workspace root; child-repository discovery is not guaranteed. Refresh with fx sync --only docs,skills. Never install the bundled companion through a shared team Skill link; use a user copy or an independent directory.

Team MCP and rules

Harness declarations project owned MCP entries and rule pointers into selected hosts. Secret values remain environment references. mcp list/show and can mcp:<name> explain prerequisites; a correct configuration does not prove native host activation.

Workspace lifecycle

Managed hooks may return cached context and schedule manifest/docs/Skills refresh at session start. They do not sync business repositories or approve trust. Native project and hook trust remain owned by the host. Use hook list, hook enable and hook disable; host activation explains the unverified states hook list reports.

Shared source contributions

source push previews or submits selected source changes while preserving the source checkout's HEAD, index and working files. It requires evidence of a personal fork and its upstream relationship, and a manifest source hosted on Bitbucket or GitHub. Inspect fx source push --help and the command reference before an actual submission.

Commands

Daily workflows remain top-level; resource operations live under a noun. Use fx <topic> --help for canonical commands and compatibility aliases. Flags describe whether they accept repeated or comma-separated values. select takes space-separated names; init's --repos takes a comma-separated list.

list/show discovers resources; select replaces a selection; pick/unpick adds/removes selected names; add/remove changes local registration. Bare topics show their available commands. Unknown commands and invalid selectors produce structured errors. The generated CLI reference owns the full syntax and flags.

Integrations

The manifest chooses which providers and companion tools a workspace uses. Run fx manifest providers for what each capability is bound to in your workspace, and fx tool list --catalog for every companion tool fx knows, including those nothing here selects. Communication and knowledge entries hand off to companion tools; fx does not proxy every service API.

Agent discovery includes Claude Code, Codex CLI, Cursor and other registered hosts. Skill delivery, hooks, MCP and rules have different support per host. Use fx agent list, fx hook list and fx mcp list to inspect the relevant capabilities instead of assuming feature parity.

For coding agents

Start with fx self info --format json. For initialization, read the returned initialization_guide; it is the short route from a source and directory to a verified workspace. Keep the exact executable prefix. The full Skill covers other tasks.

stdout contains results; stderr contains progress, notices and structured errors. Use --format json and capture both streams. Workflow JSON keeps the preparation verdict and every blocker; --details adds full stage evidence. Human output starts with the task result and next action. Human release check output opens each repository with what it would ship: the version its target branch declares, the head commits of both branches, and how many commits on the source branch are not merged into the target yet. The opening counts distinguish failed, warning, incomplete, passed and not-applicable checks. Confirmed problems appear under their repositories; identical unavailable or partial checks are grouped with their affected checks, repositories and recovery. A known failure can also be incomplete. Only repositories whose checks completed without problems appear in the completed section; explicit exclusions are counted separately from passes. --details expands every repository's checks. Incomplete reports without confirmed failures emit RELEASE_INCOMPLETE, while JSON keeps its existing ok/complete semantics and retains structured query failures. A missing error-tracker project is reported as incomplete rather than querying all projects. On a terminal, human output adds colour and symbols, fits tables to the width and prints an error as text; a pipe or a file receives plain text and the JSON error envelope, and NO_COLOR removes the colour. While a command works, the terminal also shows one status line with the time elapsed, how far counted work has come and what it is waiting on; the line disappears when the command ends, and a pipe, a file, JSON output and --quiet never receive it. While git or an installer runs, which may ask for a host key or a passphrase on the same terminal, the line is printed every five seconds instead of being redrawn. --fields projects the complete report in any format, using flat keys for dot paths, for example:

fx sync --format json --fields operation,preparation.state,items,summary

Release versions prefer the root VERSION file when present on the source branch; the selected file is read at both branch heads. Its text is trimmed, and an empty declaration stays unknown. Without VERSION, fx uses the existing dependency-file version lookup (for example, package.json). Dependency checks still read dependencies.

For a release's error window, use a relative duration or an explicit pair of timezone-qualified instants. Absolute ranges include the start and exclude the end; use the following local midnight to include a whole day. For example:

fx release check fx-example-api --from 2026-04-01T00:00:00+08:00 --to 2026-04-15T00:00:00+08:00 --format json --details
fx repo version fx-example-api --ref main --baseline v1.2.0 --format json
fx repo version fx-example-sdk --path packages/client/package.json --format json

Version evidence pins refs to commits, identifies the actual declaration field and finds its last value change along the first-parent history. A dependency-only edit does not count. A historical baseline compares everything since that ref; it is separate from commits not yet merged into the release branch. A source version or its modification time does not prove publication. Missing history or an exhausted history budget returns partial evidence with a reason. The CLI reference covers the options for adding this evidence to a multi-repository release check and selecting package paths.

Automatic version-evidence discovery skips dependency-only files such as requirements.txt. A supported version source that is present but unreadable leaves evidence incomplete instead of silently selecting another package; Gradle can use adjacent gradle.properties. Maven supports literal versions or a single ${property} resolved to a literal in the project's properties. Composite, nested or unresolved expressions return VERSION_DECLARATION_UNREADABLE with incomplete evidence.

Sentry evidence retains collected candidates that matched an unresolved query and were active in the window, including older issues. It keeps lifetime first-seen separate from list/window dates. A later resolved or ignored status remains in the audit evidence and is excluded from the fresh-issue verdict. Pagination or metadata failures remain explicit; partial evidence does not prove that no issue exists. Status and assignee describe the time each response was read, not the historical window. Event counts have unknown scope and are not counts of newly introduced events. The error verdict counts lifetime first appearances; deciding whether an old issue regressed is a separate review.

repo show also returns ownership_evidence: repository-linked business scopes, people, teams and collective responsibilities. Its date filter evaluates declared intervals in the current members document; it does not restore a historical snapshot or choose an assignee.

Ready preparation exits 0; incomplete preparation exits 12. Preview is only a plan. Fatal configuration/execution errors retain their category exit codes and may include partial stdout. doctor.coverage describes diagnostic coverage separately; optional native activation can remain unverified without blocking required work. A projection file alone does not establish host activation.

Release reports still exit zero when produced. ok means no failed check and complete means complete check coverage. evidence_complete also includes the requested repository facts; inspect facet_coverage and failures when it is false. observed_at is the command's start time. Each repository records its normalized range; the top-level range is null when repository policies use different windows.

Init executes authorized local preparation itself. Completed setup steps stay visible in the result; do not repeat them while authentication is pending.

When capturing output for further analysis, use a location inside the authorized task directory; Read-only posture cannot control shell redirection.

Read preparation.next first: review a preview, continue the original task when complete, perform Agent actions, or hand off missing prerequisites. next_actions contains Agent work only; personal actions stay on their blockers with actor: user. Run resume after conditions change.

Read all preparation.blockers together. next_actions provide exact argument vectors, working directories, optional environment coordinates and approval requirements. Preserve the returned argv, cwd and env; resume continues the registered workspace. Existing approval persists; new vectors need review. Never infer success from registration or a clone, repeat a write to obtain more detail, or copy personal credentials into a manifest.

For file conflicts, stage_details.docs.files (under sync in init) preserves completed and unstarted writes. Foreign replacements require approval and retain a sibling backup. See the response contracts.

Configuration

What lives in ~/.fx

Global configuration registers workspaces and preferences. Each workspace has its manifest checkout, personal layer and owned projection state. Trust records and caches stay on this machine. FX_HOME relocates fx's personal directory without changing where companion tools store credentials.

Settings

Use fx config list for the complete settings catalog, including default values, environment names and effective sources. fx config get <key> --explain shows applicable layers. Explicit flags override environment, file and built-in defaults; get/list describe the same invocation. config export/import transfers a profile. Import merges workspace registrations by name and retains registrations absent from the profile. It replaces named personal layers, but refuses to change an existing workspace's root or source: use workspace relocate or workspace rebind first. Use workspace unregister to remove a registration deliberately. The import plan lists registrations and preparation still needed; missing manifest checkouts are restored with the printed init commands. Export does not copy manifest checkouts, trust or credentials.

format controls result format. command_shell controls generated command text, not execution: auto chooses PowerShell on Windows and POSIX elsewhere. Override it with --command-shell or FX_COMMAND_SHELL; cmd users can set it to cmd. Manifest-authored shell templates remain verbatim, and canonical evidence/trust identities do not change with presentation.

Shell completion is opt-in. For example, PowerShell users can generate a script and dot-source it in their own profile:

fx.cmd completion powershell | Out-File -Encoding utf8 "$HOME\fx-completion.ps1"
. "$HOME\fx-completion.ps1"

Bash, zsh and fish are also available through fx completion <shell>.

Agent selection

fx config set agents codex selects specific hosts; fx config set agents '' selects none. An empty FX_AGENTS also selects none. Unset both overrides to restore detection. Selection is global across workspaces in this FX_HOME. FX_HOME relocates fx state, not global Skills or companion credential storage.

Reading initialization and recovery results

Follow the continuation action in the result. If new source input was rejected before acceptance, it returns the full original retry; otherwise resume uses the managed source and existing selection. Registration and written files are effects, not completion. preparation.state and its blockers own that decision.

Source validation identifies invalid fields before workspace effects. A local preview inspects directories, stdin or committed Git contents; a fresh remote source remains source_inspected: false until acquired. Known guide conflicts and planned command vectors are shown before application; no preview grants trust. Plain source guides are supported: missing fx regions are appended to generated target guides, preserving source prose. Ambiguous markers require source repair.

Completed repositories, local preparation and user files survive a partial failure. Resolve all reported prerequisites, then use the returned action. Existing installs and successful setup checks are skipped on continuation. Relative verification files are resolved from the workspace root. Names are generated for directories with spaces or Unicode; use the returned workspace identity instead of guessing it.

SKILL_WRITE_DENIED identifies the protected path. Changing FX_HOME does not move global Skill locks. Available repository/guide work can continue with fx sync --only repos,docs --no-refresh-manifest, without claiming Skill repair. Foreign replacement still requires approval and preserves a sibling backup. Git-source refresh protects local work, and ordinary retries recheck repository readability. Support explains discovery and updates.

Resume login after a handoff

Use doctor --tool <name> for a focused diagnosis: only that tool's installation and setup are checked or repaired. It does not refresh unrelated repositories, guides or host resources. Omit --tool for the full workspace check. If an executable/version check fails, dependent command checks wait for that prerequisite; this does not mean the person needs to sign in again.

can and checked where results include execution.binary_path, version and cwd for an inspected tool. Use that path and working directory in later calls: another shell may resolve the same name to a different installation. Provider commands and direct handoff vectors are bound to it; manifest shell templates remain verbatim. tool install/update reports binary_path with version_after. Recheck readiness and reload the matching companion Skill after an update.

Preparation readiness does not guarantee every API permission. Verify the operation you need before requesting more access: inability to search does not prove that a known document cannot be read. Sentry instances without device OAuth can declare service.auth_scheme: token; fx then hands over personal token setup and still accepts an already authenticated CLI. Never put the token in the manifest or chat.

When login needs human input, complete the authorized handoff and repeat the same invocation. fx checks current state before rerunning actions; then recheck the original can or doctor query and continue your task. Like init and sync, login runs the bundled step that reuses an existing login without asking, even with --no-input; it asks before a sign-in.

Machine callers must read partial stdout even after a nonzero exit, alongside the error on stderr. Completed steps remain visible; handoff, blocked, failed and not_started distinguish the remaining work. See the login response contract for summaries, plan problems and per-step recovery fields.

A step handed over says what its check answered. Its check carries the tool's own message and, where fx can read the failure, the cause: authentication that was not established, a permission the service refused or a connection that could not be completed. The step's instructions then describe what resolves that cause, so read them before signing in again. Most checks name no cause; go by the tool's message and the step's guidance then.

A check that gave no answer, because its tool did not start or it ran out of time, is never handed to a person. can and where list it as unfinished and answer unknown when nothing else failed; login stops with that error and keeps the partial result on stdout; doctor reports the finding with incomplete coverage. An earlier fx omits these fields; fx doctor --tool <tool> --env <env> shows the tool's message for one tool.

Skill ownership and host activation

Bundled user Skills are shared across workspaces and protected by a user-wide lock. Team Skill links belong to their workspace; companion installers own their own version behavior. A matching file alone does not prove native activation.

Inspect hook list for supported and unverified states. In the tested Grok 1.0.25 host, project hooks require a Git root; normal directory trust does not enable them at a plain workspace root. Use explicit fx sync --only docs,skills, and keep the workspace root a plain directory. Host execution approval remains independent of fx.

Reuse a login you already have

Initialization keeps the team's context names. Compatible companion CLIs match an existing login to the same service and reuse its identity before asking you to sign in. Tokens stay in the companion's credential store, and your current context and existing identities are preserved. If several identities match, choose a source with the companion's auth reuse --from-context command; network or keychain failures are diagnosed separately from missing credentials. Environments may share a stored login: when fx login signs you in for one of them, it checks the tool's earlier environments it could not finish again, and reports those that now work as verified.

Member relationships

Discover filter values with fx member selectors, optionally --kind area, scenario, team or function. Each row returns its kind, ID, name and parent area without listing people. A scenario used as an area returns explicit queries for its actual parent areas. Missing account keys remain unknown. Responsibility data is evidence for a proposal, not permission to replace an existing work-item owner.

Use fx member show <account> --system <system> --area <id> --format json to look up an author in context. Require one exact identity match. Read directory memberships, responsible teams for the business, and the person's assignments separately. Multiple confirmed teams can apply. Candidates need verification and missing coverage stays unknown. With no area, show returns all applicable relationships.

Use fx member list --team <id> --function <id> --area <id> to find people doing that work. All supplied dimensions must match one assignment. Without business scope, a directory membership can also match. Use --as-of YYYY-MM-DD for declared validity on a particular date.