birdclaw 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.1.1 - 2026-04-27
+
+### Added
+
+- Add opt-in low-quality timeline filtering for year-scale tweet review, including date windows, originals-only mode, and CLI/API flags for hiding retweets, tiny replies, and link-only noise.
+
+### Fixed
+
+- Fix fresh npm installs so the packaged `birdclaw` binary includes its TypeScript runtime dependency.
+
 ## 0.1.0 - 2026-04-27
 
 ### Added

package/README.md

@@ -179,6 +179,7 @@ pnpm cli blocks import ~/triage/blocklist.txt --account acct_primary --json
 ```bash
 pnpm cli search tweets "local-first" --json
 pnpm cli search tweets "sync engine" --limit 20 --json
+pnpm cli search tweets --since 2020-01-01 --until 2021-01-01 --originals-only --hide-low-quality --limit 500 --json
 ```
 
 ### Export mentions for agents

package/bin/birdclaw.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const tsxCli = join(packageRoot, "node_modules", "tsx", "dist", "cli.mjs");
+const require = createRequire(import.meta.url);
+const tsxCli = require.resolve("tsx/cli");
 const birdclawCli = join(packageRoot, "src", "cli.ts");
 
 const result = spawnSync(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "birdclaw",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "Local-first X workspace for archives, DMs, mentions, and moderation",
 	"homepage": "https://github.com/steipete/birdclaw#readme",
 	"license": "MIT",

package/src/cli.ts

@@ -131,10 +131,14 @@ const searchCommand = program
 	.description("Search local data");
 
 searchCommand
-	.command("tweets <query>")
+	.command("tweets [query]")
 	.option("--resource <resource>", "home or mentions", "home")
 	.option("--replied", "Only replied items")
 	.option("--unreplied", "Only unreplied items")
+	.option("--since <date>", "Include tweets created at or after this date")
+	.option("--until <date>", "Include tweets created before this date")
+	.option("--originals-only", "Exclude authored replies that start with @")
+	.option("--hide-low-quality", "Hide RTs, tiny replies, and link-only noise")
 	.option("--limit <n>", "Limit results", "20")
 	.action((query, options) => {
 		const replyFilter = options.replied
@@ -146,6 +150,10 @@ searchCommand
 			resource: options.resource === "mentions" ? "mentions" : "home",
 			search: query,
 			replyFilter,
+			since: options.since,
+			until: options.until,
+			includeReplies: !options.originalsOnly,
+			qualityFilter: options.hideLowQuality ? "summary" : "all",
 			limit: Number(options.limit),
 		});
 		print(items, program.opts().json ?? false);

package/src/lib/queries.ts

@@ -12,6 +12,7 @@ import type {
 	QueryEnvelope,
 	QueryResponse,
 	ReplyFilter,
+	TimelineQualityFilter,
 	TimelineItem,
 	TimelineQuery,
 	TweetEntities,
@@ -124,6 +125,36 @@ function buildReplyClause(replyFilter: ReplyFilter) {
 	return "";
 }
 
+function buildTimelineQualityClause(qualityFilter: TimelineQualityFilter) {
+	if (qualityFilter === "all") {
+		return "";
+	}
+
+	return `
+    and not (
+      t.text like 'RT @%'
+      or (
+        t.like_count < 50
+        and (
+          (
+            length(trim(replace(t.text, 'https://t.co/', ''))) < 16
+            and t.media_count = 0
+          )
+          or (
+            t.text like '@%'
+            and length(trim(t.text)) < 60
+          )
+          or (
+            t.text glob '*https://t.co/*'
+            and t.media_count = 0
+            and length(trim(replace(t.text, 'https://t.co/', ''))) < 45
+          )
+        )
+      )
+    )
+  `;
+}
+
 export async function getQueryEnvelope(): Promise<QueryEnvelope> {
 	const db = getDb();
 	const counts = await Promise.all([
@@ -182,6 +213,10 @@ export function listTimelineItems({
 	account,
 	search,
 	replyFilter = "all",
+	since,
+	until,
+	includeReplies = true,
+	qualityFilter = "all",
 	limit = 18,
 }: TimelineQuery): TimelineItem[] {
 	const db = getNativeDb();
@@ -199,6 +234,21 @@ export function listTimelineItems({
 		"is_replied",
 		"t.is_replied",
 	);
+	where += buildTimelineQualityClause(qualityFilter);
+
+	if (!includeReplies) {
+		where += " and t.text not like '@%'";
+	}
+
+	if (since?.trim()) {
+		where += " and t.created_at >= ?";
+		params.push(since.trim());
+	}
+
+	if (until?.trim()) {
+		where += " and t.created_at < ?";
+		params.push(until.trim());
+	}
 
 	if (search?.trim()) {
 		join += " join tweets_fts fts on fts.tweet_id = t.id ";

package/src/lib/types.ts

@@ -2,6 +2,7 @@ export type ResourceKind = "home" | "mentions" | "dms";
 export type InboxKind = "mixed" | "mentions" | "dms";
 
 export type ReplyFilter = "all" | "replied" | "unreplied";
+export type TimelineQualityFilter = "all" | "summary";
 
 export interface AccountRecord {
 	id: string;
@@ -139,6 +140,10 @@ export interface TimelineQuery {
 	account?: string;
 	search?: string;
 	replyFilter?: ReplyFilter;
+	since?: string;
+	until?: string;
+	includeReplies?: boolean;
+	qualityFilter?: TimelineQualityFilter;
 	limit?: number;
 }
 

package/src/routes/api/query.tsx

@@ -1,6 +1,10 @@
 import { createFileRoute } from "@tanstack/react-router";
 import { queryResource } from "#/lib/queries";
-import type { ReplyFilter, ResourceKind } from "#/lib/types";
+import type {
+	ReplyFilter,
+	ResourceKind,
+	TimelineQualityFilter,
+} from "#/lib/types";
 
 function json(data: unknown) {
 	return new Response(JSON.stringify(data), {
@@ -23,6 +27,10 @@ function parseNumber(value: string | null) {
 	return Number.isFinite(parsed) ? parsed : undefined;
 }
 
+function parseQualityFilter(value: string | null): TimelineQualityFilter {
+	return value === "summary" ? "summary" : "all";
+}
+
 export const Route = createFileRoute("/api/query")({
 	server: {
 		handlers: {
@@ -34,6 +42,12 @@ export const Route = createFileRoute("/api/query")({
 					account: url.searchParams.get("account") ?? undefined,
 					search: url.searchParams.get("search") ?? undefined,
 					replyFilter: parseReplyFilter(url.searchParams.get("replyFilter")),
+					since: url.searchParams.get("since") ?? undefined,
+					until: url.searchParams.get("until") ?? undefined,
+					includeReplies: url.searchParams.get("originalsOnly") !== "true",
+					qualityFilter: parseQualityFilter(
+						url.searchParams.get("qualityFilter"),
+					),
 					limit: parseNumber(url.searchParams.get("limit")) ?? undefined,
 				};