linear-todosA CLI tool that executes Python source code to manage todos via Linear's API. Creates tasks with natural language dates, priorities, and scheduling. This is...
Install via ClawdBot CLI:
clawdbot install avegancafe/linear-todos⚠️ This is a SOURCE-EXECUTION skill. The agent runs Python code fromsrc/linear_todos/when you invoke CLI commands. This is not instruction-only. Reviewsrc/linear_todos/api.pybefore first use.
>
🔐 Security Note: This skill stores your Linear API key in plaintext JSON at~/.config/linear-todos/config.jsononly if you run thesetupcommand. 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 toapi.linear.app(Linear's official GraphQL API). No data is sent elsewhere. Seesrc/linear_todos/api.pyfor the API client implementation.
| Variable | Required | Description |
|----------|----------|-------------|
| LINEAR_API_KEY | Yes | Your Linear API key from 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)
https://api.linear.app/graphql (Linear's official API). No telemetry, no third-party services.~/.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.main.py and code in src/linear_todos/ when you run CLI commands.LINEAR_API_KEY in the process environment to test the key. This is only during the setup session and is not persisted.always: false). Will not auto-enable itself for all agents.src/linear_todos/api.py — All HTTP requests to Linearsrc/linear_todos/config.py — Config file handlingsrc/linear_todos/setup_wizard.py — Interactive setupsrc/linear_todos/cli.py — CLI commandsLINEAR_API_KEY in your shell instead of running setup — no plaintext file is created.src/linear_todos/api.py to verify HTTP destinations before first use.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 -ePreferred 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 isolatedA powerful todo management system built on Linear with smart date parsing, priorities, and a complete CLI workflow.
# 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 reviewGet your API key from linear.app/settings/api. Recommendation: Create a dedicated API key with minimal scope for this skill.
uv run python main.py setupThis interactive wizard will:
~/.config/linear-todos/config.json (plaintext JSON)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"
}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 descriptionNatural 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 tomorrowList all your todos.
uv run python main.py list [options]
Options:
--all Include completed todos
--json Output as JSONMark 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-456Reschedule 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"Daily review command that organizes todos by urgency.
uv run python main.py reviewOutput sections:
Interactive setup wizard to configure your Linear integration.
uv run python main.py setupThis will guide you through:
~/.config/linear-todos/config.jsonWhen the user asks for reminders or todos:
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"Ask if not specified:
When asked "what do I have to do today", run:
uv run python main.py reviewPresent the output exactly as formatted - don't reformat or summarize.
When user says they completed something, mark it done:
uv run python main.py done ISSUE-123| 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 |
| 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 |
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 timezoneCommon timezone values: America/New_York, America/Los_Angeles, Europe/London, Europe/Paris, Asia/Tokyo
Settings are loaded in this order (later overrides earlier):
~/.config/linear-todos/config.jsonLINEAR_*--team, --state| 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 |
Generated Feb 23, 2026
Freelancers can use Linear Todos to organize client projects and deadlines directly from their terminal. It parses natural language dates like 'next Friday' to schedule tasks, and integrates with Linear's issue tracking for seamless project updates. This streamlines workflow without switching between multiple apps.
Development teams can manage sprint tasks and bug fixes via CLI commands, syncing with Linear's API for real-time updates. It supports priorities and scheduling to align with agile methodologies, enhancing collaboration and reducing manual entry. This is ideal for remote teams using terminal-based workflows.
Individuals can track personal goals and daily todos with smart date parsing for reminders like 'in 3 days'. It uses Linear's robust platform for organization, offering a CLI alternative to GUI tools for tech-savvy users. This helps maintain focus and efficiency in personal projects.
Small business owners can manage operational tasks such as inventory checks or customer follow-ups through automated CLI commands. It integrates with Linear for team visibility, allowing quick creation and updates without leaving the terminal. This reduces administrative overhead and improves task accountability.
Offer a free tier with basic todo management and CLI access, while premium features include advanced scheduling, team analytics, and priority support. Revenue comes from monthly subscriptions for businesses needing enhanced productivity tools. This leverages Linear's ecosystem to attract users seeking streamlined workflows.
Target large organizations by bundling Linear Todos with custom integrations, security audits, and dedicated support. Revenue is generated through annual licenses and consulting services for deployment. This model capitalizes on the need for secure, scalable task management in corporate environments.
Distribute Linear Todos as a paid skill or plugin in developer marketplaces, with one-time purchases or usage-based pricing. Revenue streams include sales commissions and optional premium support packages. This taps into the growing demand for CLI tools among programmers and tech teams.
💬 Integration Tip
Use environment variables for API keys to avoid storing plaintext config files, and review the source code in api.py to ensure secure HTTPS calls to Linear's API.
Manage Trello boards, lists, and cards via the Trello REST API.
Sync and query CalDAV calendars (iCloud, Google, Fastmail, Nextcloud, etc.) using vdirsyncer + khal. Works on Linux.
Manage tasks and projects in Todoist. Use when user asks about tasks, to-dos, reminders, or productivity.
Master OpenClaw's timing systems. Use for scheduling reliable reminders, setting up periodic maintenance (janitor jobs), and understanding when to use Cron v...
Calendar management and scheduling. Create events, manage meetings, and sync across calendar providers.
Kanban-style task management dashboard for AI assistants. Manage tasks via CLI or dashboard UI. Use when user mentions tasks, kanban, task board, mission con...