felt

Documentation

felt keeps the durable trail that builds up around work. You record each entry as a fiber. Each fiber owns a directory under .felt/, holding a <slug>.md file with YAML frontmatter and a plain-markdown body. A fiber can carry a task, a decision, a research claim, a question, or a spec.

The directory tree gives hierarchy. [[wikilinks]] in bodies give narrative cross-references. Native metadata stays small — name, status, tags, timestamps, outcome, due, description. felt preserves any other top-level YAML key opaquely, so another tool can own its own schema without felt claiming it.

felt computes back-references, reverse data-flow consumers, and body search from the markdown tree on demand. Your markdown holds everything, so felt adds no authoring burden and diffs like the rest of your repo.

felt gives AI coding agents persistent memory, as much as it gives you one. It ships one plugin that installs into both Claude Code and Codex. The plugin bundles the felt and shuttle skills, and makes .felt/ the thing an agent reaches for between sessions.

A fiber on disk, at .felt/covariance-estimation/covariance-estimation.md:

---
id: 01KTC9C1G1CBJ84H6WB92J8A13
name: Covariance estimation
status: closed
tags: [methods]
created-at: 2026-01-15T10:30:00Z
closed-at: 2026-01-16T14:20:00Z
outcome: "Jackknife covariance, 10x faster than analytic, <2% bias at all scales"
---

Tried analytic first — too slow for the number of bins we need.
Jackknife on 150 patches gives a stable diagonal and off-diagonal.

See also [[use-des-y3-weights]].

Install

curl -fsSL https://raw.githubusercontent.com/cailmdaley/felt/main/install.sh | sh  # release binary
brew install cailmdaley/tap/felt                                                  # Homebrew
go install github.com/cailmdaley/felt@latest                                      # from source

The install script needs only curl and tar. It supports macOS and Linux on x86_64 and arm64. It installs to /usr/local/bin if writable, else ~/.local/bin; override with FELT_INSTALL_DIR. If claude or codex is on your PATH, it also registers the felt plugin for them. Later, felt update refreshes both the binary and the plugin wiring.

Quickstart

felt init                                            # create .felt/ in this project
felt add covariance-estimation "Covariance estimation"
felt edit covariance-estimation -s active            # status is opt-in
felt edit covariance-estimation -s closed -o "jackknife — 10x faster, <2% bias"
felt show covariance-estimation                      # body, metadata, back-references
felt tree                                            # containment hierarchy
felt ls -s all "jackknife"                           # search names, outcomes, frontmatter
felt setup claude                                    # install the Claude Code plugin

Shuttle

The same repo ships Shuttle, an optional orchestration layer. Add a shuttle: block to a fiber's frontmatter to turn it into a constitution — a spec of a desired state. An Elixir/OTP daemon polls your felt stores. It launches one tmux worker per eligible constitution, and serves a kanban board at http://127.0.0.1:4000/ for watching and steering them. Workers stay attachable. Each one rewrites the fiber's outcome and ## Status on exit, so the next worker lands warm.

Configure Shuttle from your home directory. ~/.config/felt/agents.json layers your agents over the built-in set (felt shuttle agents init seeds it). ~/.config/felt/remotes.json lists the remote daemons a hub aggregates (felt shuttle remotes add). Linux and macOS both run a single host — daemon, board, and workers — with the keep-alive installed as a systemd user unit or a launchd LaunchAgent. Multi-host tunnel management (felt shuttle tunnels) is macOS-only. The daemon ships as a checkout you build, not a release binary. felt works without the daemon. Full list: Honest scoping.

Documentation

Everything deeper lives at https://cailmdaley.github.io/felt/:

• concepts — fibers, stores, nesting, wikilinks, outcomes, frontmatter ownership
• the full command reference and flags
• agent integration — one plugin for Claude Code and Codex, its hooks and bundled skills
• Obsidian compatibility — open a .felt/ directory directly as an Obsidian vault
• the Shuttle layer — constitutions, dispatch, the board, the HTTP API
• installing and operating the daemon, including its sharp edges

Contributing

See CONTRIBUTING.md to get set up, and AGENTS.md for the architecture, build and lifecycle, deploy path, and invariants. Issues and pull requests are welcome.

License

The felt CLI and the board UI are under the MIT License. The Shuttle daemon (lib/) contains code derived from OpenAI's Symphony under the Apache License 2.0, preserved in NOTICE.