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:

Recommended Security Practices

1. 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:

CODEBLOCK0

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

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

Quick Start

CODEBLOCK2

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

CODEBLOCK3

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:

CODEBLOCK4

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

CODEBLOCK5

Commands

create

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

CODEBLOCK6

Natural Date Examples:

CODEBLOCK7

Complete Examples:

CODEBLOCK8

list

List all your todos.

CODEBLOCK9

done

Mark a todo as completed.

CODEBLOCK10

snooze

Reschedule a todo to a later date.

CODEBLOCK11

review

Daily review command that organizes todos by urgency.

CODEBLOCK12

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.

CODEBLOCK13

This will guide you through:

• - Verifying your API key
• Selecting your Linear team
• Configuring initial and done states
• Saving settings to INLINECODE34

For Agents

When the user asks for reminders or todos:

1. Parse Natural Language Dates

Convert user input to specific dates:

CODEBLOCK14

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:

CODEBLOCK15

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

4. Complete Todos

When user says they completed something, mark it done:

CODEBLOCK16

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:

CODEBLOCK17

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)
• INLINECODE46 sets due date to 7 days from now, end of day in your timezone
• INLINECODE47 sets due date to end of tomorrow in your timezone

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

Configuration Precedence

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

1. 1. Default values (none)
2. Config file: INLINECODE53
3. Environment variables: INLINECODE54
4. Command-line flags: --team, INLINECODE56

Files