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"
}

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

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