diff --git a/README.md b/README.md
index b6698601..02a6d5de 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ This is the source code for the free [Pixel Agents extension for VS Code](https:
 
 - VS Code 1.109.0 or later
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and configured
+- **Platform**: Windows, Linux, and macOS are supported
 
 ## Getting Started
 
@@ -94,7 +95,7 @@ The webview runs a lightweight game loop with canvas rendering, BFS pathfinding,
 
 - **Agent-terminal sync** — the way agents are connected to Claude Code terminal instances is not super robust and sometimes desyncs, especially when terminals are rapidly opened/closed or restored across sessions.
 - **Heuristic-based status detection** — Claude Code's JSONL transcript format does not provide clear signals for when an agent is waiting for user input or when it has finished its turn. The current detection is based on heuristics (idle timers, turn-duration events) and often misfires — agents may briefly show the wrong status or miss transitions.
-- **Windows-only testing** — the extension has only been tested on Windows 11. It may work on macOS or Linux, but there could be unexpected issues with file watching, paths, or terminal behavior on those platforms.
+- **Linux/macOS tip** — if you launch VS Code without a folder open (e.g. bare `code` command), agents will start in your home directory. This is fully supported; just be aware your Claude sessions will be tracked under `~/.claude/projects/` using your home directory as the project root.
 
 ## Roadmap
 
diff --git a/src/agentManager.ts b/src/agentManager.ts
index 4c53af84..29d45182 100644
--- a/src/agentManager.ts
+++ b/src/agentManager.ts
@@ -9,7 +9,12 @@ import { JSONL_POLL_INTERVAL_MS, TERMINAL_NAME_PREFIX, WORKSPACE_KEY_AGENTS, WOR
 import { migrateAndLoadLayout } from './layoutPersistence.js';
 
 export function getProjectDirPath(cwd?: string): string | null {
-	const workspacePath = cwd || vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
+	// Fall back to home directory when no workspace folder is open.
+	// This is the common case on Linux/macOS when VS Code is launched without a folder
+	// (e.g. `code` with no arguments). Claude Code writes JSONL files to
+	// ~/.claude/projects/<hash>/ where <hash> is derived from the process cwd, so we
+	// must use the same directory as the terminal's working directory.
+	const workspacePath = cwd || vscode.workspace.workspaceFolders?.[0]?.uri.fsPath || os.homedir();
 	if (!workspacePath) return null;
 	const dirName = workspacePath.replace(/[^a-zA-Z0-9-]/g, '-');
 	const projectDir = path.join(os.homedir(), '.claude', 'projects', dirName);
@@ -34,7 +39,10 @@ export async function launchNewTerminal(
 	folderPath?: string,
 ): Promise<void> {
 	const folders = vscode.workspace.workspaceFolders;
-	const cwd = folderPath || folders?.[0]?.uri.fsPath;
+	// Use home directory as fallback cwd when no workspace is open (common on Linux/macOS).
+	// This ensures the terminal starts in a predictable location that matches the project
+	// dir hash Claude Code will use for JSONL transcript files.
+	const cwd = folderPath || folders?.[0]?.uri.fsPath || os.homedir();
 	const isMultiRoot = !!(folders && folders.length > 1);
 	const idx = nextTerminalIndexRef.current++;
 	const terminal = vscode.window.createTerminal({