og-drizzles/trache

Summary

Trache is a CLI tool that caches a Trello board locally in SQLite and provides Git-style pull/push semantics for reading and mutating cards without hitting the Trello API repeatedly. It's specifically designed to minimize token usage when AI agents (like Claude) need to work with Trello boards — local reads cost nothing, and only explicit push commands write back to Trello. It supports multi-board management, checklist/label operations, and includes a batch command mode optimized for agent workflows.

Great for

Great for people interested in building local-first caching layers for external SaaS APIs, or optimizing AI agent workflows to reduce expensive API round-trips — specifically in the Trello/project-management space.

Easy wins

• +Add a CONTRIBUTING.md — the setup is already clean (Makefile, pyproject.toml, hatchling), just needs documented contribution workflow and how to get a Trello test token
• +Add `trache list list` command to show all lists on the board — the lists table is already in SQLite (add_list, read_lists are implemented in db.py) but there's no CLI surface for it
• +The comment commands are explicitly API-direct (documented as bypassing local-first model) — adding a warning/confirmation prompt before destructive comment operations (delete) would be a concrete UX improvement with a clear scope
• +Add OAuth flow support — pyproject.toml has an `[oauth]` optional dep for authlib already declared but the CLI only supports API key + token auth; wiring up the authlib OAuth flow is a bounded, well-scoped addition

Red flags

• !Only 1 commit in the entire repo history — this is a fully-formed project dropped in one shot, which makes it impossible to understand design evolution or assess maintainer responsiveness
• !No lockfile (pip-only with no poetry.lock or requirements.txt pinning) — minor for a CLI tool but means reproducible installs depend on upstream package stability
• !The list name ambiguity issue is documented in README ('List names aren't unique... will silently pick one') but the underlying resolve_list_id in db.py appears to use case-insensitive name matching without any disambiguation warning to the user — confirmed in test_db.py TestResolve where no duplicate-name test exists
• !last_commit_at is 2026-03-17 — either the repo has a future-dated commit (clock issue or intentional) or this data is stale; either way worth flagging as unusual

Code quality

The SQLite layer in db.py is notably well-designed: WAL mode, explicit transaction rollback on error, clean separation between _connect (internal) and connect (public alias), and a two-phase crash-safe migration path from the old file-based store with a sentinel file. The CLI in app.py has consistent dual-mode output (human Rich vs machine JSON) throughout every command, which is rare and genuinely useful for agent consumption. Test coverage is thorough — test_db.py exercises CRUD, migration, resolution, and snapshots; test_cli.py covers error paths including invalid UID6 format, duplicate labels, and missing checklists. One minor inconsistency: comment commands bypass the local-first model entirely (documented, but the architectural asymmetry means push doesn't cover all mutations).

What makes it unique

The local-first + Git-semantics framing for a project management API cache is a genuinely distinct niche — most Trello tools are either full sync clients or thin API wrappers. The explicit optimization for AI agent token costs (batch mode, UID6 short identifiers, machine JSON output mode, `trache agents` command that prints agent-readable setup instructions) is a concrete differentiator. That said, the concept of 'cache external API locally, diff, push' is well-trodden in other domains (git-bug, etc.) and this is a single-API implementation with no plugin architecture.