Linear Todos

Linear Todos

⚠️ This is a SOURCE-EXECUTION skill. The agent runs Python code from src/linear_todos/ when you invoke CLI commands. This is not instruction-only. Review src/linear_todos/api.py before first use.

🔐 Security Note: This skill stores your Linear API key in plaintext JSON at ~/.config/linear-todos/config.json only if you run the setup command. Use a dedicated API key with minimal scope. The key is only used for Linear API calls and is never transmitted elsewhere. Prefer environment variables (LINEAR_API_KEY) to avoid persisted state.

Audit Info: This skill makes HTTPS requests only to api.linear.app (Linear's official GraphQL API). No data is sent elsewhere. See src/linear_todos/api.py for the API client implementation.

Credentials

Config Path: ~/.config/linear-todos/config.json (created by setup, permissions 0o600)

Security & Auditing

What This Skill Does

• HTTP Requests: Makes HTTPS requests only to https://api.linear.app/graphql (Linear's official API). No telemetry, no third-party services.
• Data Storage: Stores your API key and config in ~/.config/linear-todos/config.json (plaintext, permissions 0o600) only if you run the setup command. Team/issue data is fetched fresh each run — nothing is cached locally except your config.
• Runtime Behavior: This skill runs from bundled Python source code (not preinstalled system tools). The agent executes main.py and code in src/linear_todos/ when you run CLI commands.
• Setup Behavior: During interactive setup, the wizard temporarily sets LINEAR_API_KEY in the process environment to test the key. This is only during the setup session and is not persisted.
• No Auto-Enable: Does not request platform privileges (always: false). Will not auto-enable itself for all agents.
• Code Locations:
  • src/linear_todos/api.py — All HTTP requests to Linear
  • src/linear_todos/config.py — Config file handling
  • src/linear_todos/setup_wizard.py — Interactive setup
  • src/linear_todos/cli.py — CLI commands

Recommended Security Practices

1. Use a dedicated API key: Create a separate Linear API token with minimal scope for this skill. Revoke it if you uninstall or stop using the skill.
2. Prefer environment variables: Set LINEAR_API_KEY in your shell instead of running setup — no plaintext file is created.
3. Audit the code: Review src/linear_todos/api.py to verify HTTP destinations before first use.
4. Run initial setup in isolation: If unsure, run the skill in a container/VM for the first setup to inspect behavior.

Cron Jobs (Optional)

The file cron-jobs.txt contains example cron entries for daily digests. It does NOT automatically install them. Adding cron jobs requires manual action:

# Review the examples first:
cat cron-jobs.txt

# If you want to use them, edit your crontab:
crontab -e

Preferred alternative: Use OpenClaw's built-in cron instead of system crontab:

openclaw cron add --name "morning-digest" --schedule "0 8 * * *" \
  --payload "linear-todos digest" --session-target isolated

A powerful todo management system built on Linear with smart date parsing, priorities, and a complete CLI workflow.

Quick Start

# Setup (run once)
uv run python main.py setup

# Create todos
uv run python main.py create "Call mom" --when day
uv run python main.py create "Pay taxes" --date 2025-04-15
uv run python main.py create "Review PR" --priority high --when week

# Natural language dates
uv run python main.py create "Meeting prep" --date "tomorrow"
uv run python main.py create "Weekly report" --date "next Monday"
uv run python main.py create "Dentist" --date "in 3 days"

# Manage todos
uv run python main.py list
uv run python main.py done ABC-123
uv run python main.py snooze ABC-123 "next week"

# Daily review
uv run python main.py review

Setup

1. Get API Key

Get your API key from linear.app/settings/api. Recommendation: Create a dedicated API key with minimal scope for this skill.

2. Run Setup

uv run python main.py setup

This interactive wizard will:

• Verify your API key
• List your Linear teams
• Let you select your todo team
• Configure initial and done states
• Save settings to ~/.config/linear-todos/config.json (plaintext JSON)

3. Manual Configuration (optional)

Instead of running setup, you can use environment variables:

export LINEAR_API_KEY="lin_api_..."
export LINEAR_TEAM_ID="your-team-id"
export LINEAR_STATE_ID="your-todo-state-id"
export LINEAR_DONE_STATE_ID="your-done-state-id"

Or create ~/.config/linear-todos/config.json:

{
  "apiKey": "lin_api_...",
  "teamId": "team-uuid",
  "stateId": "todo-state-uuid",
  "doneStateId": "done-state-uuid",
  "timezone": "America/New_York"
}

Commands

create

Create a new todo with optional timing, priority, and description.

uv run python main.py create "Title" [options]

Options:
  --when day|week|month     Relative due date
  --date DATE               Specific due date (supports natural language)
  --priority LEVEL          urgent, high, normal, low, none
  --desc "Description"      Add description

Natural Date Examples:

uv run python main.py create "Task" --date "tomorrow"
uv run python main.py create "Task" --date "Friday"
uv run python main.py create "Task" --date "next Monday"
uv run python main.py create "Task" --date "in 3 days"
uv run python main.py create "Task" --date "in 2 weeks"
uv run python main.py create "Task" --date "2025-04-15"

Complete Examples:

# Due by end of today
uv run python main.py create "Call mom" --when day

# Due in 7 days
uv run python main.py create "Submit report" --when week

# Specific date with high priority
uv run python main.py create "Launch feature" --date 2025-03-15 --priority high

# Natural language date with description
uv run python main.py create "Team meeting prep" --date "next Monday" --desc "Prepare slides"

# Urgent priority, due tomorrow
uv run python main.py create "Fix production bug" --priority urgent --date tomorrow

list

List all your todos.

uv run python main.py list [options]

Options:
  --all       Include completed todos
  --json      Output as JSON

done

Mark a todo as completed.

uv run python main.py done ISSUE_ID

# Examples
uv run python main.py done TODO-123
uv run python main.py done ABC-456

snooze

Reschedule a todo to a later date.

uv run python main.py snooze ISSUE_ID [when]

# Examples
uv run python main.py snooze TODO-123 "tomorrow"
uv run python main.py snooze TODO-123 "next Friday"
uv run python main.py snooze TODO-123 "in 1 week"

review

Daily review command that organizes todos by urgency.

uv run python main.py review

Output sections:

• 🚨 OVERDUE - Past due date
• 📅 Due Today - Due today
• ⚡ High Priority - Urgent/high priority items
• 📊 This Week - Due within 7 days
• 📅 This Month - Due within 28 days
• 📝 No Due Date - Items without dates

setup

Interactive setup wizard to configure your Linear integration.

uv run python main.py setup

This will guide you through:

• Verifying your API key
• Selecting your Linear team
• Configuring initial and done states
• Saving settings to ~/.config/linear-todos/config.json

For Agents

When the user asks for reminders or todos:

1. Parse Natural Language Dates

Convert user input to specific dates:

# "remind me Friday to call mom"
uv run python main.py create "Call mom" --date "2025-02-21"

# "remind me to pay taxes by April 15"
uv run python main.py create "Pay taxes" --date "2025-04-15"

# "remind me next week about the meeting"
uv run python main.py create "Meeting" --date "next Monday"

2. Determine Priority

Ask if not specified:

• Urgent (🔥) - Critical, do immediately
• High (⚡) - Important, do soon
• Normal (📌) - Standard priority (default)
• Low (💤) - Can wait

3. Daily Briefing

When asked "what do I have to do today", run:

uv run python main.py review

Present the output exactly as formatted - don't reformat or summarize.

4. Complete Todos

When user says they completed something, mark it done:

uv run python main.py done ISSUE-123

Date Parsing Reference

Priority Levels

Timezone Support

By default, due dates are calculated in UTC (end of day = 23:59:59 UTC). To use your local timezone for "end of day" calculations:

# Set via environment variable
export LINEAR_TIMEZONE="America/New_York"

# Or add to config.json
{
  "timezone": "America/New_York"
}

OpenClaw Integration: If running inside an OpenClaw workspace, the skill will automatically detect your timezone from USER.md (e.g., timezone: America/New_York). No manual configuration needed!

When a timezone is configured:

• --when day sets due date to end of today in your timezone (converted to UTC for Linear)
• --when week sets due date to 7 days from now, end of day in your timezone
• --date "tomorrow" sets due date to end of tomorrow in your timezone

Common timezone values: America/New_York, America/Los_Angeles, Europe/London, Europe/Paris, Asia/Tokyo

Configuration Precedence

Settings are loaded in this order (later overrides earlier):

1. Default values (none)
2. Config file: ~/.config/linear-todos/config.json
3. Environment variables: LINEAR_*
4. Command-line flags: --team, --state

Files