Projects and Profiles

Projects & Profiles

Two distinct concepts in adjacent sidebar items. Projects are agent-generated dashboards for any directory. Profiles are isolated Hermes installations.

Projects

A project is any directory you tell Scarf about — typically a code repo, but anything works. Each project gets a custom dashboard composed of widgets defined in <project>/.scarf/dashboard.json.

Widget types (from ProjectDashboard.swift):

Type	Purpose
stat	Single metric: value + label + optional icon and color.
progress	Progress bar with label.
text	Markdown / plain text block.
table	Columns + rows.
chart	Line / bar / area / pie with ChartSeries[] of ChartDataPoint{x, y}.
list	Bulleted list with optional status badges.
webview	Embedded web view (URL + height).

The Hermes pattern: ask your agent to build and maintain the dashboard for you. "Update .scarf/dashboard.json to show test pass rate, lines of code, and the open PR list." Scarf renders the result; the agent maintains it.

The full schema is documented in scarf/docs/DASHBOARD_SCHEMA.md in the main repo.

Adding a project: click + in the Projects sidebar, pick a directory. The project is registered in ~/.hermes/scarf/projects.json; the dashboard JSON lives in <project>/.scarf/dashboard.json (which you should add to your project's .gitignore if it's user-specific).

Per-project tabs (v2.3+, v2.5): clicking a project row reveals a tabbed detail view — Dashboard, Sessions, Site (when the dashboard has a webview widget), and Slash Commands (v2.5). The Sessions tab lists chats attributed to the project; New Chat spawns hermes acp with the project's directory as the session cwd and writes a Scarf-managed block into <project>/AGENTS.md so the agent boots with project context. Attribution survives across Mac and ScarfGo via the shared SessionAttributionService. See Slash Commands for the per-project authoring tab.

Sharing a project: as of v2.2.0, projects can be packaged into .scarftemplate bundles and shared with anyone — see Project Templates. Export turns a live project into a redistributable bundle; install unpacks one and sets up the dashboard, skills, cron jobs, configuration schema, and (in v2.5+) project-scoped slash commands in a single preview-and-confirm step. The public catalog lives at awizemann.github.io/scarf/templates/.

Profiles

A profile is an isolated Hermes installation — separate config, sessions, memory, skills, the lot. Useful for keeping work / personal context separate, or for testing a config change without disturbing your main instance. Hermes ships profiles as of v0.11.0.

How profile storage actually works (v0.11+, as Scarf reads it in v2.5.1+):

• The "default" profile is ~/.hermes/ itself — backward compatible, zero migration.
• Named profiles live under ~/.hermes/profiles/<name>/, each a fully independent HERMES_HOME. Each profile carries its own state.db, sessions/, config.yaml, .env, memories/, cron/, skills/, gateway_state.json, etc.
• The active profile is recorded in ~/.hermes/active_profile — a single-line text file containing the profile name, or absent / empty when default is active. hermes profile use <name> writes that file; the Hermes CLI then sets HERMES_HOME accordingly per invocation.
• Scarf v2.5.1+ reads active_profile via HermesProfileResolver and routes every derived path through it — state.db, sessions/, config.yaml, memories/, cron/jobs.json, auth.json, plugins, gateway state, logs, all of it. So switching profiles on the host with hermes profile use coder and relaunching Scarf correctly reads the new profile's data. The chat session info bar surfaces a small profile chip when not on default so you can tell at a glance which profile Scarf is reading from.
• Pre-2.5.1 Scarf hardcoded ~/.hermes and ignored active_profile, which silently read the wrong DB after a profile switch (issue #50). If you're on 2.5.0 or older, upgrade.

Operations (all wrap hermes profile ... via context.runHermes):

• Switch — make a profile active. Scarf shows a "restart Scarf to fully apply" reminder; the resolver re-reads active_profile on launch and on each HermesPathSet construction (5s cache).
• Create / rename / delete — straightforward.
• Export — zips the profile directory; useful for backup or moving to a new machine.
• Import — unzip into a new profile slot.

Remote SSH contexts don't yet auto-resolve active_profile — HermesPathSet.defaultRemoteHome stays at the configured remote home. If you're using profiles on a remote, set the Hermes data directory field in Manage Servers to point at ~/.hermes/profiles/<name> for that server context. Issue #53's degraded-pill diagnostics will tell you when this is the cause of an empty dashboard.

Related pages

• Project Templates — .scarftemplate bundles (schemaVersion 3 in v2.5), the install / export / author flows, the public catalog.
• Slash Commands — project-scoped slash commands authored in the per-project Slash Commands tab.
• Hermes Paths — ~/.hermes/profiles/ and the projects registry.
• Memory & Skills — memory is profile-scoped.
• Settings — exposes "Backup & Restore" buttons (hermes backup / hermes import) at the profile level.

---

Last updated: 2026-04-27 — Scarf v2.5.1 (Hermes v0.11 profile awareness via HermesProfileResolver + active_profile chip in chat info bar)