Skip to content

Quickstart

Install SpecsGraph on your own server, connect a GitHub repository and Claude Code, then have an agent propose a requirement that you review and publish.

This guide takes you from an empty server to a published requirement. It follows the self-hosted path, which is how you run SpecsGraph today; SpecsGraph Cloud is coming soon. It uses the Northwind Commerce example from the rest of the docs: an online store with contexts such as Orders, Billing and Catalog. Swap in your own system as you go.

Before you start

  • A Linux server that meets the minimum requirements, with a domain name pointing at it. The examples use https://specsgraph.example.com.
  • A GitHub repository that holds the code you want to describe, and owner rights in its GitHub organization, so you can create a GitHub App and install it there.
  • Claude Code installed and working in that repository. Any other MCP client works too; see Connect an agent.
  • A rough idea of the main parts of your system. You do not need a written spec.

Set up and publish your first change

  1. Install SpecsGraph with Docker Compose

    Follow Install with Docker Compose on your server. It covers the compose file, secrets, TLS and registering your own GitHub App, which sign-in needs. Set SPECSGRAPH_PUBLIC_URL to your own domain. When docker compose ps shows every service running, continue here.

  2. Sign in as the first user

    Open your public URL, here https://specsgraph.example.com, and sign in with GitHub. The first person to sign in becomes the Owner of the install, so do it before you share the address. Other people join later through invitations; see Members and roles.

  3. Create a workspace

    A workspace holds your team, its roles and the connection to GitHub. Name it Northwind Commerce.

  4. Connect your GitHub App to the repository

    Open Workspace settings, then GitHub and choose Connect GitHub. SpecsGraph sends you to GitHub to install the App you registered in Create your GitHub App; install it on your repository only. It requests Contents (read and write), Pull requests (read and write), Metadata (read). Connect GitHub explains each permission.

  5. Create a project

    A project holds the model of one system and publishes to one repository. Name it Shop, pick the repository you just connected and keep the suggested base branch, the repository's default branch. Workspaces and projects explains when to split a system into several projects.

  6. Sketch your first contexts

    On the system map, add three or four contexts for the parts of the system you know best, each with a short key that prefixes its requirement IDs: Orders (ORD), Billing (BIL) and Catalog (CAT). A one-line purpose for each is enough; Edit the graph in the web app shows where. Your edits collect in a Draft proposal. Choose Request review, then Approve, and merge the pull request SpecsGraph opens. The contexts are now part of the spec. If you would rather start from the code, skip this step: after step 8, ask your agent to propose the contexts as described in Start from an existing codebase, and merge that proposal before step 9.

  7. Create a personal access token

    Open Account settings, then Access tokens and create a token named claude-code-laptop. Choose Read and write access, because the agent will draft a proposal, and limit the token to the Shop project. Tokens start with sgp_ and are shown once, so copy it into an environment variable right away. See Personal access tokens to manage and revoke tokens.

    Shell
    export SPECSGRAPH_TOKEN="sgp_paste-your-token-here"

  8. Connect Claude Code to your server

    From your repository, register your SpecsGraph server's MCP URL: your public URL plus /mcp, here https://specsgraph.example.com/mcp. Your shell expands $SPECSGRAPH_TOKEN when you run the command, so Claude Code stores the token value in its own configuration. Run claude mcp list, or /mcp inside a Claude Code session, and check that specsgraph shows as connected. Claude Code's own documentation is the authority on its flags.

    Shell
    claude mcp add --transport http specsgraph https://specsgraph.example.com/mcp \
  --header "Authorization: Bearer $SPECSGRAPH_TOKEN"

  9. Ask the agent for a requirement

    Give Claude Code a prompt like the one below. It reads the Orders context with get_context, checks the glossary with list_glossary_terms and drafts the requirement with propose_requirement. The proposal opens for review with a branch name under spec/, here spec/checkout-reserve. These docs call the requirement ORD-12, its ID in the Northwind Commerce sample; in your project it gets the next number for ORD, as described in Requirement IDs.

    PromptText
    Use the specsgraph MCP server. Read the Orders context, then propose
a requirement: "Reserve stock for every line item at checkout".
Add acceptance scenarios for a cart where every line item gets a
reservation and for a cart where a line item cannot be reserved. Use
existing glossary terms where they fit.

  10. Review and approve

    In the web app, open Reviews and select the proposal. Read the requirement and its scenarios. If something is off, choose Comment on that node: the agent can read the thread and revise the proposal. When it reads right, choose Approve. Only people can approve; Proposals and reviews covers the details.

  11. See the pull request and the spec folder

    After approval, SpecsGraph commits the change to spec/checkout-reserve and opens a pull request against your base branch. It adds specsgraph/contexts/orders/requirements/ORD-12.md to the spec folder and updates the generated README.md and graph.json. The proposal stays Approved until you merge the pull request the way you merge any other. Merging it marks the proposal Published.

What lands in your repository

The requirement file carries the scenarios the agent drafted and you approved. For ORD-12 they look like this:

ORD-12: Reserve stock for every line item at checkoutGherkin
@ORD-12
Feature: Reserve stock for every line item at checkout

  Background:
    Given the Catalog has 5 units of "Trail mug" in stock
    And the Catalog has 1 unit of "Canvas tote" in stock

  Scenario: Every line item gets a reservation
    Given a Customer has a cart with 2 "Trail mug" and 1 "Canvas tote"
    When the Customer starts checkout
    Then a reservation holds 2 "Trail mug" for the order
    And a reservation holds 1 "Canvas tote" for the order
    And the Catalog shows 3 units of "Trail mug" available

  Scenario: Checkout stops when a line item cannot be reserved
    Given a Customer has a cart with 2 "Canvas tote"
    When the Customer starts checkout
    Then no reservation is created for the order
    And the Customer is told that only 1 "Canvas tote" is left
    And payment is not requested

As the model grows, the specsgraph/ folder fills out. A project with a few changes behind it looks like this:

Spec folder layoutText
specsgraph/
  README.md                 index of the model, generated
  glossary.md               every term with its definition
  actors.md                 people, systems and agents
  graph.json                machine-readable graph for tools and CI
  contexts/
    orders/
      context.md            purpose, subdomain, services, relationships
      requirements/
        ORD-12.md           one file per requirement, scenarios included
        ORD-13.md
  decisions/
    0007-reserve-stock-before-payment.md
  workstreams/
    WS-3.md

If the agent cannot connect

  • specsgraph shows as failed. Check that $SPECSGRAPH_TOKEN was set in the shell where you ran claude mcp add. If it was empty, remove the server with claude mcp remove specsgraph and add it again.
  • Requests are rejected as unauthorized. The token may have been revoked or copied with a missing character. Create a new one and add the server again.
  • The connection times out or returns 404. Check that the URL ends in /mcp and that your proxy sends that path to the mcp service. Check the install lists common causes.
  • The agent answers without using SpecsGraph. Name the server in your prompt, as in the example above, until the agent picks it up on its own.
  • No pull request appears. Confirm your GitHub App is installed on this repository, then check the proposal status in Reviews.

Troubleshooting covers more cases, from sign-in to publishing.

Next steps