aware-connector: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm install                              # runtime deps are MCP-only (see below); the CLI uses none
node src/cli.ts <command>                # run the CLI (login | me | search <q> | people | logout)
node src/cli.ts search <q> --limit 5     # search flags: --limit N, --all; --refresh bypasses the feed cache
node src/mcp.ts                          # run the MCP server (speaks JSON-RPC on stdio; not interactive)
npm test                                 # run all tests (node --test over test/*.ts)
node --test test/auth.test.ts            # run a single test file
node --test --test-name-pattern="refresh" # run tests whose name matches a pattern
npm run typecheck                        # tsc --noEmit (the only "build" — nothing is compiled/emitted)
npm run lint                             # eslint . (type-aware rules; needs a green typecheck to be meaningful)

There is no build step. TypeScript runs directly via Node's native type-stripping; tsc is used only for type-checking. ESLint carries only type-aware rules and the no-console ban described below — style is left to the compiler's strict settings.

Runtime constraints

• Node 24+ and macOS only. Relies on native fetch, TS type-stripping, node:test, and parseArgs, plus the macOS security CLI (keychain) and pbpaste (bootstrap). 24 is the floor because it is the active LTS, not because of a language feature — the code also runs on 22.18+, where type-stripping stopped needing a flag. Development happens on the version mise.toml pins (26); CI proves both ends of that range.
• Node type-stripping is strip-only, so TS syntax that emits code is forbidden: no parameter properties (constructor(private x) — declare fields explicitly), no enums, no namespaces. Local .ts imports must include the .ts extension. erasableSyntaxOnly in tsconfig.json enforces this: without it the typecheck happily accepts an enum that crashes with ERR_INVALID_TYPESCRIPT_SYNTAX the first time Node loads the file.
• Runtime deps are confined to the MCP entry point. @modelcontextprotocol/server and zod exist only for src/mcp.ts; src/cli.ts and everything it imports stay dependency-free, so node src/cli.ts works against an empty node_modules. Keep it that way. @modelcontextprotocol/server is deliberately not @modelcontextprotocol/sdk: the latter pulls express/hono for HTTP transports this stdio server never uses (91 packages vs 2).