Lets an AI client create, edit, and render product roadmaps using a plain-text domain-specific language.
Also known as lolay/nowline, @nowline/mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.13.0
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is Nowline MCP?
Nowline lets an AI client create, edit, and render product roadmaps using a plain-text domain-specific language.
Summary generated from the project's README
About Nowline MCP server
Product managers and engineering teams can manage roadmaps as code using Nowline, a text-first domain-specific language. Instead of using traditional Gantt chart software, users write plain .nowline files that are human-readable, version-controlled, and easy to review in pull requests. This approach allows for structured planning through indented, keyword-driven text that describes swimlanes, items, milestones, and dependencies.
Developers can integrate this into their workflow by installing the MCP server via the Claude Code marketplace or using the CLI for local operations. The toolchain supports rendering these text files into various formats including SVG, PNG, PDF, HTML, Mermaid, XLSX, and MS Project XML. It also features a live-reload server for real-time previews and a validation engine with over 30 rules to catch planning mistakes early. The system is designed for composability, allowing users to include and merge different roadmap files into a single view.
What you can do with it
- 1Validate roadmap syntax and logicCheck a roadmap file for errors using strict validation rules before committing it to version control.
- 2Sync roadmaps with spreadsheet toolsExport roadmap data into an Excel format for stakeholders who prefer spreadsheet views.
Written from the project's README. Every use case is checked against a quote from it.
How to install Nowline MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Nowline MCP in Claude Code
$ claude mcp add nowline -- npx -y @nowline/mcpInstall Nowline MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"nowline": {
"command": "npx",
"args": [
"-y",
"@nowline/mcp"
]
}
}
}Install Nowline MCP in VS Code
.vscode/mcp.json
{
"servers": {
"nowline": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@nowline/mcp"
]
}
}
}Install Nowline MCP in VS Code CLI
$ code --add-mcp '{"name":"nowline","type":"stdio","command":"npx","args":["-y","@nowline/mcp"]}'Install Nowline MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"nowline": {
"command": "npx",
"args": [
"-y",
"@nowline/mcp"
]
}
}
}Install Nowline MCP in Codex
$ codex mcp add nowline -- npx -y @nowline/mcpInstall Nowline MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.nowline] command = "npx" args = ["-y", "@nowline/mcp"]
Install Nowline MCP in Gemini CLI
$ gemini mcp add -s user nowline npx -- -y @nowline/mcpInstall Nowline MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"nowline": {
"command": "npx",
"args": [
"-y",
"@nowline/mcp"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablelolay/nowline is public and reachablegithub.com/lolay/nowline ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/lolay/nowline ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @nowline/mcpPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWhat is Nowline?
Nowline is a text-first DSL for describing product and engineering roadmaps — human readable and machine readable. You write plain .nowline text files — indented, keyword-driven, diff-friendly — and tooling renders them as timelines, validates them, and composes them.
nowline v1
roadmap minimal "Starter" start:2026-01-05 scale:2w author:"Jane Doe"
swimlane engineering "Engineering"
item research "Research" duration:3w status:done
item design "Design" duration:2w status:in-progress remaining:5d
item build "Build" duration:3w status:planned
Renders to:
Why Nowline?
- Text, not a Gantt chart. Version-controlled, diffable, reviewable in a PR.
- Indentation, not XML. Roadmaps read like outlines, because that's how people think about them.
- Strict enough to catch mistakes. 30+ validation rules, clear error messages with line and column numbers.
- Composable.
includeother files with explicitmerge/ignore/isolatesemantics.
Quick start
Install the CLI from your package manager:
brew trust lolay/tap # macOS / Linux / WSL (one-time)
brew install lolay/tap/nowline
Debian/Ubuntu and Windows users can grab the latest .deb or .exe from GitHub Releases. See packages/cli/README.md for the full install matrix (including man nowline setup).
Toolchain
Two-tier Node policy: Node ≥ 22 to consume @nowline/* packages (engines.node on every published package), Node 26 (.nvmrc) to develop. CI tests both versions on every PR. See Toolchain & Supported Versions for the full policy and bump procedure.
Render your first roadmap:
nowline examples/minimal.nowline # writes ./minimal.svg
nowline --version
Or scaffold a brand-new file from a template:
nowline --init my-project # ./my-project.nowline
nowline --init my-project -t teams # ./my-project.nowline (teams template)
To give an AI agent Nowline tools, install the plugin from this repo's marketplace. In Claude Code:
/plugin install nowline --marketplace lolay/nowline
GitHub Copilot CLI and Codex read the same marketplace; see plugins/nowline/README.md for those and the other ways to add the MCP server.
For the VS Code / Cursor / VSCodium extension, search Nowline on the VS Code Marketplace or Open VSX.
0.xversioning.nowlineis on0.x.ywhile we settle the embed surface and IDE expansion. Public APIs may change between minor versions; full SemVer guarantees apply once we ship1.0. Seespecs/releasing.mdfor the version contract.
To run from a checkout for local development (pnpm install && pnpm build), see CONTRIBUTING.md.
Use the CLI
nowline is verbless: rendering is the default. Other operations are flags on the same command.
Render (default)
nowline roadmap.nowline # writes ./roadmap.svg
nowline roadmap.nowline -f png # writes ./roadmap.png
nowline roadmap.nowline -f pdf # writes ./roadmap.pdf
nowline roadmap.nowline -f html # writes ./roadmap.html
nowline roadmap.nowline -f mermaid # writes ./roadmap.md
nowline roadmap.nowline -f xlsx # writes ./roadmap.xlsx
nowline roadmap.nowline -f msproj # writes ./roadmap.xml
nowline roadmap.nowline -o roadmap.pdf # format inferred from extension
nowline roadmap.nowline -o - # SVG to stdout
nowline roadmap.nowline --theme dark --now 2026-03-15
nowline roadmap.nowline --now - --asset-root ./brand --no-links --strict
nowline roadmap.nowline -f pdf --page-size a4 --orientation landscape --margin 0.5in
cat roadmap.nowline | nowline - # stdin → ./roadmap.svg
The render pipeline is @nowline/core parse → @nowline/layout layout → @nowline/renderer SVG → format-specific exporter. Output is byte-for-byte deterministic for the same input, theme, and --now. A single nowline binary ships every format — see packages/cli/README.md for install details.
Validate (--dry-run)
Run the full pipeline (parse + validate + layout + format) without writing. Exits 0 on success, 1 if any errors are emitted.
nowline roadmap.nowline --dry-run
nowline roadmap.nowline -n # short alias
cat roadmap.nowline | nowline - --dry-run # read stdin
nowline roadmap.nowline -n --diagnostic-format json # machine-readable output
nowline - -n --format=json < roadmap.nowline # same, json is the default here
--diagnostic-format text|json picks the stderr format; with --dry-run --format=json it defaults to json, otherwise text. JSON mode writes one { "$nowlineDiagnostics": "1", "diagnostics": [...] } document to stderr whenever any diagnostic exists, warnings included, so a warnings-only source exits 0 with the document. Clean sources print nothing.
Convert text ↔ JSON
Convert is just -f json (or -f nowline to go the other way). Input format is inferred from the extension; --input-format overrides for unusual filenames.
nowline roadmap.nowline -f json -o roadmap.json # text → JSON
nowline roadmap.json -f nowline -o roadmap.nowline # JSON → text (canonical)
nowline roadmap.nowline -f json -o - | jq '.ast.roadmapDecl.name'
The emitted JSON carries a top-level "$nowlineSchema": "1" so downstream tools can detect schema changes. Comments are not preserved across round-trips — see packages/cli/README.md for the canonical printer rules.
Serve (--serve)
Run a live-reload preview in the browser. Great while authoring.
nowline roadmap.nowline --serve # http://127.0.0.1:4318
nowline roadmap.nowline --serve -p 4400 -t dark --open
nowline roadmap.nowline --serve -o latest.svg # rewrite latest.svg on each rebuild
The server re-parses, re-validates, re-lays-out, and re-renders on every file change; connected clients refresh automatically via Server-Sent Events. Validation errors are displayed as an overlay on top of the most recent successful render.
Init (--init)
Scaffold a new .nowline file in cwd. The positional argument is the project name, not a file path. .nowline is auto-appended.
nowline --init # ./roadmap.nowline (default name)
nowline --init my-project # ./my-project.nowline
nowline --init my-plan.nowline # ./my-plan.nowline (literal)
nowline --init my-project --template=teams # use the teams template
minimal, teams, and product correspond to the files under examples/. Existing files are silently overwritten.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Validation error (parse failure, invalid reference, any include error such as a missing include, a wave rule across included files) |
| 2 | Usage error (missing input, bad flags, unsupported format, file not found, empty stdin, invalid --diagnostic-format, binary→TTY refusal) |
| 3 | Output error (cannot write to destination) |
Manual
After any package-manager install (brew install lolay/tap/nowline, npm install -g @nowline/cli, or the .deb from GitHub Releases), man nowline shows the CLI manual and man 5 nowline shows the full DSL reference. Both man pages also ship as standalone assets on every GitHub Release — see packages/cli/man/ for the mdoc sources.
Language at a glance
File structure
nowline v1 // 1. version directive (optional, must be first)
include "shared/teams.nowline" // 2. includes
include "brand.nowline" config:isolate
config // 3. config section (optional)
scale
name: weeks
style enterprise
bg: blue
fg: navy
roadmap r "My Roadmap" // 4. roadmap section
swimlane platform
item x "Work item" duration:1w status:done
Entities
| Keyword | Purpose |
|---|---|
roadmap |
The top-level roadmap declaration. At most one per file. |
swimlane |
A horizontal lane of work. |
item |
A unit of work inside a swimlane. |
parallel |
A block whose children run concurrently. |
group |
A logical grouping of items, rendered together. |
anchor |
A named date on the timeline. |
milestone |
A point-in-time marker that depends on work. |
wave |
A barrier across every swimlane: no work in the next wave starts until this one ends. |
footnote |
A callout anchored to one or more entities. |
person, team |
Ownership references. |
non-working, working |
Days that consume no work (weekends, holidays, closures) and the exceptions that give them back. Config entries with date:, start: / end: or every:; a declaration named weekend replaces the business weekend. A dated closure with a title is labelled on the chart (Thanksgiving · 2d) and carried into the MS Project and Mermaid exports; a titled working day is labelled with the days it adds (Crunch Saturday · +1d). |
style, symbol, label, size, status, scale, calendar, default |
Config and declaration entries. |
Properties
item auth "Auth refactor"
duration: 2w // duration literal: d, w, m, q, y
status: in-progress // builtin or custom from config
owner: sam // id reference (person or team)
wave: build // barrier the item belongs to (a declared wave)
after: kickoff // dependency (single)
after: [kickoff, approvals] // dependency (list)
remaining: 30% // percentage
labels: [security, p0] // list of label ids
link: https://… // URL (bare, no quotes)
Roadmap start date
A roadmap may carry an optional start:YYYY-MM-DD that anchors the timeline baseline:
roadmap platform-2026 "Platform 2026" start:2026-01-06
- If the roadmap contains any
anchor, or anymilestonewith adate:property,start:is required. - Every such date must be on or after
start:. - A pure-relative roadmap (built from
duration:andafter:only) does not needstart:. - Across
includes that don't useroadmap:ignore, the parent and any included roadmap must agree onstart:— both absent, or both present with the same value. Mismatches are errors, not silent overrides.
Includes
include "teams.nowline" // merge everything (default)
include "snippet.nowline" config:ignore // skip child config
include "partner.nowline" roadmap:isolate // render child as a separate region
merge— default: child content is merged; parent definitions win on collision.ignore— child content of that kind is discarded.isolate— child roadmap is preserved as a self-contained region (requires aroadmapin the child).
Waves never merge. Under roadmap:merge or roadmap:isolate, an included file that declares a roadmap, swimlanes, or waves must declare the same waves as its parent, in the same order with the same start floors (NL.E0202).
For the full grammar reference, see specs/dsl.md.
Examples
Progressively-richer examples are included. Every build of main renders them, and the renderer fixtures in tests/, at review.nowline.dev.
examples/minimal.nowline— smallest complete file.examples/capacity.nowline— lane and itemcapacity:with on-call support taking a quarter of team bandwidth; lane utilization underline.examples/sizing.nowline— T-shirtsize:entries plus shortening calendar span withcapacity:(parallel work).examples/teams.nowline— persons, teams, anchors, milestones, footnotes.examples/product.nowline— full config, styles, labels, parallels, groups, descriptions.examples/long.nowline— stress test: eight swimlanes, ~160 items, parallels, groups, anchors, milestones, footnotes, cross-cutting labels. Used for layout/render perf.examples/nested.nowline+examples/nested/— parent Security swimlane plus five isolated per-team roadmap includes (iOS, Android, Web, Platform, Data). Demonstratesroadmap:isolate.examples/waves.nowline—wavebarriers: three waves (Foundations, Build, Launch) across three lanes, agroup wave:that assigns its children, unwaved background work, and milestonesafter:a wave.examples/waves-program.nowline+examples/waves-program/— multi-team waves: web and API team files re-declare the same waves (with a start floor), so each renders alone and the program file merges them behind one barrier.
Editor support
A TextMate grammar lives at grammars/nowline.tmLanguage.json. It works in any editor that supports TextMate grammars (VS Code, Sublime Text, Zed, IntelliJ via third-party plugins, etc.). A first-class LSP server and VS Code extension are tracked in packages/lsp/ and packages/vscode-extension/.
Use as a library
@nowline/core is a pure-TypeScript parser, typed AST, and validator built on Langium. Everything the CLI does on top of parsing is itself built against this library. See packages/core/README.md for the API and a usage example.
Status
Nowline is on v0.x — published to Homebrew, npm, the VS Code Marketplace, Open VSX, and GitHub Releases. The parser, validator, layout, renderer, every export format (SVG, PNG, PDF, HTML, Markdown+Mermaid, XLSX, MS Project XML), and the verbless CLI (--dry-run, --init, --serve) are usable today. Breaking changes may land between 0.x minor versions while the embed surface and IDE expansion settle; full SemVer guarantees kick in at 1.0. The release-by-release roadmap lives in specs/milestones.md.
Contributing
Bug reports, feature requests, and pull requests are welcome. Start with CONTRIBUTING.md for setup, build/test commands, and the expected workflow. Before opening an issue, please check the templates under .github/ISSUE_TEMPLATE/. Security issues should follow SECURITY.md. All participation is governed by our CODE_OF_CONDUCT.md.
Design specs for the DSL, renderer, CLI, IDE integrations, and OSS milestones live under specs/ — start there to understand how Nowline is shaped before touching code.
License
Apache 2.0 — see LICENSE.
Nowline MCP questions
How do I add Nowline MCP to Claude Code?
Run claude mcp add nowline -- npx -y @nowline/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Nowline MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What formats can Nowline render to?
Nowline can render roadmaps to SVG, PNG, PDF, HTML, Mermaid, XLSX, and MS Project XML.
How do I use Nowline with an AI agent?
You can install the plugin from the repository's marketplace in Claude Code using the command: /plugin install nowline --marketplace lolay/nowline.
Is Nowline version-control friendly?
Yes, because it uses plain text files, roadmaps are version-controlled, diffable, and reviewable in pull requests.