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.

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:

Agent hooks observe tool lifecycle events.
Thread creates a compact deterministic memory entry.
The entry is added to a local Moss SessionIndex.
A later PreToolUse checks exact-path memory and semantic similarity.
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:

Resolves the Thread session associated with the agent session ID and current directory.
Canonicalizes the requested path to avoid duplicate memories caused by symlinked path variants.
Checks the local entry map for an exact prior file read or exploration.
If no exact match exists, queries Moss with topK: 5 and hybrid retrieval using alpha: 0.75.
Accepts a semantic match at or above the configured similarity threshold, 0.86 by default.
Writes a redundancy entry for status accounting.
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:

updates the local entry map;
calls SessionIndex.addDocs() with upsert: true when Moss is connected;
atomically updates the local JSON mirror;
schedules a debounced Moss push five seconds after the latest mutation;
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

Entry type	Trigger	Stored information	Not stored
`file_read`	Read tool or recognizable shell read	Canonical path, timestamp, line count, signatures, first meaningful line, estimated character count	Full file contents
`file_edit`	Edit, Write, or `apply_patch`	Canonical path and `+added / -removed` line count	Full diff
`command`	Bash, shell, or command execution	Command string, timestamp, exit code	Full stdout/stderr
`exploration`	Glob, Grep, directory listing, repository search	Directory/path and pattern or command	Search output corpus
`decision`	Agent turn completion	Decision statement and optional reasoning	Entire transcript
`redundancy`	Relevant memory found before a tool call	Related entry ID, reminder, estimated avoidable characters	A claim that the tool was actually prevented

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:

Agent	Settings file
Claude Code	`~/.claude/settings.json`
Codex	`${CODEX_HOME:-~/.codex}/hooks.json`

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:

marks the name as current for the working directory;
marks it as pending for the next unseen agent session ID;
asks the daemon to open the named Moss session immediately;
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

Event	Claude Code	Codex	Thread behavior
`SessionStart`	Yes	Yes	Resolve/open the Thread and Moss session
`PreToolUse`	Yes	Yes	Query exact and semantic memory before reads/exploration
`PostToolUse`	Yes	Yes	Record successful reads, edits, commands, and exploration
`PostToolUseFailure`	Yes	Not installed	Record failed shell commands with a non-zero fallback exit code
`Stop`	Yes	Yes	Detect decisions from the final assistant message when available
`SessionEnd`	Yes	Not installed	Request a best-effort push

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:

calls OpenRouter’s GET /api/v1/models;
keeps text-output models whose prompt and completion prices both parse as zero;
sorts them by context length, creation time, and model ID;
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

Feature	Deterministic behavior	AI-enhanced behavior
File summary	Path, line count, signatures, first meaningful line	One-sentence semantic description of what the file does
Decision extraction	Phrase-pattern matching	Classification and normalized `{decision, reasoning}` pairs
Status	Counts and estimates	Optional one-paragraph session recap

Asynchronous behavior

For file and decision entries:

the deterministic entry is fully written;
the hook response completes;
the daemon calls OpenRouter in the background;
a successful result upserts the same or a stable AI entry with ai_enhanced: true;
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

Variable	Required	Default	Purpose
`MOSS_PROJECT_ID`	For Moss	None	Moss project identifier
`MOSS_PROJECT_KEY`	For Moss	None	Moss project key used to open sessions
`THREAD_HOME`	No	`~/.thread`	Local state, socket, logs, and mirrors
`THREAD_AI_ENABLED`	No	`false`	Enable OpenRouter enrichment
`OPENROUTER_API_KEY`	For AI	None	OpenRouter bearer token
`OPENROUTER_MODEL`	No	Auto-selected zero-price model	Explicit OpenRouter model slug
`THREAD_SIMILARITY_THRESHOLD`	No	`0.86`	Minimum semantic match score from `0` to `1`
`CODEX_HOME`	No	`~/.codex`	Location used when installing Codex hooks

Configuration precedence

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

process environment;
nearest .env.local found by walking upward from the working directory;
~/.thread/config.json for AI, model, and similarity settings;
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

Failure	Thread behavior	Agent impact
Missing Moss credentials	Store compact entries in the local mirror; report `local mirror only`	Tool continues
Moss session open fails	Log error and use local mirror	Tool continues
Moss `addDocs()` fails	Keep entry in memory/local snapshot; mark connectivity false	Tool continues
Moss query fails	Log error and return no semantic reminder	Tool continues
Background push fails	Log error; keep local entries	Tool continues
OpenRouter key missing	Skip AI enrichment	Deterministic behavior unchanged
OpenRouter request fails	Keep deterministic entry; log error	Hook already completed
Daemon absent	Attempt detached startup and retry local socket	Hook remains fail-open
Daemon startup fails	Log hook error and emit no reminder	Tool continues
Secret, binary, or oversized file	Skip file summary/indexing	Tool continues
Invalid settings JSON during install	Stop installation with an error rather than overwrite it	Existing file remains

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

Open ~/.claude/settings.json.
Confirm a Thread PreToolUse group exists.
Run thread install --agent claude again; installation is idempotent.
Start a new Claude Code session.
Read the same eligible file twice.
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:

run thread push for sessions you want to keep in Moss;
stop the daemon after verifying daemon.pid belongs to Thread;
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.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
tests		tests
video/output		video/output
.env.example		.env.example
.gitignore		.gitignore
DEMO.md		DEMO.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Thread

Contents

Why Thread exists

Key properties

How it works

Architecture

PreToolUse: recall before repetition

PostToolUse: write memory after the action

Stop: capture decisions

Moss document shape

What Thread records

Deterministic file summaries

Edit summaries

Shell command recognition

Requirements

Installation

1. Install dependencies and build

2. Configure Moss credentials

3. Install agent hooks

Quickstart

Sessions, persistence, and handoff

Default session resolution

Local mirror

Background push

Resume by name

Claude Code and Codex behavior

Installed events

Claude Code reminders

Codex reminders

Optional OpenRouter enhancement

Model selection

What AI enrichment changes

Asynchronous behavior

Data sent to OpenRouter

Configuration reference

Environment variables

Configuration precedence

Stored configuration

CLI reference

thread install

thread status

thread resume

thread push

thread config

Internal commands

Local storage

Security and privacy

Default ignored paths

Data boundaries

Hook safety

Failure behavior

Known limitations

Troubleshooting

thread status says local mirror only

Claude Code does not show reminders

Codex says hooks need review

thread status has no active session

Cross-machine resume is empty

AI enrichment remains at zero

Resetting local Thread state

Development

Project layout

Commands

Manual end-to-end check

References

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`PreToolUse`: recall before repetition

`PostToolUse`: write memory after the action

`Stop`: capture decisions

`thread install`

`thread status`

`thread resume`

`thread push`

`thread config`

`thread status` says `local mirror only`

`thread status` has no active session