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 (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, v2.7.5): clicking a project row reveals a tabbed detail view — Dashboard, Sessions, Site (when the dashboard has a webview widget), Kanban (v2.7.5+, Hermes v0.12+ only), 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.

Per-project Kanban (v2.7.5): each project gets its own Kanban board scoped to a Scarf-minted scarf:<slug> tenant. The slug is derived from the project name (lowercased, hyphenated, ≤48 chars), persisted to <project>/.scarf/manifest.json's new optional kanbanTenant field on first kanban interaction, and immutable across rename so existing tasks stay attributable. ProjectAgentContextService adds a Kanban tenant: scarf:<slug> line inside the AGENTS.md scarf-managed block at every chat-start, instructing the agent to pass --tenant <slug> on hermes kanban create so agent-spawned tasks land on the right project board automatically. Bare projects (no template manifest) get a sentinel manifest written with id: scarf/<project-id> + version: 0.0.0 + just the kanbanTenant set — ProjectAgentContextService recognizes the sentinel and refuses to surface it as a "Template" line, so a project that's never been template-installed doesn't suddenly start advertising a fake template to the agent. iOS gets a read-only board on the same project tab as a horizontally-paged segmented Picker of single-column lists. The new kanban_summary dashboard widget shows the top three running / blocked / todo tasks plus a glance footer ("12 todo · 3 running · 5 blocked"); add { kind: kanban_summary, max_rows: 3 } to dashboard.json to include it. See Sidebar and Navigation for the global Kanban surface.

Kanban v0.15 wave (v2.10.0+, Hermes v0.15+): the board gains server-side --sort, Promote / Schedule (park) / Delete-permanently (archive --rm) card actions, new Scheduled + Review columns (collapse when empty), per-task worktree --branch on create + a read-only model_override line in the inspector, and --board multi-board plumbing in the service layer (board switcher UI is a follow-up). The biggest change for project boards: tasks are now scoped by the originating ACP session_id (stamped by Hermes) rather than the tenant + time-window approximation, so a board opened from a project chat shows exactly that session's tasks — even ones the agent created without tagging the scarf:<slug> tenant — with a "This chat ⇄ All tasks" scope toggle to widen it. The tenant slug above is still minted and injected for cross-session attribution, but session scoping is now authoritative for the per-chat view. Gated on HermesCapabilities.hasKanbanV015 / hasKanbanSessionFilter; pre-v0.15 hosts keep the v2.7.5 tenant-scoped board. See Chat for the chat-header Kanban chip.

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.

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-05-28 — Scarf v2.10.0 (Kanban v0.15 wave: --sort, Promote / Schedule / Delete-permanently actions, Scheduled + Review columns, worktree --branch + model_override display, session-scoped per-project board)