Installation

Singletrack ships as native distribution packages so orchestrators can load the protocol without pasting the full bootloader into every session. This page covers manual configuration for environments where you want explicit control over config paths, server processes, and skill registration.

Trial without installing: Paste the Recursive Bootstrap Prompt into a browser chat to run Singletrack with zero local setup. Graduate to MCP or a global skill when you want persistence.

1. Connecting via Model Context Protocol (MCP)

The Singletrack MCP server (github:vlutton/singletrack-mcp) runs as a child process of your orchestrator. It dynamically supplies the agent with the Singletrack state machine—phase gates, artifact conventions, and workspace scaffolding—without embedding the entire protocol in the chat context on every turn.

At runtime the host launches:

npx -y github:vlutton/singletrack-mcp

The -y flag accepts the package fetch non-interactively. Ensure Node.js 18+ and network access to the npm registry (and GitHub, for the package source) are available to the IDE process.

Reference: MCP server entry

Merge this object into your host’s mcpServers map. Do not remove existing servers; only add or update the singletrack key.

{
  "mcpServers": {
    "singletrack": {
      "command": "npx",
      "args": ["-y", "github:vlutton/singletrack-mcp"]
    }
  }
}

After editing config, restart the host or reload MCP servers per your tool’s documentation.

Claude Code setup

1. Open (or create) the global MCP config file:

   ~/.config/claude/mcp.json

2. If the file is empty, start with { "mcpServers": {} }. Append the singletrack entry from the reference block above inside mcpServers.

   Example (minimal new file):

   {
     "mcpServers": {
       "singletrack": {
         "command": "npx",
         "args": ["-y", "github:vlutton/singletrack-mcp"]
       }
     }
   }

3. Validate JSON syntax (trailing commas are invalid in strict JSON).

4. Restart Claude Code or run its MCP reload command so the new server registers.

5. Confirm: the singletrack server appears in the MCP server list and /singletrack (or your host’s equivalent) is available in the workspace.

Project-scoped config: Some setups support a project-level MCP file. Prefer global config for consistent behavior across repositories unless your team standardizes per-repo overrides.

Cursor setup

Cursor manages MCP servers through the UI rather than a single documented global path on all platforms.

1. Open Cursor Settings (gear icon or Cmd+, / Ctrl+,).
2. Navigate to Models → MCP (label may vary slightly by Cursor version).
3. Click + Add New Server (or Add MCP Server).
4. Configure the server:
   • Type: command (stdio transport)
   • Command: npx
   • Arguments: -y, github:vlutton/singletrack-mcp
     (Enter as separate args if the UI provides an argument list; otherwise use a single command line: npx -y github:vlutton/singletrack-mcp.)
5. Name the server singletrack when prompted.
6. Save and enable the server.
7. Reload the window or restart Cursor if tools do not appear immediately.

Verification: Open the MCP tools panel. You should see the singletrack server connected. Invoke a Singletrack slash command or tool exposed by the server to confirm the state machine is reachable.

Other MCP hosts

Any client that supports the Model Context Protocol with stdio command servers can use the same npx invocation. Map the reference JSON to the host’s config format (Cline, Windsurf, custom runners, etc.).

2. Global skill registration

The Open Skills Standard (and compatible hosts such as Claude Code) let you register reusable skill packages on disk. The orchestrator loads SKILL.md and supporting files when the skill is relevant, dropping the Singletrack state machine into the agent’s persistent skill layer instead of re-injecting the full bootloader prompt each session.

Repository: github.com/vlutton/singletrack-skill

Clone the skill repository

git clone https://github.com/vlutton/singletrack-skill.git ~/src/singletrack-skill

Use any stable path; ~/src/singletrack-skill is arbitrary. The clone must remain on disk—do not delete it after linking.

Open Skills path (~/.agent/skills)

For agents that follow the Open Skills layout, register the skill with a symbolic link:

mkdir -p ~/.agent/skills
ln -s ~/src/singletrack-skill ~/.agent/skills/singletrack

Replace ~/src/singletrack-skill with the absolute path to your clone if different. The link name singletrack is the skill identifier the host discovers.

Why symlink: Upstream updates are a git pull in the clone; the agent always reads through the link without copying files into place.

Claude Code skills path

Claude Code commonly reads skills from ~/.claude/skills/. Either symlink or clone directly:

git clone https://github.com/vlutton/singletrack-skill.git ~/.claude/skills/singletrack

Or, if you already cloned elsewhere:

mkdir -p ~/.claude/skills
ln -s ~/src/singletrack-skill ~/.claude/skills/singletrack

Verify registration

1. Confirm the target directory contains SKILL.md (and any bundled references).
2. Restart the orchestrator or start a new agent session (skills are often loaded at session start).
3. Ask the agent to confirm Singletrack skill availability or trigger a phase-gated workflow on a trivial intent.

MCP vs skill: use both?

They are complementary, not mutually exclusive:

• MCP exposes tools and slash commands tied to the running server process.
• Skill keeps the written protocol and phase boundaries in the agent’s skill index.

Many teams install one method first, then add the other. For maximum integration in Claude Code or Cursor, MCP is usually the first install; skill registration helps when you want the protocol always discoverable without server startup overhead.

Troubleshooting

For a zero-setup trial, use the master bootloader prompt before debugging native installs.