Working with Agents¶

felt ships as a plugin for Claude Code and Codex. The plugin makes an agent fiber-aware. It shows the agent the active fibers at session start. It nudges the agent toward felt instead of raw file edits. It keeps fiber timestamps honest when the agent edits a fiber file directly.

Requirement: `felt` on `PATH`¶

Every hook shells out to the felt binary. If the agent's process doesn't have felt on PATH, the hooks fail quietly.

In a terminal-launched session this is usually fine — your shell's PATH carries over.
A GUI-launched agent (no shell profile sourced) can miss ~/.local/bin or wherever felt landed. If SessionStart context never shows up, check PATH first.
The daemon has the same requirement server-side: a PATH missing felt turns into 500s on the board's fiber endpoints, so the board loads but the kanban stays empty.

Installing the plugin¶

felt setup claude    # Claude Code
felt setup codex     # Codex

Both wrap the official plugin-marketplace flow:

# Claude Code
claude plugin marketplace add cailmdaley/felt[#v<tag>]
claude plugin install felt@cailmdaley-felt

# Codex
codex plugin marketplace add cailmdaley/felt[@v<tag>]
# then config.toml: features.plugin_hooks = true, plugins."felt@cailmdaley-felt".enabled = true

Neither needs a local checkout — the CLI clones the marketplace straight from GitHub. A tagged felt binary pins the plugin to the matching tag; a dev build tracks the default branch, so the plugin content always matches the binary that installed it.

Both commands are idempotent, so re-running is safe. Both take --uninstall to remove what they installed. felt uninstall clears both harnesses at once, and serves as the general inverse.

install.sh (the curl installer) runs both commands automatically for whichever CLI it finds on PATH, with no opt-out flag — see Getting started.

Skills only¶

felt setup skills [--target <dir>]

Symlinks felt's skills into a directory without touching the plugin marketplace — ~/.claude/skills by default. Useful if you want the skill content without the hooks.

Plugin contents¶

One plugin directory serves both harnesses. It bundles two skills and four hooks.

Skills¶

felt — the substrate practice: filing fibers, updating outcomes and bodies, additional YAML fields, session mining, maintenance passes.
shuttle — the dispatch practice: authoring constitutions, worker dispatch, operating the board. Only relevant once you're using the optional Shuttle layer.

Skills activate the way any Claude Code / Codex skill does — by the harness matching the user's request against the skill's description. felt setup skills (above) links these into your skills directory independent of the plugin.

Hooks¶

Hook	Event	Effect
`session.sh`	`SessionStart`	Wraps `felt session`'s plain-text context (active + recently-touched fibers) in the harness's `additionalContext` envelope
`remind.sh`	`PreToolUse`	Gates the first non-skill tool call in a felt-enabled project until the felt skill has activated this session; a pass-through everywhere else
`touch.sh`	`PostToolUse` (Edit/Write/MultiEdit)	Stamps a fiber's `updated-at` when the agent edits its markdown file directly, so hand-edits count toward recency the same as `felt edit` does
`event.sh`	`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `SubagentStop`, `Notification`, `SessionEnd`	Appends one JSON line per event to the Shuttle event stream (`~/.shuttle/events.jsonl`), which the daemon reads for activity ranking and the sent-files trail; writes nothing unless `~/.shuttle` exists

The logic lives in the binary, not the script. remind.sh, touch.sh, and event.sh each shim a single line over felt hook pretool, felt hook posttool, and felt hook event. session.sh wraps felt session with a jq -Rs pipeline, and falls back to felt hook session when jq is absent.

Note

Updating the binary updates hook behavior. felt update (and Homebrew's post-install) refresh the binary and the plugin wiring together, so hooks always run against a matching binary. You only need to re-run felt setup claude/codex when the skill content changes, not when hook logic changes.

Full CLI surface¶

See the CLI reference for every felt and felt shuttle verb.