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 | Variable | Required | Description | |----------|----------|-------------| | `LINEAR_API_KEY` | **Yes** | Your Linear API key from [linear.app/settings/api](https://linear.app/settings/api) | | `LINEAR_TEAM_ID` | No | Default team ID for todos | | `LINEAR_STATE_ID` | No | Default state for new todos | | `LINEAR_DONE_STATE_ID` | No | State for completed todos | | `LINEAR_TIMEZONE` | No | Your local timezone (e.g., `America/New_York`, `Europe/London`). Used for "end of day" calculations. Falls back to OpenClaw `USER.md` timezone if available. | **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: ```bash # 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: ```bash 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 ```bash # 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](https://linear.app/settings/api). **Recommendation:** Create a dedicated API key with minimal scope for this skill. ### 2. Run Setup ```bash 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: ```bash 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`: ```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. ```bash 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:** ```bash 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:** ```bash # 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. ```bash uv run python main.py list [options] Options: --all Include completed todos --json Output as JSON ``` ### done Mark a todo as completed. ```bash 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. ```bash 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. ```bash 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. ```bash 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: ```bash # "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: ```bash 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: ```bash uv run python main.py done ISSUE-123 ``` ## Date Parsing Reference | Input | Result | |-------|--------| | `today` | Today | | `tomorrow` | Next day | | `Friday` | Next occurrence of Friday | | `next Monday` | Monday of next week | | `this Friday` | Friday of current week (or next if passed) | | `in 3 days` | 3 days from now | | `in 2 weeks` | 14 days from now | | `2025-04-15` | Specific date | ## Priority Levels | Level | Number | Icon | Use For | |-------|--------|------|---------| | Urgent | 1 | 🔥 | Critical, blocking issues | | High | 2 | ⚡ | Important, time-sensitive | | Normal | 3 | 📌 | Standard tasks (default) | | Low | 4 | 💤 | Nice-to-have, can wait | | None | 0 | 📋 | No priority set | ## 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: ```bash # 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 | File | Purpose | |------|---------| | `main.py` | Main entry point for the CLI | | `src/linear_todos/cli.py` | CLI implementation with all commands | | `src/linear_todos/api.py` | Linear API client | | `src/linear_todos/config.py` | Configuration management | | `src/linear_todos/dates.py` | Date parsing utilities | | `src/linear_todos/setup_wizard.py` | Interactive setup wizard |