tokenjuice AGENTS.md

Repository Guidelines

Project Structure & Module Organization

tokenjuice is a TypeScript CLI/library. Main source lives in src/:

• src/cli/ contains the CLI entrypoint.
• src/core/ contains shared reducers, rule loading, and other host-agnostic logic.
• src/hosts/ contains host-specific integrations (codex/, claude-code/, cursor/, pi/, opencode/, openclaw/) plus shared hook helpers under shared/.
• src/rules/ contains built-in JSON rules and fixtures.

Tests live in test/ and mirror the source layout (test/core/, test/hosts/, test/hosts/shared/). Supporting docs live in docs/, packaging files in packaging/, and utility scripts in scripts/. dist/, release/, and src/core/builtin-rules.generated.ts are generated outputs; do not hand-edit them.

Build, Test, and Development Commands

• pnpm install installs dependencies.
• pnpm test runs the full Vitest suite and regenerates built-in rules first.
• pnpm typecheck runs TypeScript without emitting files.
• pnpm build rebuilds dist/, Pi runtime output, and packaged rules.
• pnpm verify is the pre-handoff gate: lint, circular-dep check (madge), typecheck, and the full Vitest suite.
• pnpm release:local runs the local release pipeline: tests, build, tarball, checksums, and Homebrew formula.
• pnpm exec vitest run test/hosts/codex.test.ts runs a focused test file during iteration.

For a quick smoke check after building, run node dist/cli/main.js --version.

Coding Style & Naming Conventions

Use TypeScript with ESM imports and explicit .js import suffixes in source files. Match the existing style:

• 2-space indentation
• named exports over default exports for library modules
• small, focused helpers in src/core/
• descriptive test names using describe / it

Keep generated files out of manual edits. If you change built-in rule data, rely on the existing scripts and test/build flows to regenerate derived output.

Host integrations

Every post-tool host adapter (codex, pi, opencode, openclaw) routes through the shared primitive compactBashResult in src/core/integrations/compact-bash-result.ts. New host behavior belongs in src/core/, not in an adapter. Pre-tool rewriters (claude-code, codebuddy, cursor, vscode-copilot) funnel commands through tokenjuice wrap and shared helpers in src/hosts/shared/pre-tool-wrap.ts. When adding or changing a host, see docs/integration-playbook.md for the install/doctor/uninstall checklist and update the hardcoded host list in src/cli/main.ts accordingly.