LinearPlus

LinearPlus is a small CLI-first bridge for Linear API capabilities that are not reliably exposed through the current connector surface.

Product position — a shim, by design

LinearPlus exists to be slightly better than the official Linear MCP connector where it falls short — nothing more. It is a shim until Linear's own surface catches up (Daniel, 2026-06-10). That means:

• Only build the delta. Issues/comments/projects CRUD work through the official connector; LinearPlus must not duplicate them. Current delta: initiative writes (create/ensure/attach — the connector is read-only for initiatives), workspace dumps, local SQLite analytics.
• Every verb carries a sunset test: "does the official connector do this now?" When it does, the verb retires.
• No deep roots. The durable layer is LinearDB (the local mirror + analytics, useful regardless of connector quality); LinearPlus stays thin on top. OAuth app name in Linear: LPlus (Linear rejects app names containing the word "Linear").

LinearPlus uses LinearDB for connectivity and local Linear data sync. See LINEARDB.md for the product boundary: OAuth app access, workspace identity checks, SQLite schema, retries, and time-series/related-data storage.

The first workflow is initiative management:

• Create or reuse a Linear initiative by name.
• Attach an existing Linear project to an initiative.
• Summarize issue analytics across the Greenmark Linear team.
• Emit redacted JSON evidence suitable for Eidos/Codex loops.

Credentials

Preferred Greenmark/recurring setup is the LinearDB OAuth install flow:

export LINEARDB_GREENMARK_OAUTH_CLIENT_ID=<client-id>
export LINEARDB_GREENMARK_OAUTH_CLIENT_SECRET=<client-secret>

lineardb --account greenmark connect

The first greenmark profile is expected to connect Daniel's daniel@eidosagi.com Linear login and validate access to team GMW. LinearPlus/LinearDB never prints OAuth tokens or writes them to repo files.

Verify workspace/team access before a Greenmark run:

python -m linearplus.cli auth-check --team-key GMW

Prefer explicit account selection:

python -m linearplus.cli --account greenmark auth-check --team-key GMW

An explicit account only uses LINEARDB_GREENMARK_* credentials. It will not fall back to ambient LINEARPLUS_* or LINEAR_* credentials.

Pairing For LinearDB OAuth

LinearPlus uses LinearDB for account credentials. It does not create the Linear OAuth app, but it can consume the local LinearDB token store after connection.

1. Run the intended command with --dry-run first when available.

2. Create or select the LinearDB OAuth app and ensure this callback URL is configured:

   http://localhost:8721/oauth/callback
   

3. Put the OAuth app client id/secret in a local shell or vault-backed environment variable:

   export LINEARDB_GREENMARK_OAUTH_CLIENT_ID=<client-id>
   export LINEARDB_GREENMARK_OAUTH_CLIENT_SECRET=<client-secret>

4. Connect with the intended Linear login:

   lineardb --account greenmark connect

5. Run the narrow approved live command and capture redacted evidence.

Linear references:

• https://linear.app/docs/api-and-webhooks
• https://linear.app/developers/graphql

Greenmark Bootstrap

Dry run:

python -m linearplus.cli greenmark-bootstrap --dry-run

Live run:

python -m linearplus.cli greenmark-bootstrap

The live run creates or reuses the Greenmark AI Search Visibility initiative and attaches project 079b8875-9c80-41c8-b4b0-ea09834a7065.

Greenmark Analytics

Dry run:

python -m linearplus.cli greenmark-analytics --dry-run

Live read-only run:

python -m linearplus.cli greenmark-analytics

The live run reads issues for Linear team key GMW and emits JSON counts by state type, state, priority, assignee, project, and label, plus sample issue summaries and oldest open issues. Use --team-key, --page-size, or --sample-size to tune the report.

Greenmark Data Dump

Dry run:

python -m linearplus.cli greenmark-dump --dry-run

Live read-only dump:

python -m linearplus.cli greenmark-dump

The live run pulls raw task data for Linear team key GMW, computes the same analytics, and writes a JSON artifact under outputs/greenmark/ in the LinearPlus plugin root. Use --output /path/to/file.json for an exact path or --output-dir /path/to/dir for a timestamped artifact directory.

Account-Wide SQLite Dump

Dry run:

python -m linearplus.cli account-dump --dry-run

Live read-only SQLite dump:

python -m linearplus.cli account-dump

Greenmark account profile form:

python -m linearplus.cli --account greenmark account-dump --skip-related

The live run reads all accessible Linear teams, pulls issues for each team, and writes a local SQLite database under outputs/linear/. The database stores raw JSON plus queryable current-state tables and timeline tables:

• Current state: teams, issues, projects, users, labels, issue_labels, and metadata.
• Per-run time series: sync_runs and issue_snapshots.
• Related issue data: comments, attachments, issue_history, and issue_state_spans.

Use an explicit path when you want a stable local database:

python -m linearplus.cli account-dump --sqlite /path/to/linear.sqlite

Use --skip-related for a faster teams/issues-only refresh when comments, attachments, issue history, and state spans are not needed.

See LINEAR_DATA_EXPORT.md for the credential boundary, SQLite schema, time-series tables, related-data tables, and useful local SQL queries.

Generic Commands

python -m linearplus.cli initiative-get --name "Greenmark AI Search Visibility"
python -m linearplus.cli initiative-ensure --name "Greenmark AI Search Visibility" --status Planned
python -m linearplus.cli attach-project --initiative-id <initiative-id> --project-id <project-id>