34 lines
2.6 KiB
Markdown
34 lines
2.6 KiB
Markdown
---
|
|
name: lodge
|
|
description: 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.
|