fx — the harness as one binary

Three scopes — a global ~/.fx/AGENTS.md, the workspace chain, and target-scoped files — but the resolution is the interesting part: instructions are not assembled once into a system prompt, they are resolved per tool call. “When a tool targets a path, fx resolves the instruction chain for that target,” narrowest scope winning, so an edit under apps/web/src/ carries that package's rules and a sibling edit does not. The layer answers its own limitation: passive text becomes delivered text, chosen by what the tool is about to touch.

The usual channels, hand-rolled: list, glob, grep, ranged read, file_info, plus web_search and web_fetch as first-party tools rather than an MCP afterthought. semantic_search is honest about being lexical repository search despite the name. Additional workspace directories can be granted for tool access, and they deliberately do not contribute AGENTS.md — reach is widened without letting a second repository start giving orders.

Two mechanisms, both stated as numbers rather than heuristics. Compaction fires after eight completed turns, keeps the latest four verbatim, and condenses everything earlier into a record of requests, outcomes, tool and file evidence, background work, and interruptions — changing only what the model receives, never the saved transcript. Beneath that, every context source carries a declared byte budget in settings: 128 KiB for all project instructions, 16 KiB for the skill catalogue, 1 KiB per MCP tool description, 64 KiB for a selected schema. You can raise one for a single run, or set it to off and still meet a 64 MiB emergency ceiling.

Roughly twenty-five built-ins across files, shell, web, skills, subagents, memory and MCP, all compiled in. The MCP client is where the architecture shows: servers come only from ~/.fx/mcp.json, never from the repository, so cloning a project cannot hand the agent a new tool. Discovery is lazy in two steps — mcp_search_tools then mcp_select_tool — with selected tools namespaced and sanitised against collisions, which keeps a large server off the prompt until the model asks for it.

Permissions and sandboxing are deliberately separate axes, and only one of them is portable. Rules live in settings with wildcard matching, last match wins, workspace over user-global; modes are ask, auto and yolo. The default, auto, puts a second model in the loop — an unresolved call is sent for automatic review on a separate Gateway request using openai/gpt-5.4, independent of the agent's own model, falling back to human approval when that review is unavailable. The sandbox axis is thinner: os exists on macOS only, so on Linux auto resolves to none and the boundary is policy plus reviewer, with no kernel behind it.

Sessions are files under ~/.fx/sessions/, resumable by picker, by id, or as last — which stays workspace-scoped while an explicit id can be rebound to wherever you are now. Compaction is explicitly non-destructive to that record. Two smaller distinctions carry weight: /undo reverses the most recent tracked file operation, and background processes are treated as session state with their own lifetime rule — /clear starts a new session and keeps them running, /reset starts a new session and forgets them.

The loop exposes four typed lifecycle points and they are not decoration. PreToolUse runs before validation, permissions and execution, and may pass a call through, rewrite its arguments, or block it outright. Stop fires on a terminal assistant candidate and can refuse the ending — requesting a synthetic continuation instead, which is the harness deciding the model is not finished. PostTurnEnd and AttentionRequired observe without altering. Long work escapes the turn entirely: run_command launches OS processes that outlive it, managed afterwards through /background.

One subagent tool with six branches — create, inspect, message, relationship, configure, lifecycle — spawning child fx sessions in the parent's workspace with their own model, effort, permission mode, transcript and lifecycle. Children run one-off or persist idle between messages, and the queues between parent and child are durable, so a child works without copying its transcript into the parent's window. The constraint is the good part: “children cannot elevate model-created authority” — a child the model spawns inherits the caller's effective permission mode and cannot ask for more.

SKILL.md directories with YAML frontmatter, discovered at startup and loaded only on invocation — “discovering a skill does not add its instructions to every prompt.” Budgets keep the catalogue honest at 1 KiB per description and 16 KiB overall, with bodies streamed in 20 KiB chunks. The neighbourly detail is the search path: fx reads .opencode/skills/ and .codex/skills/ as well as its own, but managed installs always land in ~/.fx/skills/ because “fx never writes into another agent's directory.” It borrows know-how and declines to leave fingerprints.

Observability is strong and verification is absent, and the sheet should not blur them. /trace produces a private diagnostic trace — carrying prompts, code, paths, commands, model output and possibly secrets, which the docs say to review before sharing — and fx doctor audits workspace, configuration, authentication, resolved startup settings, session state and Git integration without spending a turn. What there is no equivalent of is the language-server fleet on the first sheet of this register: nothing hands the model diagnostics after an edit. Receipts exist only if the model thinks to run the tests itself.

The thinnest slot on the sheet, and the thesis explains why. Two things persist across sessions: permission decisions, promoted to durable rules by /permissions remember and /allowlist; and the memory tool, which is a flat JSON array of strings at ~/.fx/memories.json supporting exactly save, list and clear — user-global, unscoped, unranked, with no decay and no retrieval beyond reading all of it. Everything past those two dials is a recompile, because the hooks that could have carried learned behaviour are compiled-in Zig with no configuration surface.