Reads

Reads is a local-first research tracking and memory CLI. It helps humans and agents turn questions into hypotheses, evidence, and explicit graph links, while keeping every change auditable through an event log.

Why Reads

• Keep research state consistent across sessions and agents.
• Preserve provenance and deterministic history for every write.
• Move from ad-hoc notes to explicit reads, edges, tasks, and lifecycle transitions.

For the deeper rationale, read docs/philosophy-of-reads.md.

Installation

Requirements:

• Node.js 20+ (recommended for npm/global install)
• Bun 1.3+ (required for source-mode development commands)
• jq (optional, for JSON scripting examples)

Install from source:

git clone <your-fork-or-this-repo-url> reads-ts
cd reads-ts
bun install

Run from source:

bun run src/cli.ts --help

Supported global install flow:

cd reads-ts
bun link
export BUN_INSTALL="${BUN_INSTALL:-$HOME/.bun}"
export PATH="$BUN_INSTALL/bin:$PATH"
rd --help

Install from npm:

npm install -g reads-ts
rd --help

Runtime note:

• Published CLI uses Node (dist/cli.js with #!/usr/bin/env node).
• Bun is still the repository package-manager/development standard.

Platform support:

• Linux and macOS are the primary validated targets.
• Windows is currently best-effort (no dedicated CI matrix yet).

Persist PATH for future bash shells:

echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.bashrc
echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.bashrc

Quick start

RD="bun run src/cli.ts"
W1=$(mktemp -d)
W2=$(mktemp -d)

$RD --workspace "$W1" init --prefix rd
R1=$($RD --workspace "$W1" --json create "Claim: Tau217 predicts progression" --type claim | jq -r '.data.readId')
R2=$($RD --workspace "$W1" --json create "Finding: cohort result supports Tau217" --type finding | jq -r '.data.readId')
$RD --workspace "$W1" link "$R2" "$R1" --type supports --justification "Cohort analysis supports the claim"
$RD --workspace "$W1" transition "$R1" under-review --evidence "Initial supporting evidence logged"
$RD --workspace "$W1" task create "$R1" --type research --instruction "Find two independent replications"
$RD --workspace "$W1" doctor
$RD --workspace "$W1" export "$W1/snapshot.json"
$RD --workspace "$W2" import "$W1/snapshot.json"

Documentation

• Docs home: docs/README.md
• Docs landing page (GitHub Pages): docs/index.md
• Tutorial and quickstart: docs/tutorial-quickstart.md
• Philosophy of Reads: docs/philosophy-of-reads.md
• CLI reference: docs/cli.md
• Operations and recovery: docs/operations.md
• Architecture and data model: docs/architecture.md
• Agent prompt JSON contract: docs/agent-prompt-json.md
• Releasing and npm publishing: docs/releasing.md

Development policy

For contributors, dependency management is Bun-only:

• bun.lock is the only lockfile.
• package.json declares packageManager: bun@....
• Run bun run check:policy in local checks and CI.
• Feel free to use agents if 1) it responds to an issue, 2) the issue has the tag agOK.

License

MIT.