cd /news/ai-tools/show-hn-dotfactory-dotfiles-for-your… · home › topics › ai-tools › article
[ARTICLE · art-173703] src=github.com ↗ pub= topic=ai-tools verified=true sentiment=↑ positive

Show HN: Dotfactory – dotfiles for your Claude Code sessions

A developer released Dotfactory, a Claude Code plugin that loads a user's saved preferences and registered tools into every session across projects, tested with Claude Code 2.1.330 and requiring version 2.1.287 or later for its side pane. The plugin stores personal configuration in a separate "brain" folder of markdown files — preferences in `prefs/*.md`, tools in `tools/*.md`, and projects in `projects.md` — located via the `DOTFACTORY_BRAIN` environment variable, a `brain` folder next to a checkout's plugin folder, or `~/.config/dotfactory/brain`. It is installed via `claude plugin marketplace add gesposito/dotfactory` and `claude plugin install dotfactory@dotfactory`, and its pane is built on Claude Code's early-access mods API, which the author warns can change between releases.

key takeaway

Dotfactory loads each applicable `prefs/*.md` file and a one-line entry per registered tool at every Claude Code session start, with preferences scoped to all projects or only those containing a marker file such as `Cargo.toml`.

read5 min views1 publishedNov 21, 2026
Show HN: Dotfactory – dotfiles for your Claude Code sessions
Image: Michielbdejong (auto-discovered)

A Claude Code plugin that makes every session, in any project, start with your preferences and your tools in view.

The plugin knows nothing about any language, tool or kind of project. Everything personal lives in a folder of markdown files called the brain, which is yours and is never part of this repository.

The recording runs real commands against a throwaway brain. The walkthrough goes through the same example step by step, with the files each step writes.

What it is Where
Preferences How you like things done. A file applies to every project, or only to projects that have a marker file such as Cargo.toml . prefs/*.md
Tools Anything a session can call on for a job: a repo to run, an expert session to consult, or written notes. tools/*.md
Projects The projects you started with /dotfactory:new . projects.md

A tool is reached one of three ways:

  • Repo: code in a folder. A session reads the entry and runs its commands.
  • Expert: another Claude Code session of yours, with its own knowledge. A session in any project messages it by name with a question and waits for the reply. An expert has to be running to answer, so keep it open or in the background.
  • Notes: steps written in the entry itself.

The same job can be backed differently by different people. One person's naming is an expert session, another's is a page of notes. The plugin doesn't care which.

From GitHub:

claude plugin marketplace add gesposito/dotfactory
claude plugin install dotfactory@dotfactory

Or from a checkout, if you want to change the plugin:

claude plugin marketplace add /path/to/dotfactory
claude plugin install dotfactory@dotfactory

Installed from a checkout, the plugin runs straight from that folder, so edits take effect in the next session.

Tested with Claude Code 2.1.330. The pane needs 2.1.287 or later. It is built on Claude Code's mods API, which is early access and can change between releases; the commands and the session-start note don't depend on it.

The first of these that applies:

  1. The folder named by the DOTFACTORY_BRAIN environment variable.
  2. A brain folder next to theplugin folder of a checkout. This repository ignores it.
  3. ~/.config/dotfactory/brain

The folder is created the first time you save something. Make it a git repository of its own to keep its history.

Say or type What happens
/dotfactory:new Starts a project: applies your preferences, uses the tools you registered for new projects (naming, licensing, anything), scaffolds it and records it. Offered automatically when a session starts in an empty folder.
/dotfactory:remember <preference> Saves a lasting preference to the brain.
/dotfactory:add-tool <path> Registers a repo as a tool.
/dotfactory:add-tool session <name> Registers an expert session.
/dotfactory:add-tool <what the notes cover> Registers written notes for a job.
/dotfactory:status Shows what the brain holds and flags problems.
/dotfactory Opens the dotfactory pane beside the conversation: a button for each command above, then your preferences, tools, projects and any problems. It refreshes when a turn ends.

Claude also runs these when a request matches, for example "remember that I always…".

Every session start also loads, with no command:

  • each preferences file that applies to the project
  • one line per tool: its name, how it's reached and when to use it

A button runs its command right away, with nothing after it, so the command asks for what it needs in the conversation. If a command can't be started for you, it's put in the prompt box instead.

  • Keyboard:/dotfactory opens the pane with the keyboard in it, so type/dotfactory and then a digit:1 new project,2 remember,3 add tool,4 status. Tab and Enter also work.
  • Mouse: click a button. In the terminal this needs fullscreen rendering.
  • VS Code: the digits do nothing there. Click, or Tab to a button and press Enter.

After a press, the keyboard goes back to the prompt so you can answer Claude's question. To leave the pane without pressing anything, press Esc. To move the keyboard into an open pane again, press Ctrl+X then Tab.

The shortcuts are digits on purpose. With letters, a sentence typed while the pane still had the keyboard would press buttons.

A preferences file for one kind of project names its marker files. Without the markers: line, the file applies everywhere.

---
markers: Cargo.toml
---


- Prefer the standard library over a new dependency.

A tool entry:

---
name: naming
description: Proposes names for new projects. Use when a project, repo or package needs a name.
session: namer
---

## What it does
## How to use it
## If it isn't available

Use session: for an expert, path: for a repo, and neither for notes.

plugin/                the plugin
  skills/              /dotfactory:new, :remember, :add-tool, :status
  hooks/hooks.json     runs scripts/session-start.sh at session start, and loads pane.tsx
  hooks/pane.tsx       the dotfactory pane (draws what scripts/pane-data.sh prints)
  types/index.d.ts     the shape of the data the pane keeps
  scripts/             session-start.sh, status.sh, pane-data.sh, brain-path.sh, lib.sh
  tests/pane.test.tsx  tests for the pane
tests/hook.test.sh     tests for the scripts
docs/walkthrough.md    one example, step by step
docs/demo.cast         the terminal recording, in asciinema's format
docs/demo.svg          the same recording as an animated image
docs/demo/             the scripts and the example repo that produce the recording
  • Check after editing: sh tests/hook.test.sh ,claude plugin test plugin andclaude plugin validate plugin
  • Record the demo again after changing what a command prints: sh docs/demo/record.sh , thennpx svg-term-cli --in docs/demo.cast --out docs/demo.svg --window --width 100 --height 32
  • Try the plugin without installing it: claude --plugin-dir /path/to/dotfactory/plugin
  • In a fresh clone, an editor shows type errors in plugin/hooks/pane.tsx until Claude Code has generated its type files inplugin/.claude-plugin/types/ , which this repository ignores. the plugin once in an interactive session generates them:claude --plugin-dir plugin . You don't need them to check your work, becauseclaude plugin validate plugin type-checks the pane by itself.
  • Session-start output is capped at 10,000 characters by Claude Code. The budgets in plugin/scripts/lib.sh keep it under that, so long preferences files get cut. Keep them short.

MIT. See LICENSE.

── more in #ai-tools 4 stories · sorted by recency
── more on @claude code 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/show-hn-dotfactory-d…] indexed:0 read:5min 2026-11-21 · —