team-toon-tack (ttt)

繁體中文 | English

Optimized task workflow for Claude Code — supports Linear and Trello, saves significant tokens compared to MCP.

Features

• Token Efficient — Local cycle cache eliminates repeated API calls, saving significant tokens vs MCP
• Multi-source Support — Works with both Linear and Trello
• Smart Task Selection — Auto-pick highest priority unassigned work with /work-on next
• Multi-team Support — Sync and filter issues across multiple teams/boards
• Flexible Sync Modes — Choose between remote (immediate sync) or local (offline-first, sync later with --update)
• Completion Modes — Four modes for task completion (Linear): simple, strict review, upstream strict, upstream not strict
• QA Team Support — Auto-update parent issues in QA team to "Testing" when completing dev tasks (Linear)
• Attachment Download — Auto-download images and files to local .ttt/output/ for AI vision analysis
• Blocked Status — Set tasks as blocked when waiting on external dependencies
• Persistent Estimates — Store local human-effort estimates that survive future ttt sync
• Claude Code Plugin — Install plugin for /ttt:* commands and auto-activated skills
• Cycle History — Local .toon files preserve cycle data for AI context

Quick Start

1. Install & Initialize

npm install -g team-toon-tack

# For Linear
export LINEAR_API_KEY="lin_api_xxxxx"

# For Trello
export TRELLO_API_KEY="your-api-key"
export TRELLO_TOKEN="your-token"

cd your-project
ttt init

During init, you'll be prompted to select your task source (Linear or Trello) and configure:

For Linear:

• Dev team: Your development team (single selection)
• Dev testing status: Testing/review status for your dev team (optional)
• QA team(s): For cross-team parent issue updates, each with its own testing status (optional)
• Completion mode: How task completion is handled (see below)
• Status source: remote (update Linear immediately) or local (work offline, sync with ttt sync --update)

For Trello:

• Board: The Trello board to sync
• User: Your Trello username
• Status mappings: Map Trello lists to Todo (supports multiple lists)/In Progress/Done
• Label filter: Optional label to filter cards

Completion Modes (Linear only)

Mode	Behavior
simple	Mark task as Done + parent as Done. Default when no QA team configured.
strict_review	Mark task to dev testing + parent to QA testing.
upstream_strict	Mark task as Done + parent to Testing. Falls back to dev testing if no parent. Default when QA team configured.
upstream_not_strict	Mark task as Done + parent to Testing. No fallback if no parent.

Note: Trello always uses simple completion mode as it doesn't support parent issues.

2. Install Claude Code Plugin (Optional)

/plugin marketplace add wayne930242/team-toon-tack
/plugin install team-toon-tack@wayne930242

3. Daily Workflow

In Claude Code (with plugin installed):

/ttt:sync              # Fetch all issues/cards for current cycle
/ttt:work-on next      # Pick highest priority task & start working
/ttt:estimate MP-123 6 # Save a local 6-hour estimate
/ttt:done              # Complete task with AI-generated summary

Or using CLI directly:

ttt sync
ttt work-on next
ttt estimate MP-123 6
ttt done -m "Completed the task"

---

CLI Reference

ttt init

Initialize configuration in current directory.

ttt init                           # Interactive mode (select source)
ttt init --source=linear           # Initialize for Linear
ttt init --source=trello           # Initialize for Trello
ttt init --user alice@example.com  # Pre-select user
ttt init --label Frontend          # Set default label
ttt init --force                   # Overwrite existing config

ttt sync

Sync current cycle issues from Linear/Trello.

ttt sync              # Sync Todo/In Progress issues (fast)
ttt sync --all        # Sync all issues regardless of status
ttt sync MP-123       # Sync specific issue only
ttt sync --update     # Push local status changes to remote (for local mode)

ttt work-on

Start working on a task.

ttt work-on              # Interactive selection
ttt work-on MP-123       # Specific issue
ttt work-on next         # Auto-select highest priority

ttt estimate

Save a local human-effort estimate that persists in .ttt/cycle.toon.

ttt estimate MP-123 6                         # Save a 6-hour estimate
ttt estimate 2.5                              # Save estimate for current in-progress task
ttt estimate MP-123 16 --note "API pending"   # Save estimate with a note
ttt estimate MP-123 --clear                   # Remove saved estimate

ttt done

Mark task as completed.

ttt done                         # Auto-select if only one in-progress
ttt done MP-123                  # Specific issue
ttt done -m "Fixed the bug"      # With completion message
ttt done MP-123 --from-remote    # Fetch from remote (bypasses local data check)

Use --from-remote (or -r) when the issue exists in remote but not in local sync data.

ttt status

Show or modify task status.

ttt status              # Show current in-progress task
ttt status MP-123       # Show specific issue status
ttt status MP-123 --set +1      # Move to next status
ttt status MP-123 --set done    # Mark as done
ttt status MP-123 --set blocked # Set as blocked (waiting on dependency)

ttt show

Show issue details or search issues from local cycle data.

ttt show                       # Show all issues in local cycle data
ttt show MP-123                # Show specific issue from local data
ttt show MP-123 --remote       # Fetch specific issue from remote
ttt show --label frontend      # Filter by label
ttt show --status "In Progress" --user me   # My in-progress issues
ttt show --priority 1          # Show urgent issues
ttt show --export              # Export as markdown

ttt config

Configure settings.

ttt config              # Show current configuration
ttt config status       # Configure status mappings
ttt config filters      # Configure label/user filters
ttt config teams        # Configure multi-team selection

Configuration

Directory Structure

your-project/
└── .ttt/
    ├── config.toon     # Team config (gitignore recommended)
    ├── local.toon      # Personal settings (gitignore)
    ├── cycle.toon      # Current cycle data + local estimates (auto-generated)
    └── output/         # Downloaded attachments (images, files)

Environment Variables

Variable	Description
LINEAR_API_KEY	Required for Linear. Your Linear API key
TRELLO_API_KEY	Required for Trello. Your Trello API key
TRELLO_TOKEN	Required for Trello. Your Trello authorization token
TOON_DIR	Config directory (default: .ttt)

Trello Setup

1. Get your API key from: https://trello.com/power-ups/admin
2. Generate a token by visiting the authorization URL shown during ttt init
3. Set both TRELLO_API_KEY and TRELLO_TOKEN in your environment

Concept Mapping: Linear vs Trello

Concept	Linear	Trello
Container	Team	Board
Task	Issue	Card
Status	Workflow State	List
Tag	Label	Label
Sprint	Cycle	- (not supported)
Parent	Parent Issue	- (not supported)

Claude Code Plugin

Install the plugin for Claude Code integration:

/plugin marketplace add wayne930242/team-toon-tack
/plugin install team-toon-tack@wayne930242

Available Commands

Command	Description
/ttt:sync	Sync issues to local cycle data
/ttt:work-on	Start working on a task
/ttt:estimate	Save a local human-effort estimate
/ttt:done	Mark current task as completed
/ttt:status	Show or modify task status
/ttt:show	Show issue details or search issues

Auto-Activated Skill

The plugin includes a linear-task-manager skill that automatically activates when working with tasks, providing workflow guidance and best practices.

License

MIT