Keep your coding agent in sync with your project context — Briefs, Tasks, Blueprints, and Methods update on disk in real time.
By default, hamster sync refreshes shared account context under ~/.hamster/. Passing a Brief UUID, slug, or full Studio URL runs a one-shot scoped sync. The CLI reuses the nearest existing .hamster/ projection at or above the current directory, or creates one at the repository root when none exists. Scoped Brief sync cannot be combined with --watch; use hamster sync --watch only for shared account context.
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:
No copy-pasting requirements into chat. No switching windows to check a Task description. Shared context is on disk under your home directory, while explicitly scoped Brief context can sit beside the code that uses it.
After each sync, the CLI generates <base>/.claude/skills/hamster-project-context/SKILL.md. For user-level initialization and shared account sync, <base> is your home directory. For a Brief-scoped sync, <base> is the repository root when the CLI creates a projection, or the parent of the nearest existing .hamster/ projection.
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 to initialize shared ~/.hamster/ state.
Run hamster sync with no Brief identifier to refresh shared account context. It runs once and exits unless you add --watch.
Pass a Brief UUID, slug, or full Studio 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 ignore the local cache and refresh shared account context, or add --force to an explicit Brief sync to pull that projection 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 your home directory for shared sync. For an explicitly scoped sync, it is the parent of the nearest existing .hamster/ projection, or the repository root when the CLI creates a projection. The .state.json file tracks sync metadata — you do not 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 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.