Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(terminal): make ~/ paths in terminal output Cmd/Ctrl+clickable

review9a8c79b7466d
diff --git a/CLAUDE.md b/CLAUDE.md
index e709d4a0a..5bb49e185 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1316,6 +1316,12 @@ session.
have no remote fs API with which to verify a token; relay tabs do have a core-bound, jailed fs
API and therefore support file links. Windows existence matching is case-insensitive and accepts
both separators; UNC tokens are refused whole before they can be reinterpreted as cwd-relative.
+ **Home-relative `~/x` tokens** (Claude Code prints its plan file as `~/.claude/plans/<name>.md`)
+ stay `~`-rooted all the way to the fs call and are expanded by the core that OWNS the filesystem
+ — `expandHomePath` in `core/fs-handlers.ts` for desktop/Server Edition, the remote shell for
+ `sshFs` — because the renderer does not know that home. A `~` after a path character (`a~/x`)
+ or `~user/x` is not a home path and yields no link. The relay's jailed `fs.*` calls fs-ops
+ directly and does not expand, so a relay tab's `~` token fails closed (no link).
- **Agent** (`createAgentNode(agentId, …)`) — a terminal preset that runs an agent CLI as its
`initialCommand` (runs once on open via `transport.write`, then cleared), with `data.agentId`
set. Builtins (`claude`/`codex`/`gemini`) come from `AGENT_CONFIG` (clay color etc.).
diff --git a/src/core/fs-handlers.ts b/src/core/fs-handlers.ts
index 514a9c58a..0e908faaa 100644
--- a/src/core/fs-handlers.ts
+++ b/src/core/fs-handlers.ts
@@ -1,3 +1,5 @@
+import { homedir } from 'os'
+import path from 'path'
import type { CorePlatform } from './platform'
import * as fsOps from './fs-ops'
import { saveUpload } from './uploads'
@@ -5,6 +7,20 @@ import { saveCanvasImage } from './canvas-images'
import { IPC } from '../shared/ipc'
import type { DownloadTicket } from '../shared/types'
+/**
+ * Expand a leading `~` / `~/` against THIS core's home directory — the machine that owns the
+ * filesystem, not the viewer. Terminal output names home-relative paths constantly (Claude Code's
+ * plan-approval screen prints `~/.claude/plans/<name>.md`), and the renderer cannot resolve them
+ * itself: it does not know the core's home, and on the Server Edition it runs on another machine.
+ * An SSH project never reaches here — its `sshFs` stack leaves the `~` for the remote shell.
+ * `~user` is NOT a home-relative path and stays literal (same rule as the accounts link dialog).
+ * The relay's jailed `fs.*` path calls fs-ops directly and is deliberately not routed through this.
+ */
+export function expandHomePath(p: string, home: string = homedir()): string {
+ if (typeof p !== 'string') return p
+ return p === '~' || p.startsWith('~/') ? path.join(home, p.slice(1)) : p
+}
+
/** The fs.* + files.quickOpen RPC surface, registered ONCE for every shell (Electron main, the
* Server Edition, and — through the Electron platform's handler table — a relay peer). The logic
* is already pure in core/fs-ops.ts; this is only the registration.
@@ -34,14 +50,15 @@ export function registerFsHandlers(
localProjectCwd?: (projectId: string) => string | undefined
} = {}
): void {
- platform.handle(IPC.fsList, (dirPath: string) => fsOps.listDir(dirPath))
- platform.handle(IPC.fsRead, (filePath: string) => fsOps.readText(filePath))
- platform.handle(IPC.fsReadBinary, (filePath: string) => fsOps.readBinary(filePath))
+ const home = expandHomePath
+ platform.handle(IPC.fsList, (dirPath: string) => fsOps.listDir(home(dirPath)))
+ platform.handle(IPC.fsRead, (filePath: string) => fsOps.readText(home(filePath)))
+ platform.handle(IPC.fsReadBinary, (filePath: string) => fsOps.readBinary(home(filePath)))
platform.handle(IPC.fsWrite, (filePath: string, content: string) =>
- fsOps.writeText(filePath, content)
+ fsOps.writeText(home(filePath), content)
)
- platform.handle(IPC.fsMkdir, (dirPath: string) => fsOps.makeDir(dirPath))
- platform.handle(IPC.fsExists, (p: string) => fsOps.pathExists(p))
+ platform.handle(IPC.fsMkdir, (dirPath: string) => fsOps.makeDir(home(dirPath)))
+ platform.handle(IPC.fsExists, (p: string) => fsOps.pathExists(home(p)))
platform.handle(IPC.filesQuickOpen, (cwd: string) => fsOps.listQuickOpenFiles(cwd))
// Bytes with no path on this machine (a clipboard paste, or a browser client's file) land in
// the managed uploads dir so the terminal has something to name. See core/uploads.ts.
diff --git a/src/renderer/terminal/file-links.test.ts b/src/renderer/terminal/file-links.test.ts
index a8e1fb794..b6051c7bd 100644
--- a/src/renderer/terminal/file-links.test.ts
+++ b/src/renderer/terminal/file-links.test.ts
@@ -36,8 +36,24 @@ describe('matchFileTokens', () => {
expect(matchFileTokens('https://example.com/a/b plain word')).toEqual([])
})
- it('skips ~ paths (no home resolution in v1)', () => {
- expect(matchFileTokens('~/notes.md')).toEqual([])
+ it('matches home-relative ~/ paths with their tilde attached', () => {
+ expect(matchFileTokens('~/notes.md')).toEqual([
+ { text: '~/notes.md', startIndex: 0, path: '~/notes.md', line: undefined }
+ ])
+ // Claude Code's plan-approval footer — the path the user Cmd+clicks.
+ const line = 'ctrl-g to edit in Vim · ~/.claude/plans/wondrous-rossum.md'
+ const [t] = matchFileTokens(line)
+ expect(t.text).toBe('~/.claude/plans/wondrous-rossum.md')
+ expect(t.path).toBe('~/.claude/plans/wondrous-rossum.md')
+ expect(line.slice(t.startIndex, t.startIndex + t.text.length)).toBe(t.text)
+ expect(matchFileTokens('(~/src/a.ts:12)')).toEqual([
+ { text: '~/src/a.ts:12', startIndex: 1, path: '~/src/a.ts', line: 12 }
+ ])
+ })
+
+ it('does not treat a mid-word tilde or ~user as a home path', () => {
+ expect(matchFileTokens('backup~/notes.md')).toEqual([])
+ expect(matchFileTokens('~alice/notes.md')).toEqual([])
})
})
@@ -61,6 +77,12 @@ describe('resolveFileToken', () => {
expect(resolveFileToken('../../../x.ts', '~/proj')).toBeNull() // .. may not pop the ~
expect(resolveFileToken('/abs/x.ts', '~/proj')).toBe('/abs/x.ts') // absolutes unaffected
})
+
+ it('keeps a ~/ token home-rooted whatever the cwd, for the core to expand', () => {
+ expect(resolveFileToken('~/.claude/plans/p.md', '/root/nodeterm')).toBe('~/.claude/plans/p.md')
+ expect(resolveFileToken('~/a/../b.md', undefined)).toBe('~/b.md')
+ expect(resolveFileToken('~/../etc/passwd', '/x')).toBeNull() // .. may not pop the ~
+ })
})
describe('POSIX existence lookup', () => {
diff --git a/src/renderer/terminal/file-links.ts b/src/renderer/terminal/file-links.ts
index d1ed21121..4689ebac1 100644
--- a/src/renderer/terminal/file-links.ts
+++ b/src/renderer/terminal/file-links.ts
@@ -1,8 +1,11 @@
// Cmd/Ctrl+click links in terminal output. `createUrlLinkProvider` handles http(s) URLs;
// `createFileLinkProvider` handles path-like tokens: absolute (`/x/y`), dot-relative
// (`./x`, `../x`) and bare relatives with at least one slash (`src/a.ts`), with optional
-// `:line[:col]` suffixes (compiler/grep output). `~` paths are skipped in v1 (no home
-// resolution).
+// `:line[:col]` suffixes (compiler/grep output), and home-relative `~/x` paths. A `~` path stays
+// `~`-rooted all the way to the filesystem call: the core that owns the filesystem expands it
+// against ITS home (`expandHomePath` in core/fs-handlers.ts; an SSH project's remote shell does it
+// for `sshFs`) — the renderer does not know that home, and on the Server Edition it is another
+// machine's.
//
// Existence (and dir-ness) is verified before a file link is offered, via a short-TTL cache
// of parent-directory listings — one fs.list covers every sibling on a compiler-error screen.
@@ -71,19 +74,29 @@ export interface PathConventionOpts {
windows?: boolean
}
+/** Characters that, right before a `~`, mean it is not the start of a home path (`a~/x`). */
+const HOME_LEAD_BLOCK_RE = /[\w.@+~\/-]/
+
export function matchFileTokens(lineText: string, opts: PathConventionOpts = {}): FileToken[] {
const out: FileToken[] = []
if (opts.windows) return matchWindowsFileTokens(lineText)
for (const m of lineText.matchAll(TOKEN_RE)) {
let text = m[0]
- // URLs (and protocol-ish tokens) belong to the web-links addon. A token preceded by
- // `~` is a home-relative path minus its tilde (no home resolution in v1) — skip it
- // rather than mis-resolve `~/x` as the absolute `/x`.
+ let start = m.index
+ // URLs (and protocol-ish tokens) belong to the web-links addon.
const before = lineText.slice(Math.max(0, m.index - 8), m.index)
// `\w+:\/{1,2}$` (not just `://`): the optional leading-`/` in TOKEN_RE can swallow the
// second slash of `://`, so a URL's token starts at that slash and `before` ends `https:/`.
if (/\w+:\/{1,2}$/.test(before) || text.includes('//')) continue
- if (m.index > 0 && lineText[m.index - 1] === '~') continue
+ // A token preceded by `~` is a home-relative path minus its tilde. Re-attach the tilde when it
+ // stands at a word start (`~/x`, ` ~/x`, `(~/x`) so it never mis-resolves as the absolute `/x`.
+ // Anything else before the `~` (`a~/x`, `~user/x`) is not a home path — skip it, as before.
+ if (m.index > 0 && lineText[m.index - 1] === '~') {
+ const lead = m.index > 1 ? lineText[m.index - 2] : ''
+ if (!text.startsWith('/') || HOME_LEAD_BLOCK_RE.test(lead)) continue
+ text = '~' + text
+ start = m.index - 1
+ }
text = text.replace(TRAILING_PUNCT, '')
if (text.length < 3) continue
let path = text
@@ -94,7 +107,7 @@ export function matchFileTokens(lineText: string, opts: PathConventionOpts = {})
line = parseInt(suffix[2], 10)
}
if (!path || !path.includes('/')) continue
- out.push({ text, startIndex: m.index, path, line })
+ out.push({ text, startIndex: start, path, line })
}
return out
}
@@ -215,7 +228,13 @@ export function resolveFileToken(
opts: PathConventionOpts = {}
): string | null {
if (opts.windows) return resolveWindowsFileToken(path, cwd)
- const raw = path.startsWith('/') ? path : cwd ? `${cwd.replace(/\/+$/, '')}/${path}` : null
+ // `~/x` is rooted at the home dir, never at cwd; the `~` is kept for the core to expand.
+ const raw =
+ path.startsWith('/') || path.startsWith('~/')
+ ? path
+ : cwd
+ ? `${cwd.replace(/\/+$/, '')}/${path}`
+ : null
if (!raw) return null
const segs = raw.split('/').filter((s) => s && s !== '.')
const tilde = segs[0] === '~'
diff --git a/src/server/handlers/fs-handlers.test.ts b/src/server/handlers/fs-handlers.test.ts
index 56cf6dadf..a66c2eb67 100644
--- a/src/server/handlers/fs-handlers.test.ts
+++ b/src/server/handlers/fs-handlers.test.ts
@@ -3,7 +3,7 @@ import fs from 'fs'
import os from 'os'
import path from 'path'
import { ServerPlatform } from '../platform-server'
-import { registerFsHandlers } from '../../core/fs-handlers'
+import { expandHomePath, registerFsHandlers } from '../../core/fs-handlers'
import { appImagesDir, projectImagesDir } from '../../core/canvas-images'
import { IPC } from '../../shared/ipc'
@@ -48,6 +48,31 @@ describe('server fs handlers', () => {
expect(await call(IPC.fsMkdir, nested)).toBe(true)
expect(await call(IPC.fsExists, nested)).toBe(true)
})
+ // Terminal output names home-relative paths (Claude Code's plan footer prints
+ // `~/.claude/plans/<name>.md`) and the renderer cannot resolve them — it does not know this
+ // core's home. The handlers expand them here. os.homedir() honours $HOME on POSIX only.
+ it.skipIf(process.platform === 'win32')('expands a leading ~/ against this core\'s home', async () => {
+ const prev = process.env.HOME
+ process.env.HOME = dir
+ try {
+ fs.mkdirSync(path.join(dir, '.claude/plans'), { recursive: true })
+ fs.writeFileSync(path.join(dir, '.claude/plans/p.md'), '# Plan')
+ const entries = (await call(IPC.fsList, '~/.claude/plans')) as Array<{ name: string }>
+ expect(entries.map((e) => e.name)).toEqual(['p.md'])
+ expect(await call(IPC.fsRead, '~/.claude/plans/p.md')).toBe('# Plan')
+ expect(await call(IPC.fsExists, '~')).toBe(true)
+ expect(await call(IPC.fsWrite, '~/.claude/plans/p.md', 'edited')).toBe(true)
+ expect(fs.readFileSync(path.join(dir, '.claude/plans/p.md'), 'utf8')).toBe('edited')
+ } finally {
+ process.env.HOME = prev
+ }
+ })
+ it('leaves ~user and mid-path tildes literal', () => {
+ expect(expandHomePath('~alice/x', '/h')).toBe('~alice/x')
+ expect(expandHomePath('/a/~/x', '/h')).toBe('/a/~/x')
+ expect(expandHomePath('~', '/h')).toBe('/h')
+ expect(expandHomePath('~/a/b', '/h')).toBe(path.join('/h', 'a/b'))
+ })
// The canvas-image write directory is derived HERE, from this shell's own project registry —
// the renderer sends a projectId and never names a path. These pin the injection itself: it is
// one line per shell (src/main/index.ts and src/server/index.ts), and dropping either one sends