Projects and notes

Each project has:

Field	Notes
Name	Up to 64 characters. Its slug identifies the project in the API
UUID	A UUIDv7, set when the project is created. It never changes, even if you rename the project. It’s how a .nurseshark file finds its project
Summary	One line, up to 280 characters
Description	A few paragraphs, up to 4,096 characters
Status	idea, active, paused, shipped or archived
Tags	Up to 20, each up to 40 characters
Repo URL, URL	http(s) links. A GitHub repo gets an “Open in Codespaces” link on the website
Color	Picked at random when the project is created. The website shows a square in that color as the project’s icon and offers it as a favicon download

Notes are plain text, up to 2,048 characters each, with at most 25 per project. When a project is full, delete old notes on the website before adding more.

The .nurseshark file

When your assistant creates a project in a folder, it writes a .nurseshark file at the folder’s root. In a repo that holds several projects, each one gets the file in its own subfolder:

uuid=019a4f3c-7e21-7b4a-9c3d-2f6a1e8d5b07
project=blue-shark
name=blue-shark
summary=Home inventory
color=#3c8d1f

It’s plain text, so anything can read it, and nothing else is needed to show your project in a Claude Code status line or a shell prompt. Nurseshark doesn’t ship a script for this: write one, or ask Claude to add it for you.

Your assistant rewrites the file when it renames a project or changes its summary. A change you make on the website reaches the file when you sync it:

/mcp__nurseshark__sync_project [path]

or ask your assistant to sync the folder. It looks the project up by the file’s uuid, so this still works after a rename, and rewrites the file with the current details. If the UUID belongs to a project your account doesn’t have, it tells you and leaves the file alone. That’s what happens if you commit the file and someone else syncs it, so you may want .nurseshark in your .gitignore.

Syncing at the start of a session

Claude Code hooks can’t run a slash command, but a SessionStart hook can tell Claude the file may be out of date, and Claude then follows the sync steps. To turn this on, add the hook to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "if [ -f .nurseshark ]; then echo 'The .nurseshark file in this folder may be out of date. The Nurseshark sync_project steps refresh it.'; fi"
          }
        ]
      }
    ]
  }
}

Claude acts on the note during the session, so the sync isn’t guaranteed to happen before your first message. Your status line or prompt shows the old details until it does.

Reading the file safely

A repo you clone can contain any .nurseshark file, so read the values instead of running the file with source. In a zsh prompt, show them through psvar rather than building them into PROMPT, or a project name could run as a command.

Importing an existing project

To record a project you already have, run this in Claude Code:

/mcp__nurseshark__import_project [path]

or ask your assistant to import it. It reads the folder’s README, manifests (package.json, Gemfile, pyproject.toml, Cargo.toml, go.mod, …) and git remote on your machine, and sends Nurseshark only the fields it fills in: name, summary, description, tags and URLs, never the files themselves. Then it writes a .nurseshark file in the folder.