fiber

Fiber home

The one directory where Fiber keeps everything it writes outside a repository. Default ~/.fiber on macOS and Linux; FIBER_HOME relocates all of it.

~/.fiber/                         Fiber home
  config.json                     global configuration (docs/configuration.md)
  config/<extension>.json         an extension's global settings
  rules                           global standing rules
  AGENTS.md                       global instruction file (docs/system-prompt.md)
  SYSTEM.md                       replaces Fiber's system prompt text
  APPEND_SYSTEM.md                appended to the system prompt
  projects/<key>/                 one per project
    sessions/<id>/                events.jsonl, session.lock, artifacts/
    history.jsonl                 prompt history, append-only
    rules                         this project's standing rules
    SYSTEM.md, APPEND_SYSTEM.md   this project's system prompt files
    config.json                   this project's configuration
    config/<extension>.json       an extension's settings for this project
    worktrees/<id>/               one git worktree per session that asked for one
    worktrees/<id>.lock           its lock file, held while a process runs in it
    protected-paths/               the protected-path baseline and its two locks (docs/sandbox.md)
    approvals/<content-hash>      one file per extension or hook approval or never
    servers/<content-hash>        one record per MCP server copy this project approved
    data/<extension>/             an extension's data for this project
  extensions/<name>/              installed extensions, one directory each
  docs/                           Fiber's docs for the installed version (docs/releasing.md)
  docs/skills/<name>/             a built-in skill (docs/system-prompt.md)
  themes/<name>.json              a theme (docs/tui.md, "Themes")
  pinned/<content-hash>/          approved copies of code a repository ships
  pinned.json                     size, modification time and hash of each declared path
  data/<extension>/               an extension's data for this machine
  approvals/<content-hash>        one file per MCP server approval or never
  credentials/<name>/<label>       one file per stored provider credential, mode 0600
  credentials/<name>              one file per extension secret, mode 0600
  credentials/hubs/<name>         one device token per hub this client paired with, mode 0600
  credentials/mcp/<url-hash>      one OAuth token per remote MCP server URL, mode 0600
  hub/devices/<device>            one record per device paired with this hub: name, when, token hash
  run/<session_id>                one local socket per running session
  run/hub                         the hub's local socket
  recent.jsonl                    recently exited sessions, a rebuildable index
  cache/models/<provider>.json    discovered model list
  cache/mcp/<server>.json         an MCP server's last tool and prompt lists, and whether it offers resources
  cache/images/<session>-<file>    an image the terminal opened in the system viewer (docs/tui.md, "Images")
  crashes/<id>-<ms>.txt           one report per panic (docs/code-quality.md)
  logs/hub.log, logs/hub.log.1    the hub's diagnostic log and its previous file
  logs/<kind>-<id>.log            one other process's diagnostic log
  detached/d_<pid>_<n>.log        one output log per detached shell command, mode 0600, kept until the person deletes it (docs/tools.md, "Background jobs")

Override

One environment variable, FIBER_HOME, relocates all of Fiber home. It must be an absolute path. An empty or relative value is a startup error, code usage, naming the variable; Fiber never falls back to ~/.fiber. A supervisor that meant to isolate a run and passed an empty value by mistake would otherwise silently share the person's real sessions and credentials.

A missing directory is created, mode 0700. Two Fiber processes share state only by being given the same Fiber home. There is no second, narrower override.

Fiber home is one root under the home directory: no XDG split, no ~/Library.

One person owns one Fiber home. There are no group permissions and no multi-user sharing.

Projects

A project is a git repository, identified by git's shared directory (the common dir). Every worktree of a repository is one project; a separate clone is a different project. Outside a git repository, the launch directory is the project.

~/work and ~/work/fiber and ~/work/lens are three projects. ~/work/fiber and its worktree ~/work/fiber-wt1 are one project. Two clones ~/work/fiber-clone1 and ~/work/fiber-clone2 are two projects.

Clones are never unified. Fiber does not key by remote URL: a clone can have no remote, several, or a changed one. Sessions, prompt history and per-project standing rules are kept per project.

The key is a readable slug of the project's identity path — git's shared directory, or the launch directory outside git — after resolving symlinks. Every / becomes -. Git shared directory /Users/alice/work/fiber/.git becomes -Users-alice-work-fiber-.git. Launch directory /Users/alice/work becomes -Users-alice-work.

A slug can collide (/a-b and /a/b both become -a-b). That is harmless: the key is only a name for humans. session_started records the exact workspace, and the worktree's repository when Fiber made one, and lookup checks the repository when recorded and the workspace otherwise. The log stays the truth (ADR 0001).

Sessions and resume

Launched anywhere inside a repository — any subdirectory, any worktree — Fiber finds that repository's project by asking git for its shared directory, so resuming from docs/ or from another worktree just works. Outside git, only the exact launch directory counts.

A resumed session keeps the workspace recorded on its session_started. Resuming from elsewhere never moves or narrows it. A moved repository or directory leaves its old sessions under the old key.

The session directory is unchanged from docs/events.md:

~/.fiber/projects/<key>/sessions/<session_id>/
  events.jsonl     the log
  session.lock     one writer
  artifacts/       bytes too large to inline

The full output behind a bounded tool result goes in that session's artifacts/.

A fork's, rewind's or workspace move's history follows forked_from on the child's session_started (docs/delegates.md, "Forks"; docs/events.md, "Rewind" and "Change workspace"). When forked_from.project is present, it names the parent's project key and the reader opens projects/<project>/sessions/<session_id>/ directly. When it is absent, the parent is in the child's project. A missing parent fails closed; readers do not scan other projects.

Deleting a session a fork, rewind or workspace move points at is refused unless the person asks for those sessions to be deleted too (docs/invocation.md, "Deleting and pruning"). For a cross-project move, delete and prune read the parent's final moved event: workspace resolves the child's project key, and new_session_id names the child. Nothing deletes a session on its own, except a session that never got a prompt, which deletes its own directory as it exits (docs/invocation.md, "Lifecycle").

What each part holds

Standing rules. A global file at the top level of Fiber home and the project's rules file. Per-project rules live in Fiber home, never in the repository, so cloning a repository can never grant it permissions — the same reason docs/model-routing.md refuses project config that declares a provider.

Extensions. Installed extensions live at extensions/<name>/, one directory each. The <name> is the extension's short name when it has one (docs/extensions.md, "Names"), so the memory extension lives at extensions/memory/. Any other extension's <name> is its git address or local path, slugged the same way as project keys. The two never collide: a slugged git address keeps its host's dot (github.com-…), a slugged local path starts with -, and a short name has neither. Installing or updating writes a fresh directory and renames it into place; a running session keeps what it already loaded.

Docs. docs/ holds Fiber's documentation for the installed version: docs/user/ for a person using Fiber, and the rest for how Fiber works, including the extension API and the built-in skills in docs/skills/ (docs/system-prompt.md, "Skills"). install.sh and fiber update write it from the release's docs archive, so it always matches the binary (docs/releasing.md). Nothing else writes it. The system prompt names this path (docs/system-prompt.md).

Extension data. Each extension has two data directories: data/<name>/ at the top of Fiber home for what it keeps per machine, and projects/<key>/data/<name>/ for what it keeps per project. <name> is the extension's directory name in extensions/, so the memory extension's store is data/memory/. Fiber hands both paths to the extension and creates each the first time the extension writes there. A memory system or an index lives here. A write of Markdown files here takes the permission fast path (docs/permissions.md, "Fast paths"). Nothing in them is session state, so a rewind or fork never touches them (ADR 0001). fiber extension remove deletes an extension's data directories too, asking first in a terminal.

Pinned copies. When a person approves code a repository ships, Fiber copies it to pinned/<content-hash>/: an extension's whole package, with its dependencies and what its install step built, or the files a hook or an MCP server declaration names. Sessions run the copy, never the repository's files. Approving a server declaration also writes a project record at projects/<key>/servers/<content-hash>, naming this project as one that approved that copy. Every approved version is kept until no worktree's files match it, when fiber sessions prune removes it (docs/extensions.md, "Code a repository ships"; docs/invocation.md, "Deleting and pruning"). pinned.json records each declared path's size, modification time and hash, so a session hashes a file again only when one of the first two changed. It is an index: deleting it costs a re-hash and nothing else.

Import receipts. import-claude-code.json and import-codex.json at the top of Fiber home record one completed import each: the source, the time and the counts (docs/configuration.md, "Importing"). Deleting one means the next fiber import for that source runs again.

Approvals. One file per decision about code a repository ships, named by the content's hash; it says whether the decision is approve or never. Deleting it withdraws the decision, and the next session offers the code again. An extension's or a hook's is per project, at projects/<key>/approvals/<content-hash>, as its install is. An MCP server's is per machine, at approvals/<content-hash>, so a declaration approved in one repository is not asked about again in another (docs/mcp.md, "A repository's servers"), and each approving project also holds a record at projects/<key>/servers/<content-hash>, written when the approval is. A never writes no project record, and removes one an earlier approval left. Only a changed declaration or files, or a deleted record, offers approved content again, so a server copy approved before the project record existed has no record, and stays until a new approval writes one. A repository can neither write nor read them.

Credentials. One file per stored provider credential at credentials/<name>/<label>, one per credential label, and one file per extension secret at credentials/<name>, and one file per remote MCP server's OAuth token at credentials/mcp/<url-hash>, named by a SHA-256 of the server's canonical URL and recording that URL, each mode 0600, in 0700 directories. There is no OS keychain. OAuth refresh takes a lock on the credential file (docs/model-routing.md). Every tool call touching credentials/ is refused (docs/permissions.md).

Cache. cache/ holds only what is always safe to delete; rm -rf ~/.fiber/cache is a documented safe reset. Today it holds each provider's discovered model list, one file per provider at cache/models/<provider>.json, fetched and replaced whole, and each MCP server's last tool and prompt lists and whether it offers resources at cache/mcp/<server>.json, keyed by a hash of the server's declaration (docs/mcp.md, "Starting servers"). A writer replaces a file by rename, so two sessions refreshing one list leave one whole file.

Crash reports. crashes/<session_id>-<ms>.txt holds one panic's message, thread name and backtrace, named by the process id instead when the process has no session id, written by the panic hook before the process aborts (docs/code-quality.md, "Panics"). A report describes a bug in Fiber, not a session, so nothing reads one to decide anything, and deleting them is always safe. fiber doctor names the newest one, and fiber feedback copies a session's reports into its report with the panic message left out ("What feedback reads" below). They are pruned with the diagnostic logs.

Diagnostic logs. logs/ records what happens outside any session, where no session log could hold it. It is always on, because the failures it exists for, such as a startup error, happen before anyone would think to turn a log on. Each process writes its own file, so every file has one writer, as a session log does: the hub writes logs/hub.log, and any other process that has something to record writes logs/<kind>-<id>.log, where <kind> is session, ask, tui or cli and <id> its session id once its session log exists, or its process id until then, except a signal before Fiber starts writing fiber_started, which stays pid-named with no session_id. A cli process, a Fiber command that runs once with no session such as fiber mcp login, is always named by its process id, and its lines carry no session_id.

Each line is one JSON object: ts, level (error, warn, info or debug), process (hub, session, ask, tui or cli), session_id when one is known, code and message, one sentence, and on a debug line data, an object of named values. For a failure, code is its code from docs/errors.md. For one of the hub's operations it is the operation's name. This shape is a contract: a program that forwards these lines elsewhere reads these fields.

diagnostics.level (docs/configuration.md, "Keys") sets how much is recorded. At "info", the default, a process writes only the error, warn and info lines below. At "debug" it also writes debug lines; error, warn and info lines keep their shape and carry no data. A process reads the level when it starts, so a changed value reaches new processes only. A debug line holds no credential, token, header value, prompt, model text, tool argument or configuration value. A websocket connection to a hub is not a request and writes no http_request line.

What is recorded:

An event inside a running session is recorded in that session's log and nowhere else, with one exception: a session or ask process's own diagnostic lines, its extension_log, http_request, resources and op_timing lines, are recorded in logs/<kind>-<id>.log beside the session log, never in it; a hook that fails in a session, for example, is a notice or hook_failed there (docs/extensions.md, "When a hook fails"). Nothing in logs/ holds a credential or token, prompt or model text, a tool's arguments or a configuration value, with one exception: an extension_log line is the extension's own text, and Fiber records it as given. A failed hook is named with its code, never its content.

Detached logs. detached/ holds one output log per detached shell command (docs/tools.md, "Background jobs"), named d_<pid>_<n>.log from 0 up in a directory mode 0700, each file mode 0600. The person owns deleting them: Fiber never removes a log, and a session's deletion or pruning never touches them.

What feedback reads. fiber feedback and /feedback copy content-free lines from logs/ and crashes/ into the Diagnostics section of the report file, on the person's machine; the issue link never carries them. For the selected session they read logs/session-<id>.log, logs/ask-<id>.log and logs/tui-<id>.log, in that order, never a file named by process id or a delegate's, and logs/hub.log.1 then logs/hub.log. A line is copied only when it is one JSON object with an integer ts, a level of error, warn, info or debug, the process of its file, and string code and message; a session file's line also names the selected session, and a hub line names it or names no session. Every extension_log line is left out, and so is any line that does not meet this. A hub line also needs a ts no later than now, and unless it names the selected session, no more than 24 hours old. Without a selected session, the report holds hub lines with no session id only.

A report holds the newest 500 hub lines and the newest 2,000 session lines, oldest first, equal times in the order above. The session cap keeps every error and warn line before any other, and if those alone pass 2,000 it keeps their newest 2,000; the report then says how many earlier lines it left out, counting only lines that would otherwise have been copied. Both numbers were chosen, not measured. Each crash report named for the session is copied without a cap, as its first line, which names the thread and the source location, and the text after its last stack backtrace: line: the panic message is dropped, because it can hold anything. A report with no such line keeps only its first line. A session with no lines on this machine, such as one on a remote hub, still gets its id, how to export its log privately (docs/invocation.md, "Deleting and pruning") and the hub lines, with a notice that the machine has no diagnostic lines for it.

Bounds. logs/hub.log is renamed to logs/hub.log.1 when it passes 10 MiB, replacing any older one; its single writer makes the rename safe. Files in logs/ and crashes/ older than 30 days, and all but the newest 100 in each, are deleted by fiber sessions prune and when the hub starts. These numbers were chosen, not measured. Fiber sends nothing from logs/ anywhere (ADR 0010); fiber doctor and fiber feedback read it (docs/invocation.md, "Commands and flags").

Worktrees. Per project, worktrees/<id>/: the git worktree of a delegate started with isolation: worktree, of fiber ask --worktree or of the terminal's new-worktree switch (docs/invocation.md, "Isolation"). When one is removed or kept is docs/delegates.md ("Worktrees"). A kept worktree is removed only by fiber sessions prune (docs/invocation.md, "Deleting and pruning"). A worktree's lock file coordinates a resume's recreation, an end-of-run removal and fiber sessions prune against the processes running in the worktree. Every process that runs in a worktree it did not just create holds the file shared; a delegate's parent holds it shared before creation until the child records session_started after acquiring its own share; a recreation holds it exclusively while it checks and makes the worktree again, and a removal takes it exclusively without waiting, keeping the worktree when another process holds it. The file stays whenever its worktree stays, and goes only after a whole removal, not when only the directory is removed and the branch is kept.

Sockets. run/<session_id> is the local socket of a running session (docs/invocation.md, "Processes"), mode 0600 in a 0700 directory. The hub, a delegate's parent and session messages connect to it; every other client reaches it through the hub. run/hub is the hub's own socket, which local clients connect to; the hub that binds it removes a stale one first. The process holding that session's session.lock owns the session socket while it holds the lock: no other process unlinks it. Before binding, bind in crates/doors/src/socket.rs connects first: a socket the connect reaches is live, and binding fails with session_held. A failed connect removes the path only when replaceable in the same file agrees: a refusal or a missing path is replaceable at once, so a dangling symlink, or one pointing at a stale socket, can be removed by bind; otherwise only a regular file is. When the connect error is neither a refusal nor a missing path, a symlink, or a path whose type cannot be read, may lead to a live session, so the path stays and bind fails with io_failed. Two failure paths unlink after binding: when setting the socket to mode 0600 fails, bind attempts the unlink and returns the error, and the unlink itself can fail; and when the stdout-printer thread fails to start, open_in in crates/doors/src/session.rs unlinks the just-bound socket and returns the io_failed error. At exit, Session::close in the same file unlinks the socket while still holding session.lock, so a held lock does not imply a socket exists. Removing a socket path is implemented twice: remove_socket in crates/doors/src/socket.rs and a separate private remove_socket in crates/hub/src/listen.rs for the hub's own socket. It sits at the top of Fiber home because macOS limits a socket's path to 103 bytes (sun_path[104] in sys/un.h; binding at 104 fails, probed on Darwin 25.6.0), and a path under projects/<key>/sessions/<id>/ exceeds that. Linux allows 107 (unix(7), not measured here). A FIBER_HOME long enough to break the limit is a startup error naming the variable.

Paired devices. hub/devices/<device> holds one record per device paired with this machine's hub: its name, when it was paired, when it last connected, and a SHA-256 hash of its device token, never the token (docs/invocation.md, "Remote clients"). Revoking a device deletes its record. On a client, credentials/hubs/<name> holds the device token for each hub it paired with, mode 0600, under the same credential deny as every other file in credentials/ (docs/permissions.md, "Credentials").

Recently exited sessions. recent.jsonl at the top of Fiber home: one JSON line per session that exited, appended by the session itself as it exits. Its keys are session_id, ts, project (the project's key), workspace, name, how, status, the session's last session_status, which says what it stopped on and carries parent for a delegate, and archived, true on an archived session's row and absent otherwise. A session whose process died cannot append, so the hub appends its row when it sees the crash (docs/invocation.md, "The hub"). Archiving a session appends its row again with archived true, and its next exit appends one without it; a session's newest row is its state (docs/invocation.md, "Archiving"). A session appends whether or not a hub is running, and nothing rewrites it, so an append is never lost to a rewrite. Deleting a session leaves its row, and every reader skips a row whose session directory is gone. The hub reads its tail at start and keeps the newest 100. It grows by about 400 to 600 bytes per exited session: 10,000 sessions is about 5 MB. It is a derived index, rebuildable from the logs, and never the truth (ADR 0001).

Prompt history. Per project, history.jsonl: one JSON line per prompt, append-only. The session appends each prompt a person sends it, in a session the hub started, so every client shares one history; a fiber ask prompt is not appended. Each line holds ts (integer, wall-clock milliseconds), session_id and content, the prompt's content parts as the session accepted them. Up-arrow recalls prompts typed anywhere in that project.

Fiber writes no derived database in v0.0.1. Listing sessions asks the hub, which answers with each running session's latest session_status and the exited sessions' recent.jsonl rows (docs/invocation.md, "The hub"). Any future database is derived from the logs, rebuildable, never the truth.

Concurrent access

Every whole-file write is a temporary file renamed over the old one, so a reader sees the old file or the new one, never half. A file that is read, changed and written back — the config default, standing rules — takes a lock file first. Appends (history.jsonl, events.jsonl) are one line per single write. Readers never lock.

A write that fails before its rename leaves the old file; one that fails after it, while syncing the directory, returns an error with the new file already in place, because every reader already sees it.

One writer at a time per session, via session.lock, is docs/events.md.

Upgrades and versioning

There is no layout version marker. Coordination files that are created on demand and carry no data, such as a worktree's .lock file, do not change the layout, and binaries that do not know one skip it. The first change to this layout adds a file layout at the top of Fiber home containing 2; a missing file means layout 1. fiber update changes only the Fiber binary, extensions/ and docs/; it never touches sessions, config, rules, approvals, pinned copies, credentials or extension data. It replaces the binary by renaming a new file over it, so a running session keeps the file it launched from. How the binary is fetched and replaced is docs/releasing.md.