Guides
Tips & best practices

Tips & best practices

The small habits that compound. Skim by section.

Getting the best results from agents

Anchor every agent to a folder. Agents that own a folder write predictable things in predictable places. Agents that "help with everything" produce noise that's hard to revisit. Pick a folder, name it after the work, point the agent at it.

Write the system prompt like a job description. Title, scope, what they own, what they should never do, how they hand off. Avoid abstractions. "Always write to /sales/changelog.md" beats "stay organized."

Set visibility deliberately. A specialist with visibility: folder is fast and cheap. A lead with visibility: cabinet is aware. Almost nobody needs visibility: all.

Use heartbeats for the morning, not the moment. A heartbeat that fires every 15 minutes is a notification system. A heartbeat that fires once a day at 9am is a teammate.

Default heartbeats to silence. Write the prompt so the agent only escalates new or important findings. The good ones run for weeks without paging you.

CLI power user

⌘N from anywhere opens the task composer. The fastest path from "I want X" to a queued task.

? opens the searchable shortcut sheet. Filter by name or key. Better than memorizing.

**⌘</kbd> toggles the web terminal.** A real shell in the workspace. <span class="tx-accent">Use it for git log, find`, quick scripts.

⌘K + >command jumps straight to a command. Like Spotlight but for Cabinet actions.

/save in any chat persists the conversation as a page. No more "this was a great chat, where did it go."

/compact shortens a long chat without losing the highlights. Useful before a hand-off to another agent.

Context files & mentions

@PageName attaches a page as agent context. Works in chats, task composers, and skill prompts.

@folder/ attaches a whole folder. The agent gets the directory listing plus the index page.

Page Name wiki-links autocomplete. Type two brackets, start the title, hit tab.

AGENTS.md at any folder root is auto-loaded. Use it like CLAUDE.md — write the working agreements for that area of the cabinet.

Memory & skills

Edit memory.md like any page. If an agent learned something wrong, just open the file and fix it. No magic, no migration.

Memory should fit on one screen. When an agent's memory.md grows past ~200 lines, run /compact memory in their chat. Cabinet rewrites it shorter.

Skills are folders. Treat them like libraries. Version them, write a README, ship them to skills.sh when they're useful to others.

An empty allowed-tools list is the safest skill. Read-only skills never break anything.

Performance & cost

Cheap model for triage, careful model for synthesis. Use Haiku/GPT-4.1-mini for inbox sweeps and dispatch. Save Opus for the weekly synthesis.

Set per-task budgets in .cabinet. A single hard cap (budget.perTask.maxCostUsd: 5) prevents runaway runs.

Fallback chains save the day. Configure fallbacks.claude-opus-4-7 to drop to Sonnet, then GPT, when the primary 429s.

Local models for private data. Ollama + a 70B model is competent for most internal work. Zero API spend.

Avoid visibility: all on lead agents. It pulls the whole cabinet into context on every run. Cost adds up quickly.

Privacy & local-first

Cabinet doesn't phone home. No telemetry by default. The only network calls are the ones agents make to your configured providers.

providers.localOnly: true in .cabinet hard-locks to local models. Useful for sensitive cabinets (clients, legal, medical).

.gitignore what shouldn't be shipped. Default: .chat/, .cabinet-state/, .cabinet.db. Add anything cabinet-specific (raw client lists, API keys you accidentally committed).

Templates strip .gitignore'd files at publish time. cabinetai publish won't ship secrets if they're in .gitignore.

CABINET_DATA_DIR can be encrypted. Cabinet doesn't care where its files live. Point it at a FileVault / LUKS volume.

Publishing & templates

Test your template by installing it from a fresh clone. npx cabinets add ./your-template-path works on local folders too.

The description field on .cabinet is your hook. ≤80 chars, present tense, action-oriented. "Run your job search like a sales pipeline" beats "A cabinet for searching jobs."

Strip your real data before publishing. Replace your CSV rows with synthetic ones. Make it obvious. Real users will fill in their own.

Pin model names that exist. A template that says model: claude-3-7 breaks for everyone after the model retires. Use the defaults in the manifest so users can override.

Document heartbeats in the body of persona.md. When the install confirmation prompts the user, the heartbeat label is what they read.

Read on