projects and machines / reference

Project files reference

The exact names and fields of the five files Clawdline reads to show a project's icon and its rows under Links in a Session.

Checked against the product on 6 October 2026

Latest release: Clawdline v2.9.0 · platform support

Before you start

  • Clawdline only reads these files. Another tool, a hook, or you writes them. Nothing here makes a network call.
  • Every file is optional. Rows appear under 連結 (Links) in a Session of that project.
  • <path> is the project's working directory with every / turned into -: /Users/you/code/atrium gives health--Users-you-code-atrium.json.

The five files

ShowsFileNeeds
Icon and name~/.claude/project-icons.jsonart, or hue + tone + shape
Deploy or CI run~/.claude/statusline-cache/ghrun-<owner>-<repo>.jsonstate, url
Health check~/.claude/statusline-cache/health-<path>.jsonstate, url
Long local operation~/.claude/statusline-cache/run-<path>.jsonstate; updated_at while running
Dev servers.devstack.json at the repository rootname, each process's name and port

Icon and name

Draw the icon with art, or generate it from hue, tone, and shape. The longest registered path containing a Session's directory wins. An icon copied on the Projects page takes precedence; see Projects. 

{
  "projects": {
    "/Users/you/code/atrium": {
      "label": "atrium",
      "art": {
        "accent": "#5CBBA1",
        "bg": "#2F6B5E",
        "palette": { "W": "#EEF6F4" },
        "rows": [".WWWWW.", ".W...W.", ".W.W.W.", ".W...W."]
      }
    },
    "/Users/you/code/cairn": {
      "label": "cairn", "hue": 3, "tone": 1, "shape": 35
    }
  }
}

Deploy or CI run

Named after the GitHub origin remote. running draws elapsed time against typical_seconds; ok and fail draw a result. A running file not rewritten for 30 minutes stops showing as running. 

{
  "state": "running",
  "label": "deploy",
  "started_at": 1786925931,
  "typical_seconds": 800,
  "url": "https://github.com/you/atrium/actions/runs/31981652530"
}

Health check

ok is healthy, sick means the service is broken, and offline means this machine has no network. The url may instead come from the project's health entry in project-icons.json. 

{
  "state": "ok",
  "label": "atrium.example",
  "url": "https://atrium.example",
  "ms": 1077,
  "http": 200,
  "version": "dd138a4dea27",
  "checked_at": 1787056356
}

Long local operation

A test suite, build, or migration. label and phase are shown as written. A running row disappears once updated_at is older than stale_after seconds (900 when missing); ok and fail never go stale. 

{
  "state": "running",
  "label": "test",
  "phase": "compiling",
  "started_at": 1757040000,
  "typical_seconds": 288,
  "updated_at": 1757040100,
  "stale_after": 900
}

Dev servers

Clawdline checks whether anything listens on each port, and shows each process as a row.

{
  "name": "atrium",
  "processes": [
    { "name": "api", "port": 8002 },
    { "name": "web", "port": 3001, "url": "http://127.0.0.1:3001/app" }
  ]
}

Rules for every file

  • A row missing a required field is dropped, not drawn empty. A value of the wrong type counts as absent.
  • An unknown state, or none, draws nothing.
  • Write to a temporary name and rename it into place, so a reader never sees half a file:
tmp=$(mktemp ~/.claude/statusline-cache/.run.XXXXXX)
printf '%s' "$json" > "$tmp"
mv "$tmp" ~/.claude/statusline-cache/run--Users-you-code-atrium.json

Check or remove a file

Parse it, run your update path once, and confirm the modification time moved:

python3 -m json.tool < ~/.claude/statusline-cache/run--Users-you-code-atrium.json
ls -l ~/.claude/statusline-cache/run--Users-you-code-atrium.json

Expected result: python3 -m json.tool prints the document, and 連結 shows the rows you wrote. Undo: delete the file, or remove the project's entry from project-icons.json; nothing else changes.

Where to go deeper