@rikkainc/ccp 0.2.1

package/docs/stream-json.md

@@ -0,0 +1,82 @@
+# Stream JSON
+
+Claude's legacy print-mode stream:
+
+```bash
+claude -p --verbose --output-format stream-json "..."
+```
+
+emits runtime JSONL events. In local samples from Claude Code 2.1.140, a simple
+turn produced:
+
+- `system` / `init`, with runtime metadata such as `cwd`, tools, model, plugins,
+  and Claude Code version.
+- `rate_limit_event`, when available.
+- `assistant`, containing a full Claude message object.
+- `result`, containing the final text, session id, turn count, timing, usage,
+  cost, and terminal status.
+
+A tool-use turn produced the same shape plus:
+
+- `assistant` records with `message.content` blocks such as `tool_use`.
+- `user` records with `message.content` blocks such as `tool_result` and
+  optional `tool_use_result` metadata.
+- A final `assistant` text message followed by `result`.
+
+`claude-pty-wrapper --session-jsonl` is different: it emits the raw durable
+session records from Claude's `~/.claude/projects/.../<session-id>.jsonl` file.
+Those records use Claude's persisted history shape, often including camel-case
+fields such as `sessionId` and terminal records such as
+`{"type":"system","subtype":"turn_duration"}`.
+
+`claude-pty-wrapper -p --output-format stream-json` translates the durable
+session records into a legacy-like stream:
+
+- It emits a synthetic `system/init` event. If Claude persisted init metadata,
+  the wrapper forwards known metadata fields; otherwise it supplies `cwd` and
+  `session_id`.
+- It suppresses the initial prompt `user` record, matching legacy print-mode
+  stream output.
+- It forwards `assistant` message records with their full `message.content`
+  blocks intact, including text, tool calls, reasoning-style blocks, and other
+  content types Claude persists.
+- It forwards `user` tool-result records so consumers can observe tool outputs.
+- It emits a synthetic `result` record after the durable `turn_duration`
+  completion marker.
+- It accepts `--include-partial-messages` for CLI compatibility but silently
+  ignores it because durable session files do not contain runtime partial
+  message deltas.
+
+The translation is compatibility-oriented, not byte-for-byte identical. The
+wrapper cannot synthesize data that is not present in the durable session file,
+such as rate-limit metadata, exact API timings, full cost accounting, or every
+runtime-only init field.
+
+## Local Durable Session Findings
+
+A local review of recent `~/.claude/projects/**/*.jsonl` files and
+`~/.local/state/task-runner` run state found these durable-session patterns:
+
+- Task-runner stores Claude `backendSessionId` values and resolved
+  `~/.claude/projects/.../<session-id>.jsonl` paths in `run.json` and
+  `run-events.jsonl`, so those files are representative wrapper inputs.
+- Durable session records use `sessionId`; legacy print-mode stream JSON uses
+  `session_id`. The translator normalizes to `session_id`.
+- Durable sessions commonly include non-conversation metadata records such as
+  `last-prompt`, `custom-title`, `agent-name`, `attachment`, `ai-title`,
+  `permission-mode`, `queue-operation`, and `file-history-snapshot`. The
+  translator ignores these.
+- Durable `system` records observed include `turn_duration`,
+  `stop_hook_summary`, `away_summary`, and `local_command`. Only
+  `turn_duration` terminates the translated stream and creates `result`.
+- Durable sessions often do not persist `system/init`; the translator emits a
+  minimal synthetic init event when no persisted init is observed before the
+  turn begins.
+- Assistant content block shapes observed include `text`, `thinking`, and
+  `tool_use`. Tool-use blocks include `caller`, `id`, `input`, `name`, and
+  `type`.
+- User tool-result blocks include `content`, `tool_use_id`, `type`, and
+  sometimes `is_error`.
+- Durable user records commonly store tool result metadata as `toolUseResult`;
+  legacy stream JSON uses `tool_use_result`. The translator emits
+  `tool_use_result`.

package/docs/usage.md

@@ -0,0 +1,104 @@
+# Usage
+
+From a checkout, build and link the command before running it from your shell:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+For development validation before linking, run:
+
+```bash
+npm install
+npm run check
+npm link
+```
+
+Run Claude's normal interactive mode:
+
+```bash
+claude-pty-wrapper "Explain the current repository"
+```
+
+Bare interactive mode runs Claude in a wrapper-owned PTY relay. Claude output is
+written back to the terminal unchanged, and terminal input is forwarded to
+Claude without screen emulation.
+
+Enable idle freshness prompts in bare interactive mode:
+
+```bash
+claude-pty-wrapper --freshness-interval 60 "Explain the current repository"
+```
+
+When freshness is enabled, PTY output and user stdin both reset the idle timer.
+The default injected message is `Please wait for further instructions.`.
+
+Refresh Claude's login/session state and exit when the interactive input prompt
+is ready:
+
+```bash
+claude-pty-wrapper --login-only
+```
+
+Login-only mode starts Claude in a wrapper-owned PTY without sending a prompt.
+Terminal input and output are still relayed, so browser-login or pasted-token
+flows can complete before the wrapper exits.
+
+Run a fresh print-like turn:
+
+```bash
+claude-pty-wrapper -p "Explain the current repository"
+```
+
+Run with explicit Claude model and effort flags:
+
+```bash
+claude-pty-wrapper --model sonnet --effort high -p "Review the diff"
+```
+
+The wrapper owns `-p/--print`, `--output-format`, `--input-format`, and
+`--session-jsonl`; those flags select wrapper behavior and are not passed to
+Claude. `--login-only` is also wrapper-owned. Wrapper diagnostics such as
+`--claude-bin`, `--cwd`, `--timeout`, `--raw-pty-log`, and `--wrapper-debug`
+are also handled by the wrapper.
+Passthrough freshness flags such as `--freshness-interval`,
+`--freshness-message`, `--freshness-max-iterations`, and
+`--freshness-max-duration` are handled by the wrapper and are rejected with
+wrapper-managed output modes. Other supported Claude flags keep their Claude
+names and are forwarded; run `claude-pty-wrapper --help` for the full accepted
+flag list.
+
+Emit durable session records instead of extracted text:
+
+```bash
+claude-pty-wrapper --session-jsonl "List changed files"
+```
+
+Emit a legacy-like stream JSONL translation:
+
+```bash
+claude-pty-wrapper -p --output-format stream-json "List changed files"
+```
+
+Emit a single Claude-shaped result object:
+
+```bash
+claude-pty-wrapper -p --output-format json "List changed files"
+```
+
+A bare prompt without wrapper output flags runs Claude interactively through the
+wrapper-owned PTY relay.
+
+Resume an existing Claude session:
+
+```bash
+claude-pty-wrapper --resume 18a18377-217d-4b29-9a68-c70a89b79330 -p "Continue"
+```
+
+Run opt-in live smoke tests against the installed Claude binary:
+
+```bash
+CLAUDE_PTY_WRAPPER_LIVE_SMOKE=1 npm run test:smoke:live
+```

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@rikkainc/ccp",
+  "version": "0.2.1",
+  "description": "A PTY-backed Claude print-mode replacement that streams Claude session JSONL.",
+  "type": "module",
+  "bin": {
+    "ccp": "dist/cli/main.js"
+  },
+  "files": ["dist", "README.md", "docs", "scripts/fix-node-pty-perms.mjs"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/chmod-bin.mjs",
+    "postinstall": "node scripts/fix-node-pty-perms.mjs",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run test/unit test/integration",
+    "test:smoke": "npm run build && vitest run test/smoke",
+    "test:smoke:live": "npm run build && vitest run test/smoke/live-claude-smoke.test.ts",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "check": "npm run lint && npm run typecheck && npm run test && npm run test:smoke"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "node-pty": "^1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,mjs,cjs,json}": ["biome format --write"]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rikkainc/ccp.git"
+  },
+  "homepage": "https://github.com/rikkainc/ccp#readme",
+  "bugs": {
+    "url": "https://github.com/rikkainc/ccp/issues"
+  },
+  "license": "MIT",
+  "keywords": ["claude", "claude-code", "pty", "cli", "jsonl"],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/fix-node-pty-perms.mjs

@@ -0,0 +1,27 @@
+import { chmodSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+if (process.platform !== "darwin" && process.platform !== "linux") {
+  process.exit(0);
+}
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const helperSuffix = join(
+  "node-pty",
+  "prebuilds",
+  `${process.platform}-${process.arch}`,
+  "spawn-helper",
+);
+const candidates = [
+  join(packageRoot, "node_modules", helperSuffix),
+  join(packageRoot, "..", helperSuffix),
+  join(packageRoot, "..", "..", helperSuffix),
+  join(process.cwd(), "node_modules", helperSuffix),
+];
+
+for (const helperPath of candidates) {
+  if (existsSync(helperPath)) {
+    chmodSync(helperPath, 0o755);
+  }
+}