The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Linear Project listing page.
Three interoperable Agent Skills and an optional MCP server for creating, maintaining, and reconciling Linear projects without pulling unrelated work into scope.
This collection is an Openly Useful project: practical infrastructure people can inspect, adapt, and improve.
Openly Useful LLC is the planned legal entity and remains formation-pending. Openly Useful is currently operated by its founder as an individual, and this repository does not claim that the LLC is formed, active, or the current operator. publisher.json is a repo-local projection of the public publisher authority. The founder-owner has authorized external source and registry publication while formation proceeds; namespace verification, provider authentication, and provider review remain provider-specific steps.
| Skill | Use it to |
|---|---|
linear-bootstrap-scoped-project | Create a net-new project, establish the key-bearing team, link canonical sources, and import legacy work safely. |
linear-sync-project-work | Keep implementation evidence, backlog gaps, blockers, and status current while work proceeds. |
linear-reconcile-project-history | Find an existing project, move high-confidence related issues, and capture legacy evidence as [HISTORICAL]. |
The skills hand work to one another rather than duplicating responsibilities:
@openly-useful/linear-project-mcp-server turns the workflows into 13 typed MCP tools. It can create a dedicated Linear team or subteam, bootstrap a scope-labeled project, capture active or [HISTORICAL] issues idempotently, find and explicitly move reviewed reconciliation candidates, and link verified evidence.
The server calls Linear directly through its official TypeScript SDK. GitHub evidence is optional and read-only. Obsidian support is optional, local, restricted to allowlisted Markdown directories, and never copies note contents into Linear when adding a link.
All mutations are disabled by default and require an exact organization allowlist, a scope-code allowlist, team/project gates, and a literal per-tool confirmation. See the server setup and security guide for installation and client configuration.
The MCP integration has four intentionally distinct names:
| Name | Meaning |
|---|---|
linear_project | Canonical Codex MCP registration alias and the name used with codex mcp commands. |
@openly-useful/linear-project-mcp-server | npm package name. It becomes installable from npm after the first successful package release. |
linear-project-mcp-server | Package executable and MCP protocol server artifact name. |
linear-project-mcp-write-window | Package helper for explicitly opening, inspecting, and closing a bounded write window. |
For a source checkout, build the package and register the local executable with Codex:
These commands contain no credentials. Supply adapter credentials through a protected launcher or secret store rather than command arguments or committed client configuration. See the MCP client guide for the npm command that applies after the first release and for the expected read-only acceptance checks.
Linear issue identifiers inherit their prefix from a team, not a project or label. A workflow that must begin at XY-1 therefore needs a new team with key XY, a verified empty issue history, and immediate readback of the first created issue. These skills stop instead of pretending that a project label can provide that guarantee.
Clone the repository, then copy the skills you want into the user-level skills directory supported by your agent.
For Codex:
Start a new task or restart the agent if its skill catalog does not refresh automatically.
The repository root is one aggregate plugin containing all three canonical skill directories. .codex-plugin/plugin.json and .claude-plugin/plugin.json both point to ./skills/ and .mcp.json; no provider-specific skill copies or symlinks are maintained. The MCP config uses npx/npm exec to install the immutable @openly-useful/linear-project-mcp-server@0.1.0 package and launch its server entry explicitly. This avoids ever selecting the package's separate write-window helper and remains portable across host shells. Repo-local Codex and Claude marketplace catalogs point back to the repository root for the same reason.
Registration files are generated from manifest.json, publisher.json, and the MCP package metadata:
The write form changes only repo-local registration files. It does not install a plugin, add a marketplace to a host, authenticate, publish a package, submit an MCP Registry record, or change the founder-authorization gate.
After installing or upgrading the plugin, start a new Codex task or restart Claude Code so the host discovers the newly registered MCP tools. The plugin never embeds credentials or scope values. Supply LINEAR_API_KEY or LINEAR_ACCESS_TOKEN and the exact LINEAR_ALLOWED_* settings through the host environment or a protected launcher. Without them the server still starts, writes remain disabled, and Linear tools fail closed with configuration guidance.
The MCP Registry record is mcp/linear-project-mcp-server/server.json. Its registry identity is org.openlyuseful/linear-project, while its npm package remains @openly-useful/linear-project-mcp-server. The official Registry requires server.json.name and package.json.mcpName to match; the repository validator enforces that equality together with package and version alignment.
The skills do not include credentials, a background daemon, or permission to monitor or mutate unrelated projects.
Create a project with a dedicated issue sequence:
Keep current implementation synchronized:
Reconcile an existing project:
Historical capture is deliberately separate from active work. A historical issue:
[HISTORICAL];HISTORICAL labels;Historical only: true and Actionability: none;Every workflow is read-first and scope-gated:
The repository validator uses only the Python standard library:
To validate the MCP server too:
The repository validator checks skill structure, metadata, references, manifest entries, MCP package metadata, evaluations, placeholder text, and common private-data leaks. Pull requests run both validation paths in GitHub Actions. The MCP compatibility job runs the full server check on Node.js 20, 22, and 24; distribution validation runs once, and package-content inspection runs only on Node.js 24.
python3 scripts/validate.py --external-publication --publication-target npm-package checks the founder-owner authorization plus the exact publisher identity, policy URLs, namespace, repository provenance, package identity, and registry metadata used by the npm artifact. The MCP package runs that fail-closed gate from prepublishOnly. Formation-pending is not itself an npm package blocker because the current operator is the founder-individual and the founder-owner authorization is explicitly effective during formation. Generic provider requirements remain blocking for MCP Registry and provider submissions until their separate workflows are completed.
Do not contribute credentials, private repository content, customer data, local absolute paths, raw conversations, or organization-specific source inventories. Examples must use synthetic names and identifiers. Public source markers should be sanitized and should reveal no secret or personal data.
See CONTRIBUTING.md for the repository-specific workflow. Openly Useful's organization-wide Code of Conduct and Security Policy apply.
Released under the MIT License.