felt¶
felt tracks the durable trail that builds up around work, from the command line.
Each entry — a fiber — lives in its own directory under .felt/. The
directory holds a <slug>.md file with YAML frontmatter and a plain markdown
body. File a fiber for a task, a decision, a question, a finding, a spec, or a
reference doc. Nest the directories to build hierarchy. Write [[wikilinks]]
in bodies to cross-reference.
felt computes back-references, reverse consumers, and body search from the markdown on demand. So the store stays readable, greppable, diffable, and yours.
felt add covariance-estimation "Covariance estimation" -s open
felt edit covariance-estimation -s closed \
-o "Jackknife on 150 patches — 10x faster than analytic, <2% bias"
The trail and its readers¶
Work leaves a trail: the thing you decided, the reason you rejected the other option, the number you measured at 2am. Issue trackers want tickets. Notes apps want a silo. Neither survives contact with a coding agent, which needs the trail in a form it can read and write without a special client.
felt takes the boring option. Plain markdown files in a directory next to the code. That keeps the store legible to three readers at once:
- You, with any editor. A
.felt/directory opens as an Obsidian vault — the wikilinks and graph view work because the format matches. - Your tooling, with
grep,git, and thefeltCLI. - Coding agents, which read and write fibers through the same CLI you do. felt ships a plugin for Claude Code and Codex so agents see the active fibers at session start and file what they learn before they exit.
felt treats that last reader as a design constraint, not an afterthought. Agent sessions end. The fiber tree carries context to the next one.
Metadata stays small on purpose. Everything except name is optional. status
is opt-in. felt preserves any frontmatter key it does not own, so downstream
tools can layer their own schema without felt claiming it.
felt and Shuttle¶
This repository builds two things.
felt gives you the CLI and the data model. Most people need nothing more.
It runs with no daemon, no server, and no runtime dependencies. Only felt
update and felt setup reach the network, and they fetch from GitHub on
demand; the store itself never leaves your disk. If you want a fiber tracker
and agent memory, you can stop at felt.
Shuttle adds an optional orchestration layer on top. Give a fiber a
shuttle: frontmatter block and it becomes a constitution — a spec of a
desired state. An Elixir/OTP daemon polls the tree. It launches one tmux worker
per eligible fiber, and serves a kanban board at http://127.0.0.1:4000/.
Workers hand off to each other through the fiber, so a piece of work can span
many sessions.
Shuttle stays the more experimental half, and it is currently fleet-oriented — it runs the maintainer's machines every day, and parts of it still say so. See Honest scoping for the full list. Ignore Shuttle and felt behaves the same.
Where to go next¶
| If you want to | Read |
|---|---|
| Install the CLI and file your first fiber | Getting started |
| Understand the fiber layout on disk | Fibers |
| Learn statuses, nesting, outcomes, wikilinks | Organizing |
| Carry your own YAML alongside felt's | Frontmatter |
| Attach plots, PDFs, and HTML reports to a fiber | Companion files |
| Search across every project at once | Cross-project stores |
| Wire up Claude Code or Codex | Agent integration |
| See the orchestration layer | Shuttle |
| Look up a command | CLI reference |
License¶
The felt CLI and the board UI ship under the
MIT License. The Shuttle
daemon (lib/) contains code derived from OpenAI's Symphony under the
Apache License 2.0,
preserved in NOTICE.
Contributing¶
Source and issues: github.com/cailmdaley/felt. To build or patch felt, read CONTRIBUTING.md for the setup, and AGENTS.md for the architecture, build and lifecycle, deploy path, and invariants.