diff --git a/docs/status-line-setup.md b/docs/status-line-setup.md
new file mode 100644
index 0000000..410ded4
--- /dev/null
+++ b/docs/status-line-setup.md
@@ -0,0 +1,65 @@
+# ctask Status Line Setup
+
+## Claude Code Integration
+
+ctask includes helper scripts that display task context in Claude Code's status line.
+
+### Setup
+
+Add one of the following to your `~/.claude/settings.json`:
+
+**Linux / macOS (bash):**
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bash /path/to/ctask-statusline.sh"
+  }
+}
+```
+
+**Windows (PowerShell):**
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "powershell -NoProfile -File C:\\path\\to\\ctask-statusline.ps1"
+  }
+}
+```
+
+Replace `/path/to/` with the actual location of the script.
+
+### Output
+
+When inside a ctask session:
+
+```
+(ctask:arch-notes|local) ~/ai-workspaces/general/2026-04-05_arch-notes
+```
+
+When NOT in a ctask session: no output (falls through gracefully).
+
+### How It Works
+
+The scripts read only from environment variables set by ctask:
+
+- `CTASK_TASK` -- task slug
+- `CTASK_MODE` -- execution mode (local/container)
+- `CTASK_WORKSPACE` -- full workspace path
+
+No file parsing or subprocess calls are performed.
+
+## Non-Claude Agents
+
+For agents that do not support a dedicated status line, ctask provides an ephemeral
+shell prompt prefix in `--shell` mode:
+
+```
+(ctask:arch-notes|local) user@host:~/path$
+```
+
+This is set via `PS1` (Unix) or `PROMPT` (Windows) and does not modify permanent
+shell configuration.
diff --git a/scripts/ctask-statusline.ps1 b/scripts/ctask-statusline.ps1
new file mode 100644
index 0000000..3c66c48
--- /dev/null
+++ b/scripts/ctask-statusline.ps1
@@ -0,0 +1,8 @@
+# ctask status line helper for Claude Code
+# Reads ctask environment variables and prints a formatted context string.
+# Output: (ctask:<slug>|<mode>) <workspace_path>
+# Outputs nothing when not in a ctask session.
+
+if (-not $env:CTASK_TASK) { exit 0 }
+
+Write-Output "(ctask:$($env:CTASK_TASK)|$($env:CTASK_MODE)) $($env:CTASK_WORKSPACE)"
diff --git a/scripts/ctask-statusline.sh b/scripts/ctask-statusline.sh
new file mode 100644
index 0000000..2ba47f3
--- /dev/null
+++ b/scripts/ctask-statusline.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# ctask status line helper for Claude Code
+# Reads ctask environment variables and prints a formatted context string.
+# Output: (ctask:<slug>|<mode>) <workspace_path>
+# Outputs nothing when not in a ctask session.
+
+[ -z "$CTASK_TASK" ] && exit 0
+
+echo "(ctask:${CTASK_TASK}|${CTASK_MODE}) ${CTASK_WORKSPACE}"