Using the CLI

The terminal dashboard, everyday commands, and example prompts for working with your coding agent.

The Dashboard

Run hamster with no arguments to open the terminal dashboard. It shows four tabs:

Dashboard — Brief and Task counts, a progress bar for Task completion, and recent activity across your project
Briefs — Browse Briefs with a Task list for each one. Press Enter to open a kanban view with Tasks grouped by status
Blueprints — Read your architecture documents rendered as formatted markdown
Methods — Read your team conventions and processes

The dashboard watches for changes in real time. If a teammate updates a Brief or moves a Task in the browser, the dashboard reflects it within seconds.

Keyboard Shortcuts

Key	Action
`1` `2` `3` `4`	Jump to Dashboard / Briefs / Blueprints / Methods
`j` / `k` or arrows	Navigate lists
Enter	Open detail view or kanban
`e`	Open the selected file in your editor
`s`	Trigger a manual sync
`?`	Toggle help
`q`	Quit

Commands

Command	What it does
`hamster`	Open the terminal dashboard
`hamster sync <brief-id-or-url>`	Pull a Brief and its Tasks once at the repository root or the nearest existing projection
`hamster sync --watch`	Keep the `.hamster/` projection updated continuously
`hamster sync --force`	Re-sync every item into the `.hamster/` projection, even unchanged ones
`hamster brief create --title "Title"`	Create a new Brief
`hamster brief plan <id-or-slug> --generate`	Start Plan generation for a Brief
`hamster brief deliver <id-or-slug>`	Start Delivery for a Brief
`hamster blueprint create --title "Title"`	Create a new Blueprint
`hamster method create --title "Title"`	Create a new Method
`hamster note create --title "Title"`	Create a new Note
`hamster brief get <id-or-slug>`	View a Brief's full content
`hamster task get HAM-123`	View a Task's full details
`hamster note get <id> --content`	View a Note with its body as markdown
`hamster note list`	List non-archived Notes
`hamster task list`	List top-level Tasks for the active account
`hamster task next`	Show the next recommended Task based on priority and dependencies
`hamster team list`, `hamster team switch`, `hamster team members`	List teams, select the active team, or inspect its members
`hamster status`	Show sync statistics, entity counts, and auth state
`hamster auth login`	Authenticate or switch accounts
`hamster auth logout`	Clear your local session
`hamster init`	Create the repository's `.hamster/` projection, pick a team, and run the first sync

Example Agent Prompts

Once you have synced the needed context and your agent has it loaded, these kinds of prompts work naturally:

Starting work

"Read the Brief for my-project and summarize what needs to be built"
"What's the next Task I should work on?"
"Show me the acceptance criteria for HAM-042"

Building with context

"Implement HAM-015 following the patterns in the engineering-context Blueprint"
"Work on the next Task, using the Methods in code-review-process"
"Check the Brief requirements before starting HAM-023 — make sure nothing has changed"

Tracking progress

"Which Tasks are still in progress?"
"How many Tasks are done on the auth Brief?"
"Mark HAM-015 as done and pick up the next one"

These prompts work because the agent reads synced context files directly. Synced context includes Brief requirements, Task instructions and acceptance criteria, Blueprints, and Methods. An explicitly scoped projection contains the selected Brief and its Tasks.

For agents that can also write back to Hamster (updating Task status, creating subtasks), see MCP Server.

Tips

Run hamster sync --watch in a background terminal or tmux pane to keep the .hamster/ projection current while you work.
Press e in the dashboard to open any Brief, Task, Blueprint, or Method file in your $EDITOR.
hamster status is a quick way to check how many entities are synced and when the last sync ran.