VectorGraph documentation

# Require the current public registry release.
npm view @orintech/[email protected] version
npm install --global @orintech/[email protected]

vectorgraph auth login
vectorgraph auth status
vectorgraph workspace list

# PowerShell
npm.cmd view @orintech/[email protected] version
npm.cmd install --global @orintech/[email protected]

vectorgraph.cmd auth login
vectorgraph.cmd auth status
vectorgraph.cmd workspace list

vectorgraph workspace use "<workspace-id-or-slug>"

vectorgraph mcp setup \
  --client codex,claude \
  --team "ENG" \
  --local-north

# Review every field, then answer y.
# Codex and Claude receive separate credentials.
# The hosted server name losslessly encodes the selected workspace UUID.

vectorgraph workspace use "<workspace-id-or-slug>"

# First call: structured review only; no credential is created.
vectorgraph mcp setup \
  --client codex,claude \
  --team "ENG" \
  --local-north \
  --json

# After approval, repeat the identical request with --yes.
vectorgraph mcp setup \
  --client codex,claude \
  --team "ENG" \
  --local-north \
  --json \
  --yes

Use VectorGraph MCP only for this check.

1. Initialize the server and list resources and tools.
2. Read the workspace teams resource and report visible team IDs.
3. Report the server name, workspace resource URI, and allowed tool names.
4. Call read_context_bundle for <ISSUE_IDENTIFIER> in compact mode.
5. Return source IDs, redactions, freshness, and requestId.
6. Do not create, update, or comment on work.
7. Do not reveal credentials or Authorization headers.

# CLI HTTP API: no SDK install required.
export VECTORGRAPH_API_URL="https://api.example.com"
# Inject VECTORGRAPH_CLI_TOKEN through a local secret store before running.
: "${VECTORGRAPH_CLI_TOKEN:?VECTORGRAPH_CLI_TOKEN is not set}"

curl -s \
  -H "Authorization: Bearer $VECTORGRAPH_CLI_TOKEN" \
  "$VECTORGRAPH_API_URL/cli/v1/me"

# macOS or Linux: require the exact registry release.
(
  set -eu
  test "$(node --version)" = "v24.19.0"
  git --version
  test "$(npm view @orintech/[email protected] version)" = "0.7.1"

  npm install --global @orintech/[email protected]
  command -v vectorgraph
  vectorgraph version --json
  vectorgraph north doctor --json
)

# Windows PowerShell: require the exact registry release.
$nodeVersion = node --version
if ($LASTEXITCODE -ne 0 -or $nodeVersion.Trim() -ne "v24.19.0") {
  throw "Node.js 24.19.0 is required."
}
git --version
$vectorgraphVersion = npm.cmd view @orintech/[email protected] version
if ($LASTEXITCODE -ne 0 -or $vectorgraphVersion.Trim() -ne "0.7.1") {
  throw "VectorGraph CLI 0.7.0 is not available from npm."
}

npm.cmd install --global @orintech/[email protected]
Get-Command vectorgraph.cmd
vectorgraph.cmd version --json
vectorgraph.cmd north doctor --json

{
  "mcpServers": {
    "vectorgraph-ERERERERQRGBEREREREREQ": {
      "transport": "http",
      "url": "${VECTORGRAPH_MCP_URL}",
      "headers": {
        "Authorization": "Bearer ${VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111}"
      }
    },
    "vectorgraph-north": {
      "command": "vectorgraph",
      "args": ["north", "mcp"]
    }
  }
}

vectorgraph auth login

# The browser compares a short code, then lets the human select
# workspace profiles and the initial active workspace.
vectorgraph auth status
vectorgraph workspace list

# When another saved workspace should become active:
vectorgraph workspace use "<workspace-slug>"
vectorgraph auth status

curl -s \
  -H "Authorization: Bearer $VECTORGRAPH_CLI_TOKEN" \
  "$VECTORGRAPH_API_URL/cli/v1/me"

{
  "requestId": "req_01H...",
  "actor": {
    "actorType": "user",
    "actorLabel": null,
    "userId": "<user-uuid>"
  },
  "token": {
    "scopes": [
      "workspace:read",
      "team:read",
      "issue:read",
      "issue:write",
      "comment:write"
    ],
    "workspaceId": "<workspace-uuid>"
  },
  "workspaces": [{ "id": "<workspace-uuid>", "slug": "acme" }]
}

# Generate the client setup in the browser:
# Workspace console -> Integrations -> provider -> Connect client
# Manual fallback: Developer access -> Agents -> Create agent

export VECTORGRAPH_MCP_URL="https://app.example.com/mcp"
# Inject the workspace-specific variable through a local secret store.
: "${VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111:?workspace MCP token is not set}"

curl -s -X POST "$VECTORGRAPH_MCP_URL" \
  -H "Authorization: Bearer $VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111" \
  -H "Content-Type: application/json" \
  -H "X-VectorGraph-MCP-Purpose: setup_verification" \
  -d '{
    "jsonrpc": "2.0",
    "id": "init-1",
    "method": "initialize",
    "params": {}
  }'

# Start your MCP-compatible coding agent from the terminal.
# Keep the token in env/config; do not paste it into the prompt.

export VECTORGRAPH_MCP_URL="https://app.example.com/mcp"
# Inject the workspace-specific variable through a local secret store.
: "${VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111:?workspace MCP token is not set}"

Prompt for the terminal agent:

Use hosted VectorGraph MCP to read ENG-124 before planning. Use compact mode for the first pass.
If local NorthGraph MCP is installed and tools/list succeeds, use it to inspect affected symbols and impacted tests.
Do not edit auth, billing, email delivery, or private-team code.

{
  "mcpServers": {
    "vectorgraph-ERERERERQRGBEREREREREQ": {
      "transport": "http",
      "url": "${VECTORGRAPH_MCP_URL}",
      "headers": {
        "Authorization": "Bearer ${VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111}"
      }
    }
  }
}

{
  "mcpServers": {
    "vectorgraph-north": {
      "command": "vectorgraph",
      "args": ["north", "mcp"]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "init-1",
  "result": {
    "protocolVersion": "2025-06-18",
    "serverInfo": {
      "name": "vectorgraph",
      "title": "VectorGraph MCP",
      "version": "0.1.0"
    },
    "capabilities": {
      "resources": { "listChanged": false },
      "tools": { "listChanged": false },
      "prompts": { "listChanged": false }
    }
  }
}

vectorgraph north init
vectorgraph north index --json
vectorgraph north inspect scoreJob --json
vectorgraph north effects --type email_send --json
vectorgraph north diff analyze --base main --json
vectorgraph north verify --base main --json
vectorgraph north report pr \
  --base main \
  --out .vectorgraph/north/pr-report.json \
  --json

# Start the local codebase-intelligence MCP server.
vectorgraph north mcp

# Then connect your terminal agent to that local MCP server.
# Use hosted VectorGraph MCP for workspace work data.
# Use local NorthGraph MCP for local repo facts.

curl -s \
  -H "Authorization: Bearer $VECTORGRAPH_CLI_TOKEN" \
  "$VECTORGRAPH_API_URL/cli/v1/me"

{
  "requestId": "req_01H...",
  "actor": {
    "actorType": "user",
    "actorLabel": null,
    "userId": "<user-uuid>"
  },
  "token": {
    "scopes": [
      "workspace:read",
      "team:read",
      "issue:read",
      "issue:write",
      "comment:write"
    ],
    "workspaceId": "<workspace-uuid>"
  },
  "workspaces": [{ "id": "<workspace-uuid>", "slug": "acme" }]
}

curl -s -X POST \
  -H "Authorization: Bearer $VECTORGRAPH_CLI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-checkout-telemetry-001" \
  -d '{
    "teamId": "<team-uuid>",
    "title": "Add checkout retry telemetry",
    "description": "Record retry reason, attempt count, and final result.",
    "priority": "high"
  }' \
  "$VECTORGRAPH_API_URL/cli/v1/workspaces/$VECTORGRAPH_WORKSPACE_ID/issues"

{
  "requestId": "req_01H...",
  "issue": {
    "id": "<issue-uuid>",
    "identifier": "ENG-124",
    "title": "Add checkout retry telemetry"
  }
}

curl -s \
  -H "Authorization: Bearer $VECTORGRAPH_CLI_TOKEN" \
  "$VECTORGRAPH_API_URL/cli/v1/workspaces/$VECTORGRAPH_WORKSPACE_ID/teams"

{
  "requestId": "req_01H...",
  "teams": [
    {
      "id": "<team-uuid>",
      "identifier": "ENG",
      "name": "Engineering",
      "visibility": "public"
    }
  ]
}

# Requires context:read. The standard browser-created CLI token does not include it.
curl -s \
  -H "Authorization: Bearer $VECTORGRAPH_CLI_TOKEN" \
  "$VECTORGRAPH_API_URL/cli/v1/workspaces/$VECTORGRAPH_WORKSPACE_ID/issues/ENG-124/context"

{
  "requestId": "req_01H...",
  "bundle": {
    "issue": { "identifier": "ENG-124" },
    "permissionDecisions": [],
    "redactions": [],
    "freshness": { "generatedAt": "2026-05-15T04:00:00.000Z" }
  }
}

curl -s -X POST \
  -H "Authorization: Bearer $VECTORGRAPH_CLI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-handoff-ENG-124-001" \
  -d '{
    "body": "Verified with vectorgraph north verify --base main. Request IDs: req_01H..."
  }' \
  "$VECTORGRAPH_API_URL/cli/v1/workspaces/$VECTORGRAPH_WORKSPACE_ID/issues/ENG-124/comments"

{
  "jsonrpc": "2.0",
  "id": "create-1",
  "method": "tools/call",
  "params": {
    "name": "create_issue",
    "arguments": {
      "workspaceId": "<workspace-uuid>",
      "teamId": "<team-uuid>",
      "title": "Add retry telemetry",
      "description": "Record retry reason, attempt count, and final result.",
      "priority": "high",
      "idempotencyKey": "create-retry-telemetry-001"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "approval-1",
  "method": "tools/call",
  "params": {
    "name": "request_approval",
    "arguments": {
      "workspaceId": "<workspace-uuid>",
      "action": "Run production-impacting migration",
      "reason": "The task touches workspace isolation and requires owner approval.",
      "riskLevel": "critical"
    }
  }
}

{
  "version": 1,
  "rules": [
    {
      "name": "recommendations cannot send email",
      "paths": ["src/recommendations/**"],
      "deniedEffects": ["email_send", "secret_read", "payment_operation"],
      "requiredTests": ["ranking.test.ts"]
    },
    {
      "name": "auth requires human review",
      "paths": ["src/auth/**", "src/permissions/**"],
      "risk": "critical",
      "requiresHumanReview": true
    }
  ]
}

{
  "reportId": "north_01H...",
  "baseRef": "main",
  "risk": "medium",
  "policy": { "passed": true },
  "changedFiles": ["src/recommendations/ranking.ts"],
  "newEffects": [],
  "impactedTests": ["ranking.test.ts", "email-alert-job-selection.test.ts"],
  "verification": [
    { "command": "pnpm test ranking.test.ts", "status": 0 }
  ],
  "limitations": []
}

# Generate the client setup in the browser:
# Workspace console -> Integrations -> provider -> Connect client
# Manual fallback: Developer access -> Agents -> Create agent

export VECTORGRAPH_MCP_URL="https://app.example.com/mcp"
# Inject the workspace-specific variable through a local secret store.
: "${VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111:?workspace MCP token is not set}"

curl -s -X POST "$VECTORGRAPH_MCP_URL" \
  -H "Authorization: Bearer $VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111" \
  -H "Content-Type: application/json" \
  -H "X-VectorGraph-MCP-Purpose: setup_verification" \
  -d '{
    "jsonrpc": "2.0",
    "id": "init-1",
    "method": "initialize",
    "params": {}
  }'

curl -s -X POST "$VECTORGRAPH_MCP_URL" \
  -H "Authorization: Bearer $VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": "tools-1",
  "method": "tools/list"
}'

{
  "jsonrpc": "2.0",
  "id": "tools-1",
  "result": {
    "tools": [
      { "name": "search_work" },
      { "name": "read_context_bundle" }
    ]
  }
}

curl -s -X POST "$VECTORGRAPH_MCP_URL" \
  -H "Authorization: Bearer $VECTORGRAPH_MCP_TOKEN_11111111111141118111111111111111" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": "ctx-1",
  "method": "tools/call",
  "params": {
    "name": "read_context_bundle",
    "arguments": {
      "workspaceId": "<workspace-uuid>",
      "issueIdentifier": "ENG-124",
      "mode": "compact"
    }
  }
}'

{
  "structuredContent": {
    "contextBundle": {
      "issue": { "identifier": "ENG-124" },
      "comments": [],
      "activity": [],
      "knowledgeArtifacts": {
        "documents": [{ "title": "Launch note", "bodyExcerpt": "..." }],
        "canvases": [{
          "title": "Launch map",
          "textIndex": "Onboarding flow...",
          "scene": {
            "elementCount": 4,
            "elements": [{ "type": "text", "text": "Onboarding flow" }]
          }
        }]
      },
      "permissionDecisions": [],
      "redactions": [],
      "requestId": "req_01H...",
      "tokenEfficiency": { "mode": "compact" }
    }
  }
}

{
  "error": {
    "code": "agent_team_denied",
    "message": "Agent is not allowed to access this team.",
    "requestId": "req_01H..."
  }
}

// Client behavior:
// 1. Preserve requestId.
// 2. Branch on error.code.
// 3. Do not retry with a broader token unless a human changes policy.
// 4. Treat not_found as possibly permission-filtered.

Agent handoff for ENG-124

Context read:
- VectorGraph context bundle: req_01H...
- NorthGraph report: north_01H...

Changes:
- Files changed:
- New effects:
- Risk:

Verification:
- Commands run:
- Results:
- Limitations:

Follow-up:
- Approval required:
- Remaining risks: