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 (canonical vocabulary lives at tools/widget-schema.json; each type maps to a Swift view under scarf/scarf/Features/Projects/Views/Widgets/):

Type	Since	Purpose
`stat`	v2.2	Single metric: value + label + optional icon, color, and inline `sparkline: [Number]` trend (v2.7+).
`progress`	v2.2	Progress bar with label (0.0..1.0).
`text`	v2.2	Inline markdown / plain text block.
`table`	v2.2	Columns + rows of strings.
`chart`	v2.2	Line / bar / area / pie with `ChartSeries[]` of `ChartDataPoint{x, y}`.
`list`	v2.2	Bulleted list with optional typed status badges per item — see Status badges below.
`webview`	v2.2	Embedded web view (URL + height). Including any webview also exposes a Site tab.
`markdown_file`	v2.7	Renders a markdown file from `<project>/<path>`. Refreshes when any file under `.scarf/` changes.
`log_tail`	v2.7	Tails the last `lines` of a file (default 20), monospaced; ANSI codes stripped.
`cron_status`	v2.7	Last run / next run / state for a Hermes cron job by `jobId`, plus a small log tail.
`image`	v2.7	Local image (`path` relative to project root) or remote `url`.
`status_grid`	v2.7	Compact NxM grid of colored cells, one per service / item. Reuses the typed status enum.

Status badges (typed in v2.7): list items and status_grid cells accept a status field that maps to a colored badge. Canonical values are success, warning, danger, info, pending, done, neutral. Common synonyms also work (ok / up → success, down / error / failed → danger, active → info, complete → done). Unknown strings render as plain text — old dashboards that used ad-hoc statuses keep working byte-identically.

Auto-refresh (v2.7): Scarf watches each project's entire <project>/.scarf/ directory, not just dashboard.json. So when a cron job atomically writes <project>/.scarf/reports/uptime.md (write-temp + rename), the markdown_file widget pointing at it refreshes automatically. Limitation: in-place appends to an existing file (>> file.log) don't tick the watcher — the cron job should write atomically, or touch dashboard.json after each run to force a refresh. Remote (SSH-attached) projects share the same coverage via 3-second mtime polling.

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. v2.5.2+: on remote contexts a path-input + Verify sheet captures the destination zip path on the SSH host (mirrors the Add Project sheet's pattern from #54).
Import — unzip into a new profile slot. v2.5.2+: on remote contexts a path-input + Verify sheet captures the source zip path on the SSH host. Local context still uses NSOpenPanel. Drives hermes profile import <zip> over SSH; bytes are piped via HermesFileService.runHermesWithStdin (rather than landing on the remote disk first) when invoked from the local-file-on-Mac flow.

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.

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-05-04 — Scarf v2.7 (project-wide auto-refresh, 5 new widget types, typed status enum)

Getting Started

ScarfGo (iOS)

User Guide

Architecture

Developer Guide

Reference

Troubleshooting

Slow Chat Startup

Contributing

Release History

Legal & Support

Wiki edited via the local .wiki-worktree/ clone. See Wiki Maintenance for the workflow. Last sync: 2026-04-20.

Projects & Profiles

Projects

Profiles

Related pages