felt
A CLI for the structured trail that builds up around work — decisions made, alternatives rejected, claims under test, tasks open, fragments waiting to consolidate. Each entry is a fiber: a directory under .felt/ with a <slug>.md file inside, carrying YAML frontmatter and a plain-markdown body.
The directory tree gives hierarchy. [[wikilinks]] in bodies give narrative cross-references. YAML frontmatter holds structure (status, tags, decisions with excluded alternatives, inputs, insights), accreting as a fiber crystallizes. A rebuildable SQLite index at .felt/index.db makes the lot queryable — FTS5 over bodies, narrative back-references, reverse data-flow consumers — but plain markdown is the source of truth and the cache carries no extra authoring burden.
Felt round-trips arbitrary YAML, so tool-owned namespaces (shuttle:, or anything else a downstream tool wants to attach) survive edits unchanged. A .felt/ directory opens as a valid Obsidian vault out of the box (see Obsidian). The binary is a single static Go executable; no daemon, no required configuration.
Felt is designed to be persistent memory for AI coding agents as much as for you. The bundled Claude Code plugin and Codex hooks make .felt/ the substrate agents reach for between sessions.
Install
curl -fsSL https://raw.githubusercontent.com/cailmdaley/felt/main/install.sh | sh
Installs to ~/.local/bin by default (or /usr/local/bin if writable). Override with FELT_INSTALL_DIR.
Also available via Homebrew (brew install cailmdaley/tap/felt) or from source (go install github.com/cailmdaley/felt@latest).
Update to the latest release:
felt update
Agent setup
Felt ships as a Claude Code plugin and a Codex skill bundle:
felt setup claude # registers cailmdaley/felt marketplace, installs the plugin
felt setup codex # symlinks skills into ~/.agents/skills, configures Codex hooks
setup claude registers the felt marketplace from GitHub directly — Claude Code clones it, no local checkout required. Tagged felt binaries pin the plugin to the matching tag so the binary and the plugin stay aligned. setup codex reuses that clone for its own hook setup, so just running the two commands above is enough.
The plugin bundles two skills (felt, ralph), a SessionStart hook that lists active and recently touched fibers, and a PreToolUse hook that gates the first non-Skill tool call until the felt skill has been activated. See Agent Integration for details.
Quick Start
felt init # creates .felt/ support files
felt add use-des-y3-weights "Use DES Y3 weights" # file a decision
felt add covariance-estimation "Covariance estimation"
felt edit covariance-estimation -s closed -o "switched to jackknife — 10x faster, <2% bias"
felt history covariance-estimation # append-only event log per fiber
A fiber can be anything: a task, a decision, a research claim, a question, a spec. The body carries detail, wikilinks cite related fibers, and the outcome captures the conclusion.
felt show covariance-estimation # inspect one fiber
felt tree # containment hierarchy
felt ls -s all "jackknife" # search across everything
Fibers
A fiber is stored as .felt/<path>/<slug>.md. For example:
---
name: Covariance estimation
status: closed
tags: [pure-eb, 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 stable diagonal + off-diagonal.
See also [[use-des-y3-weights]].
IDs are slug paths such as covariance-estimation or bao-analysis/damping-prior. Bare slugs resolve when globally unique, so felt show damping-prior and felt show bao-analysis/damping-prior both work when unambiguous.
Status
Status is opt-in. Most fibers don't need it. Add -s open when something needs tracking.
· untracked just a fiber
○ open tracked, not started
◐ active in progress
● closed done — outcome captured
Tags
