lodge/backend/internal/client/skill.md

name, description

name	description
lodge	Where to keep agent notes, plans and working docs so they stay out of git but follow the repository across machines and branches. Use when writing plans, notes, research or handoff docs into a repository, when such files seem to be missing from git status, or when you need what was written earlier at a given commit.

lodge

This machine runs lodge. It syncs agent files that are deliberately kept out of git: they are hidden through .git/info/exclude, stored on a separate server, versioned there, and restored automatically after git clone on any machine.

Where to write

Run lodge status inside the repository to see the rules in effect. The defaults are:

• docs/agents/ holds what is true for the whole repository: architecture notes, conventions, research on the codebase. It stays in place when branches change.
• .agent/ holds what belongs to the current branch: the plan for the feature, what was tried, why something was reverted. It is swapped on git checkout together with the branch.
• CLAUDE.local.md is shared across branches.

The rules live in .lodge at the repository root, one per line, as shared <path>, branch <path> or ignore <pattern>. Paths are relative to the root. ignore keeps matching files local to each machine, for editor state and similar noise: the pattern is a glob over the whole path, or over any single name when it has no /, as in ignore vault/.obsidian/workspace*.json or ignore .DS_Store. The file itself is synced too.

Rules of conduct

• These files are absent from git status on purpose. Never git add -f them and never add them to .gitignore.
• Files tracked by git are never touched by lodge, even under a synced path.
• Files over 5 MB are not synced; lodge status lists them.
• A deleted file is deleted on every machine. Its history stays on the server.
• A repository may sync with another server than the rest of the machine; lodge status and lodge remote show which. Never run lodge login, lodge remote or lodge update unless asked: they change where files go.
• Nothing needs to be run after writing a file: the daemon picks it up within seconds. Without a daemon (CI, cloud sandbox) run lodge sync at the start and at the end of the work.

Reading history

• lodge log [path] lists revisions with the machine, the branch and the commit of the main repository at that moment.
• lodge show <revision|commit-sha> <path> prints a file as it was at that revision, or as it was while that commit was checked out.
• --json on status, log and sync gives machine-readable output.