Thread

Thread is a Moss-backed memory layer for Claude Code and Codex sessions.

It records what a coding agent has already inspected, changed, executed, and decided. Before the agent repeats a read or exploration, Thread checks the active memory index and surfaces the most relevant prior context. The tool call remains allowed: Thread reminds the agent without taking control away from it.

Thread is designed around Moss sessions: a local, in-process index that can be updated and queried in real time, then optionally pushed to Moss for persistence and resumed by name in another terminal, conversation, agent, or machine.

Contents

• Why Thread exists
• Key properties
• How it works
• What Thread records
• Requirements
• Installation
• Quickstart
• Sessions, persistence, and handoff
• Claude Code and Codex behavior
• Optional OpenRouter enhancement
• Configuration reference
• CLI reference
• Local storage
• Security and privacy
• Failure behavior
• Known limitations
• Troubleshooting
• Development

Why Thread exists

Long coding-agent sessions accumulate useful working knowledge:

• which files implement a feature;
• which functions matter;
• which commands passed or failed;
• which architectural choice was selected;
• which directories have already been explored;
• why one approach was chosen over another.

That knowledge is often lost in the agent’s growing transcript. The agent then re-reads the same files, repeats repository searches, and revisits decisions it already made. This wastes tokens and makes long sessions slower and less consistent.

Thread treats those actions as a searchable session memory:

1. Agent hooks observe tool lifecycle events.
2. Thread creates a compact deterministic memory entry.
3. The entry is added to a local Moss SessionIndex.
4. A later PreToolUse checks exact-path memory and semantic similarity.
5. Relevant context is surfaced before the repeated action proceeds.

The goal is not to replace the agent’s context window. Thread provides a fast, focused recall layer for facts the agent should not have to rediscover.

Key properties

• Local hot path. After a session is opened, Moss addDocs() and query() run against the in-memory session index.
• Real-time updates. A read or edit can become searchable during the same agent session.
• Semantic recall. Thread can find conceptually related files and decisions, not only exact string matches.
• Deterministic core. File summaries, edit statistics, command records, and basic decision detection work without an LLM.
• Non-blocking behavior. Redundancy reminders do not hard-block the agent’s tool call.
• Named persistence. pushIndex() makes a session resumable under the same name.
• Cross-agent support. The same memory model supports Claude Code and current Codex lifecycle hooks.
• Optional AI enrichment. OpenRouter can improve summaries and decision extraction, but it is off by default and never runs on the hook hot path.
• Graceful degradation. Missing credentials or an unavailable provider does not break the coding agent.

How it works

Architecture

Claude Code / Codex
        │
        │ command hook JSON on stdin
        ▼
short-lived Thread hook process
        │
        │ newline-delimited JSON over a local Unix socket
        ▼
long-lived Thread daemon
        ├── Moss SessionIndex             local, in-memory search
        ├── ~/.thread/sessions/*.json     compact local mirror
        ├── debounced pushIndex()         named cloud persistence
        └── optional OpenRouter queue     asynchronous enrichment

The daemon is important. Claude Code and Codex launch command hooks as separate processes, while a Moss session is an in-process index. If every hook opened its own session, Thread would repeatedly reconstruct state and lose the intended local real-time workflow. Instead, short-lived hook processes communicate with one local daemon that owns the active Moss sessions.

The socket is stored at ~/.thread/thread.sock by default. If the daemon is not running, the hook attempts to start it as a detached process and then retries the local connection.

PreToolUse: recall before repetition

For a file read or exploration request, Thread:

1. Resolves the Thread session associated with the agent session ID and current directory.
2. Canonicalizes the requested path to avoid duplicate memories caused by symlinked path variants.
3. Checks the local entry map for an exact prior file read or exploration.
4. If no exact match exists, queries Moss with topK: 5 and hybrid retrieval using alpha: 0.75.
5. Accepts a semantic match at or above the configured similarity threshold, 0.86 by default.
6. Writes a redundancy entry for status accounting.
7. Returns a reminder through the agent-specific hook output format.

An exact reminder looks like this:

[Thread] This was already inspected at 14:03.
/workspace/src/auth.ts — 120 lines; defines authenticate(), validateToken().
The action is still allowed; reuse this memory unless fresh contents are necessary.

Thread intentionally omits a Claude permissionDecision and never returns a deny result. Normal agent permissions and tool behavior remain in effect.

PostToolUse: write memory after the action

After a supported tool succeeds, Thread creates the deterministic entry first:

• file content is summarized locally;
• edit statistics are calculated without storing a full diff;
• shell commands record an exit code;
• exploration tools record the target directory or query.

The daemon then:

1. updates the local entry map;
2. calls SessionIndex.addDocs() with upsert: true when Moss is connected;
3. atomically updates the local JSON mirror;
4. schedules a debounced Moss push five seconds after the latest mutation;
5. schedules optional AI enrichment after the deterministic write has completed.

If Moss mutation fails, the local entry remains available and the hook continues successfully.

Stop: capture decisions

When an agent finishes a turn, Thread examines the final assistant message when the hook payload exposes it. It detects decision-like statements such as:

Going with a local daemon because Moss sessions are process-local.
Decided: use SQLite for local metadata.
I’ll use a Unix socket instead of an HTTP port.

The deterministic detector stores a compact statement and, when present, the text following “because” as reasoning. With the optional AI layer enabled, the full recent agent message is classified asynchronously for cleaner {decision, reasoning} extraction.

Moss document shape

Each Thread entry becomes one Moss document:

{
  id: "file_read-...",
  text: "type file_read. path /workspace/src/auth.ts. ...",
  metadata: {
    type: "file_read",
    timestamp: "2026-07-18T10:15:30.000Z",
    ai_enhanced: "no",
    agent: "claude",
    agent_session_id: "...",
    path: "/workspace/src/auth.ts",
    thread_entry: "{...serialized compact entry...}"
  }
}

text is the canonical searchable representation. thread_entry preserves the compact structured record so a pushed Moss index can reconstruct status and resume behavior without a separate database.

What Thread records

Deterministic file summaries

Thread reads eligible files after a successful file-read event and derives a compact summary from:

• canonical file path;
• line count;
• first non-empty line;
• detected JavaScript/TypeScript functions, arrow functions, classes, and interfaces;
• detected Python def functions;
• detected Rust fn functions;
• detected Go functions.

Example:

/workspace/src/auth.ts — 120 lines; defines authenticate(token), validateToken(token); starts "/** Authentication helpers */"

Files larger than 1 MB, binary files containing null bytes, and ignored secret/build paths are skipped.

Edit summaries

Thread prefers the most accurate lightweight source available:

• Claude Edit: compare old_string and new_string;
• file replacement: compare the captured pre-edit snapshot with the current file;
• apply_patch: count added and removed patch lines while excluding patch headers.

The resulting memory is intentionally small:

/workspace/src/auth.ts — +14 / -6 lines

Shell command recognition

Every supported shell event is recorded as a command. Thread also conservatively recognizes common file reads and repository exploration so Codex can benefit even when it performs those operations through a shell tool.

Recognized read-style commands include:

cat  bat  head  tail  less  more  sed  awk

Recognized exploration-style commands include:

ls  find  fd  tree  rg --files  rg  grep

Only tokens that resolve to existing files are promoted to file-read memories. Complex shell programs, commands that change directories internally, or indirect paths may be recorded only as commands.

Requirements

• Node.js 20.4 or newer.
• macOS or Linux for the current Unix-socket daemon implementation.
• A Moss project ID and project key for semantic retrieval and cloud handoff.
• Claude Code and/or a current Codex client with lifecycle hooks enabled.
• An OpenRouter API key only when optional AI enrichment is enabled.

Thread can run without Moss credentials in local-mirror mode for diagnostics and deterministic logging, but semantic query, push, and cross-machine resume require Moss.

Installation

1. Install dependencies and build

From this repository:

npm install
npm run build

Link the CLI during local development:

npm link

Or install the checked-out package globally:

npm install -g .

Confirm the executable is available:

thread --version
thread --help

2. Configure Moss credentials

Create .env.local in the project where the coding agent runs:

MOSS_PROJECT_ID=your-project-id
MOSS_PROJECT_KEY=your-project-key

Thread searches for .env.local from the current working directory upward to the filesystem root. Credentials are loaded at CLI runtime and are not bundled into the compiled package.

You can also export the values in the shell:

export MOSS_PROJECT_ID=your-project-id
export MOSS_PROJECT_KEY=your-project-key

Process environment variables take precedence over .env.local.

3. Install agent hooks

Configure both supported agents:

thread install

Or select one:

thread install --agent claude
thread install --agent codex

The installer is additive and idempotent:

• unrelated hook groups are preserved;
• an existing settings file is copied to a sibling .thread-backup file;
• an earlier Thread hook group is replaced rather than duplicated;
• hook commands use absolute paths to the current Node executable and Thread CLI file.

Files modified by the installer:

After installing Codex hooks, open /hooks in Codex and review/trust the new command-hook definitions. Codex skips non-managed command hooks until their current definitions have been trusted.

Quickstart

Start an agent normally from the configured project:

claude
# or
codex

Use the agent for ordinary repository work. Thread starts its daemon on demand and creates a default memory-session name from the repository directory and agent session ID.

From another terminal in the same project:

thread status

Example:

Thread session: payments-abc123
Moss index: connected (local session)
Files touched: 6 (5 read, 3 edited)
Commands: 9  Decisions: 2
Redundancy warnings: 4
Potential tokens saved when warnings were followed: ~1860
AI-enhanced entries: 0/24
Last activity: 2026-07-18T10:15:30.000Z

Machine-readable output is available for demos and scripts:

thread status --json

Inspect a specific named session without changing the active mapping:

thread status --session payments-abc123

Sessions, persistence, and handoff

Default session resolution

Thread maintains these mappings in ~/.thread/state.json:

• agent session ID → Thread session name;
• working directory → currently active Thread session;
• working directory → named session pending for the next agent session.

When no explicit resume is pending, Thread generates a name from the current directory basename and a shortened agent session ID. Paths are canonicalized before they are used as state keys.

Local mirror

Every deterministic entry is mirrored to:

~/.thread/sessions/<url-encoded-session-name>.json

Writes are atomic: Thread writes a temporary owner-only file and renames it into place. This mirror supports status reporting and preserves compact entries when Moss credentials or connectivity are unavailable.

The local mirror is not a replacement for a pushed Moss index. It remains on the current machine and cannot provide cross-machine semantic retrieval by itself.

Background push

After each mutation, Thread resets a five-second timer. When the session has been idle for five seconds, the daemon calls pushIndex(). This groups bursts of tool events into fewer persistence operations while keeping the hook response independent of cloud latency.

Claude’s SessionEnd hook also requests a best-effort push. For a deliberate handoff, use an explicit push rather than depending on process shutdown timing:

thread push

Expected output:

Pushed 24 entries to Moss.

Resume by name

On another terminal, conversation, or machine using the same Moss project credentials:

thread resume payments-abc123
claude   # or codex

thread resume:

1. marks the name as current for the working directory;
2. marks it as pending for the next unseen agent session ID;
3. asks the daemon to open the named Moss session immediately;
4. lets MossClient.session(name) load the existing pushed index or start empty when it does not exist.

For a reliable cross-machine handoff:

# Machine A
thread push

# Machine B, with the same Moss credentials
thread resume payments-abc123
codex

All participants resuming the same Moss index must use a compatible embedding model. Thread uses the Moss session default and does not override the model ID.

Claude Code and Codex behavior

Thread uses the same internal event model for both agents but emits different hook responses where their public hook surfaces differ.

Installed events

Claude Code reminders

Claude Code’s PreToolUse supports hookSpecificOutput.additionalContext. Thread returns:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "[Thread] This was already inspected..."
  }
}

There is no permissionDecision. Thread therefore does not auto-approve, deny, or rewrite the tool input. Claude Code continues through its normal permission flow.

See the current Claude Code hooks reference for the complete event and output schema.

Codex reminders

Current Codex supports user hooks.json with SessionStart, PreToolUse, PostToolUse, and Stop, among other events. Thread returns the documented UI/event-stream field:

{
  "systemMessage": "[Thread] This was already inspected..."
}

The reminder is visible to the user. Current public Codex documentation does not guarantee that PreToolUse.systemMessage is injected into the model’s context, so Thread does not claim equivalent model-context delivery on Codex.

Codex commonly represents reads and repository inspection as shell commands. Thread handles direct read/edit names when present and also recognizes Bash, exec_command, and apply_patch-style payloads.

See the current Codex hooks guide for configuration, trust, event support, and output limitations.

Optional OpenRouter enhancement

The OpenRouter layer is off by default. It enhances deterministic memories; it does not replace them.

Enable it with stored CLI configuration:

thread config --ai true --openrouter-key "$OPENROUTER_API_KEY"

Or use environment variables:

THREAD_AI_ENABLED=true
OPENROUTER_API_KEY=your-key
OPENROUTER_MODEL=optional/model-slug

Model selection

When OPENROUTER_MODEL is not set, Thread:

1. calls OpenRouter’s GET /api/v1/models;
2. keeps text-output models whose prompt and completion prices both parse as zero;
3. sorts them by context length, creation time, and model ID;
4. uses the first result for the daemon lifetime.

Override the model when you want a specific free or paid model:

thread config --model google/gemma-3-27b-it:free

Thread sends standard chat-completion requests to OpenRouter’s documented POST /api/v1/chat/completions endpoint.

What AI enrichment changes

Asynchronous behavior

For file and decision entries:

1. the deterministic entry is fully written;
2. the hook response completes;
3. the daemon calls OpenRouter in the background;
4. a successful result upserts the same or a stable AI entry with ai_enhanced: true;
5. a failure is logged without removing or weakening the deterministic memory.

thread status may wait for an AI recap because it is an explicit CLI request, not an agent hook. Use --no-ai-recap for a fully local status response.

Data sent to OpenRouter

When AI enrichment is enabled:

• file enrichment can send up to the first 16,000 characters of an eligible source file, plus its path and deterministic summary;
• decision enrichment can send up to the last 16,000 characters of the agent message being classified;
• status recap can send a compact JSON representation of session entries, capped at 24,000 characters.

Do not enable the AI layer for repositories whose source or agent output must not be sent to OpenRouter. The deterministic Moss-backed core remains available with AI disabled.

Configuration reference

Environment variables

Configuration precedence

For values available in multiple places, Thread uses this effective precedence:

1. process environment;
2. nearest .env.local found by walking upward from the working directory;
3. ~/.thread/config.json for AI, model, and similarity settings;
4. built-in defaults.

Moss credentials are read from the environment or .env.local; thread config does not store them.

Stored configuration

Show the stored optional settings:

thread config

Example:

AI enabled: false
OpenRouter key: not set
OpenRouter model: auto-select a zero-price model
Similarity threshold: 0.86

Update settings:

thread config --ai true
thread config --openrouter-key "$OPENROUTER_API_KEY"
thread config --model provider/model-name
thread config --similarity-threshold 0.90

Changing stored configuration asks the current daemon to terminate. The next CLI command or hook starts a new daemon with the updated settings.

The config file is created with owner-only permissions. Environment variables still take precedence over stored values.

CLI reference

thread install

Install user-level hook configuration.

thread install [--agent claude|codex|both]

both is the default.

thread status

Print counts, potential token savings, Moss connectivity, and the optional AI recap.

thread status [--session NAME] [--json] [--no-ai-recap]

• --session NAME: inspect a named session instead of the current directory mapping.
• --json: return the ThreadStatus object as formatted JSON.
• --no-ai-recap: skip OpenRouter even when AI enrichment is enabled.

The status fields are:

interface ThreadStatus {
  sessionName: string
  mossConnected: boolean
  filesTouched: number
  filesRead: number
  filesEdited: number
  commandsRun: number
  decisionsLogged: number
  explorations: number
  redundancyWarnings: number
  potentialTokensSaved: number
  aiEnhancedEntries: number
  totalEntries: number
  lastActivity?: string
  aiRecap?: string
}

Potential token savings are estimated from the character count of entries associated with redundancy warnings, divided by four. The value is not a measured tokenizer result.

thread resume

Select a named Moss session for the next agent session in the current directory.

thread resume <session-name>

thread push

Persist the current or specified in-memory Moss session immediately.

thread push [--session NAME]

Without Moss credentials, the command reports that entries remain in the local mirror.

thread config

Read or update optional configuration.

thread config \
  [--ai true|false] \
  [--openrouter-key KEY] \
  [--model MODEL] \
  [--similarity-threshold 0..1]

Internal commands

thread hook and thread daemon are hidden implementation commands used by installed hooks. They are not normal user-facing entry points.

Local storage

Default layout:

~/.thread/
├── config.json                 optional AI/model/threshold settings
├── state.json                  agent-session and cwd mappings
├── daemon.pid                  active daemon process ID
├── thread.sock                 local Unix socket
├── thread.log                  non-fatal provider and hook errors
└── sessions/
    └── <session-name>.json     compact local session mirror

THREAD_HOME relocates this entire directory.

Config, state, and session snapshots are written with owner-only file modes. Directories are created with owner-only access where the platform honors POSIX modes.

The daemon can hold more than one named session in memory. Sessions are created lazily as agent events, status requests, or resume commands refer to them.

Security and privacy

Default ignored paths

Thread skips paths matching common secret or generated-data patterns, including:

• .env and .env.*;
• .pem, .key, .p12, and .pfx files;
• id_rsa and id_ed25519;
• credential and secret JSON-style files;
• .git, node_modules, dist, build, coverage, .next, target, vendor.

This is a defensive default, not a complete secret scanner. Do not assume every sensitive filename is covered.

Data boundaries

• Deterministic summaries read source locally.
• Moss documents contain compact summaries and structured metadata, not full file contents or full diffs.
• pushIndex() uploads those compact Moss documents and their locally computed embeddings.
• The local mirror contains the same compact entry structure.
• OpenRouter receives source/message content only when AI enrichment is explicitly enabled.
• Shell stdout and stderr are not stored in memory entries.
• Agent transcripts are read only as a best-effort fallback for decision detection when a stable final-message field is unavailable.

Hook safety

• Thread does not return a hard-block decision.
• Thread does not rewrite tool inputs.
• Thread does not auto-approve tool permissions.
• Hook errors are caught and logged; the hook exits successfully so it does not break the agent loop.
• The installer preserves unrelated user hooks and writes a backup before replacing settings.

Review generated hook configuration before trusting it, particularly on shared machines.

Failure behavior

Thread’s default posture is fail-open because it is a recall assistant, not a policy-enforcement system.

Known limitations

• Warnings are not prevention. Thread counts redundancy warnings, not confirmed skipped tool calls.
• Token savings are approximate. The estimate uses four characters per token and can differ from the agent model’s tokenizer.
• Codex delivery differs from Claude. Codex systemMessage is user-visible, but current public docs do not guarantee model-context injection on PreToolUse.
• Shell parsing is conservative. Compound scripts, dynamic paths, subshells, and internal cd commands may not produce file-read memories.
• File summaries are intentionally shallow without AI. They identify shape and signatures, not full program semantics.
• Decision detection is heuristic without AI. Some decisions will be missed and some planning statements may be classified as decisions.
• The current daemon uses a Unix socket. Windows is not currently supported.
• The local mirror is not semantic search. Moss credentials are required for the semantic query path.
• Cross-machine resume requires a completed push. Unpushed local entries do not appear on another machine.
• Concurrent sessions in the same directory share the current-directory status pointer. Agent session IDs still map independently, but thread status without --session shows the most recently active mapping.
• A live Moss credentials test is not part of the default suite. The repository tests exercise the local fallback and hook protocol without requiring secret credentials.

Troubleshooting

thread status says local mirror only

Check that both variables are available from the agent’s working directory:

echo "$MOSS_PROJECT_ID"
test -n "$MOSS_PROJECT_KEY" && echo "MOSS_PROJECT_KEY is set"

If you use .env.local, confirm it is in the project directory or one of its parents. Restart the daemon by changing/saving Thread configuration, or end the current daemon after verifying its PID, then allow the next hook to start it again.

Inspect the non-fatal log:

tail -n 100 ~/.thread/thread.log

Claude Code does not show reminders

1. Open ~/.claude/settings.json.
2. Confirm a Thread PreToolUse group exists.
3. Run thread install --agent claude again; installation is idempotent.
4. Start a new Claude Code session.
5. Read the same eligible file twice.
6. Inspect ~/.thread/thread.log for hook or daemon errors.

Codex says hooks need review

Open /hooks in Codex and trust the current Thread hook definitions. Trust is associated with the exact hook definition; rebuilding or relinking Thread can change its path or hash and require another review.

Also verify hooks have not been disabled:

[features]
hooks = true

thread status has no active session

No hook event has associated the current directory with a session yet. Either start the coding agent and let SessionStart fire, or choose a name explicitly:

thread resume my-session
thread status

Cross-machine resume is empty

On the source machine:

thread push --session my-session

Confirm the command reports a Moss push rather than local-mirror mode. Then verify the destination machine uses the same Moss project credentials and exact session name.

AI enrichment remains at zero

Check configuration:

thread config

Confirm AI is enabled and an OpenRouter key is set. Then inspect ~/.thread/thread.log for model-selection or chat-completion errors. AI enrichment is asynchronous, so status may briefly show the deterministic entry first.

Resetting local Thread state

Thread state is isolated under THREAD_HOME or ~/.thread. Before removing anything:

1. run thread push for sessions you want to keep in Moss;
2. stop the daemon after verifying daemon.pid belongs to Thread;
3. archive the directory if you may need the local mirrors later.

Deleting local state does not delete already pushed Moss indexes.

Development

Project layout

src/
├── ai.ts                 OpenRouter selection and enrichment
├── cli.ts                Commander commands and hook entry point
├── config.ts             .env.local and stored configuration
├── daemon.ts             Unix-socket server and request routing
├── handler.ts            lifecycle-event processing
├── heuristics.ts         summaries, diff stats, shell and decision detection
├── install.ts            Claude/Codex hook installation
├── ipc.ts                daemon client and startup retry
├── session-manager.ts    Moss sessions, local mirror, query, push, AI queue
├── state.ts              atomic JSON state persistence
└── types.ts              shared protocol and entry types

tests/
├── cli-integration.test.mjs
└── heuristics.test.mjs

Commands

npm run build
npm test
npm run check

The default suite covers:

• deterministic file summaries and signature extraction;
• edit line statistics;
• heuristic decision detection;
• shell read-path detection;
• status and token-savings accounting;
• live daemon IPC;
• repeated-read reminders for Claude and Codex output formats;
• file edits and shell command recording;
• additive, idempotent hook installation.

The default tests set an isolated THREAD_HOME and intentionally run without Moss credentials. A live authenticated Moss smoke test must be performed separately with a test project.

Manual end-to-end check

npm run build
npm link
thread install --agent claude
thread resume thread-manual-test
claude

Inside the agent session, ask it to read the same source file twice, make a small edit, run a command, and state an explicit decision. Then inspect:

thread status --json --no-ai-recap
thread push

See DEMO.md for a screen-recording-ready before/after walkthrough.

References

• Moss sessions integration guide
• Moss JavaScript sessions reference
• Moss SessionIndex class
• Claude Code hooks reference
• Codex hooks guide
• OpenRouter quickstart
• OpenRouter model-list API