Keep your coding agent in sync with your project context — Briefs, Tasks, Blueprints, and Methods update on disk in real time.
From a repository, hamster sync refreshes the .hamster/ projection: it reuses the nearest existing .hamster/ at or above the current directory, or creates one at the repository root when none exists. ~/.hamster/ stays the user-level cache. Passing a Brief UUID, slug, or full Hamster URL runs a one-shot sync of only that Brief, which cannot be combined with --watch.
This is the core of what the CLI does: it turns your project management context into a local Knowledge base that your coding agent can read directly.
Every synced file is a markdown document with structured YAML frontmatter. A Task file includes the Task description, acceptance criteria, priority, estimated complexity, and dependency chain. A Brief file has the full product requirements. Blueprints contain architecture decisions. Methods capture team conventions.
When your coding agent starts a session with the relevant .hamster/ base available, it can read these files to understand:
Synced context sits in the repository's .hamster/, beside the code that uses it.
After each sync, the CLI generates <base>/.claude/skills/hamster-project-context/SKILL.md. In a repository, <base> is the parent of the .hamster/ projection: the nearest existing one, or the repository root when the CLI creates it. Outside a repository, a plain hamster sync uses your home directory as <base>.
The skill file tells your agent where every synced document lives, how to interpret the frontmatter fields, and how to navigate between Briefs, Tasks, Blueprints, and Methods. It loads automatically at session start.
The skill file also includes current statistics — how many Briefs, Tasks, Blueprints, and Methods are synced, and when the last sync ran — so the agent knows the scope of the project it is working on.
| Entity | Local path | What's in it |
|---|---|---|
| Briefs | <base>/.hamster/{account}/briefs/{brief}/brief.md | Product requirements and context |
| Tasks | <base>/.hamster/{account}/briefs/{brief}/tasks/HAM-001-title.md | Instructions, acceptance criteria, priority, complexity, dependencies |
| Blueprints | <base>/.hamster/{account}/blueprints/{name}.md | Architecture decisions and patterns |
| Methods | <base>/.hamster/{account}/methods/{name}.md | Team conventions and processes |
An explicitly scoped projection contains the selected Brief and its Tasks.
Done and archived Briefs are excluded automatically. Your .hamster/ directory only contains active work.
Run hamster init once in a repository to create its .hamster/ projection, pick a team, and run the first sync. If you use the Hamster plugin, its setup skill runs hamster init for you.
Run hamster sync with no Brief identifier to refresh the projection. It runs once and exits unless you add --watch.
Pass a Brief UUID, slug, or full Hamster URL when you explicitly want a local projection for that Brief. A scoped Brief sync runs once and cannot be combined with --watch.
Run hamster sync --force to rewrite every synced file, even unchanged ones, or add --force to an explicit Brief sync to pull that Brief again.
The same account layout appears under the selected base:
<base>/.hamster/{account-slug}/
├── briefs/
│ └── my-project/
│ ├── brief.md
│ └── tasks/
│ ├── HAM-001-set-up-auth.md
│ └── HAM-002-build-dashboard.md
├── blueprints/
│ └── engineering-context.md
├── methods/
│ └── code-review-process.md
└── .state.json
<base>/.claude/skills/hamster-project-context/
└── SKILL.md
<base> is the parent of the repository's .hamster/ projection, or your home directory for a plain hamster sync outside a repository. The .state.json file tracks sync metadata, and you don't need to edit it. The .hamster/ directory and .claude/skills/hamster-project-context/ are git-ignored by default. Each carries its own .gitignore, because the content is generated and specific to your account. Delete that .gitignore if your team wants the synced markdown tracked in git.
hamster team switch, then hamster sync in each repository. The team is set per user, not per repository, so each repository follows on its next hamster sync.hamster status to see sync statistics — what was synced last, how many entities are on disk, and whether anything is stale.hamster sync after a long disconnection to catch up.