Getting Started#

Welcome to Gittensory! This guide covers everything you need to get up and running — whether you're a miner or contributor who wants to use the MCP package, or a backend developer setting up a local copy of the API Worker.

Prerequisites#

Before you clone and run Gittensory locally, make sure the following tools are available.

Node.js ≥ 22.0.0#

Gittensory explicitly requires Node.js 22 or later. This is enforced in the root package.json 1:

"engines": {
  "node": ">=22.0.0"
}

Check your current version:

node --version

If you need to install or upgrade, nvm and fnm are both popular version managers. With nvm:

nvm install 22
nvm use 22

npm#

The project is pinned to npm@10.9.2 2 and uses npm workspaces to manage the monorepo. npm ships with Node.js, so upgrading Node will also upgrade npm. Confirm with:

npm --version

Git#

Git is required to clone the repository and is used internally by several scripts (including the CI gate's git diff --check step). Any reasonably recent version of Git will work.

A GitHub Account#

A GitHub account is needed for:

• Backend development — the GitHub OAuth and GitHub App integrations authenticate against GitHub identity.
• MCP usage — gittensory-mcp login uses GitHub Device Flow to authenticate you and exchange your GitHub identity for a Gittensory session token.

A Cloudflare Account (backend development only)#

The API Worker runs on Cloudflare Workers via Wrangler. Wrangler is already included as a dev dependency 3, so there is no separate global install required. However, you will need a free Cloudflare account if you plan to deploy, and wrangler login must succeed for commands that talk to Cloudflare (such as wrangler secret put). For purely local development (npm run dev), a Cloudflare account is helpful but the local D1 database and Worker can run without one.

MCP-only users (miners and contributors who just want to install @jsonbored/gittensory-mcp) only need Node.js ≥ 22, npm, and a GitHub account. No Cloudflare setup is required.

Local Development Setup#

These steps bring up a fully working local copy of the Gittensory API Worker.

1. Clone the repository#

git clone https://github.com/JSONbored/gittensory.git
cd gittensory

The repository URL is git+https://github.com/JSONbored/gittensory.git 4.

2. Install dependencies#

npm install

Gittensory is an npm workspaces monorepo containing both apps/* and packages/* 5. A single npm install at the repo root installs dependencies for every workspace — the API Worker, the gittensory-ui frontend, and the @jsonbored/gittensory-mcp package — all at once.

Expected output: npm will print the usual dependency tree and produce a single node_modules directory at the root. If you see peer-dependency warnings, they are generally safe to ignore unless they're errors.

3. Generate Cloudflare Worker types#

npm run cf-typegen

This runs wrangler types to generate TypeScript type declarations for every Cloudflare Workers binding — the D1 database, Queues, AI binding, and Durable Objects — and writes them to worker-configuration.d.ts 6. A trailing perl one-liner strips any trailing whitespace that Wrangler adds.

Why it's necessary: without these generated types, the TypeScript compiler cannot resolve the Cloudflare-specific globals (Env, DB, JOBS, etc.) that the Worker source code references.

Expected output: Wrangler prints a confirmation message and worker-configuration.d.ts is created or updated in the project root.

4. Run local database migrations#

npm run db:migrate:local

This runs wrangler d1 migrations apply gittensory --local 7, which applies all pending SQL migrations from the migrations/ directory to a local SQLite file that Wrangler manages on your machine 8. No Cloudflare account or internet connection is needed for the local flag.

Why it's necessary: the API Worker expects the D1 database schema to be in place before it can serve requests. Skipping this step causes runtime errors when the Worker tries to query tables that don't exist yet.

Expected output: Wrangler lists each migration file applied and reports success. If all migrations have already been applied, it prints that there is nothing to run.

5. Start the development server#

npm run dev

This runs wrangler dev 9, which compiles src/index.ts and serves the gittensory-api Worker locally 8. Wrangler starts a local HTTP server — by default at http://localhost:8787 — and watches your source files for changes.

Expected output:

⛅️ wrangler dev
------------------
⎔ Starting local server...
[wrangler] Ready on http://localhost:8787

You can verify the Worker is running by visiting http://localhost:8787/health — it should return {"status":"ok"}.

Optional: Link the MCP package from a local checkout#

If you're also developing the @jsonbored/gittensory-mcp package, you can link it locally instead of installing from npm 10:

npm link --workspace @jsonbored/gittensory-mcp

This makes the gittensory-mcp CLI point to your local packages/gittensory-mcp/ source so that changes are reflected immediately.

Environment Configuration#

Gittensory does not use .env files. All configuration is split between two places:

• Public variables — checked in to wrangler.jsonc under the vars key. These are non-sensitive values that are safe to commit.
• Secrets — set with wrangler secret put and stored encrypted in Cloudflare. These are never written to the filesystem.

Public variables (wrangler.jsonc)#

The following variables are already present in the checked-in wrangler.jsonc 8. For local development you can use the values as-is:

For local development, change PUBLIC_API_ORIGIN to http://localhost:8787 if you want the frontend and MCP to point at your local Worker instead of production.

Secrets#

These values are sensitive and must be set with wrangler secret put 12. Run each command and paste the value when prompted:

wrangler secret put GITHUB_WEBHOOK_SECRET
wrangler secret put GITHUB_APP_PRIVATE_KEY
wrangler secret put GITHUB_PUBLIC_TOKEN
wrangler secret put GITHUB_OAUTH_CLIENT_SECRET
wrangler secret put GITTENSORY_API_TOKEN
wrangler secret put GITTENSORY_MCP_TOKEN
wrangler secret put INTERNAL_JOB_TOKEN

For local-only development without deploying, you can skip secrets that are only used by deployed Worker features (e.g., GITHUB_WEBHOOK_SECRET is only needed if you are routing real GitHub webhooks to your machine via a tunnel such as cloudflared or ngrok).

Cloudflare bindings#

The Worker also uses these Cloudflare-managed resources 8, which Wrangler provisions automatically in local mode:

No manual setup is needed for local development — Wrangler emulates all of these locally.

MCP environment variables#

If you are using @jsonbored/gittensory-mcp and need to override defaults, the following environment variables are supported 15:

MCP Package Quick Start#

@jsonbored/gittensory-mcp is the primary surface for miners and contributors. It is a local stdio MCP wrapper that reads your branch's git metadata, calls the Gittensory API, and returns structured Gittensor intelligence — without ever uploading your source code 17.

Install#

npm install -g @jsonbored/gittensory-mcp@latest

Or run it once without installing globally 18:

npx -y @jsonbored/gittensory-mcp@latest --help

Step 1 — Log in#

gittensory-mcp login

login uses GitHub Device Flow by default 19. The CLI will print something like:

Open https://github.com/login/device and enter code XXXX-XXXX.

Open the URL in your browser, enter the code, and approve the authorization. The CLI polls for your approval 20 and, once confirmed, stores a Gittensory session token — not your GitHub PAT — in local config 21.

Alternative (non-interactive): if you already have a GitHub token available (e.g., via the gh CLI), skip the browser step:

gittensory-mcp login --github-token "$(gh auth token)"

After logging in, verify your session:

gittensory-mcp whoami
gittensory-mcp status

status reports your local package version, the latest npm version, API health, auth state, and source-upload posture 22.

Step 2 — Run a health check#

gittensory-mcp doctor

doctor is a comprehensive diagnostic command 23. It checks:

• api_health — Can the CLI reach the Gittensory API?
• version — Is your installed package up to date?
• api_compatibility — Does the API require a newer client version?
• auth — Is a valid session token configured and verified?
• source_upload — Confirms GITTENSORY_UPLOAD_SOURCE is disabled (safe posture).
• decision_pack_cache — Reports local stale fallback cache status and entry count.
• git_metadata — Can the CLI read the local git repository?
• client_path — Is gittensory-mcp visible on your shell PATH?
• local_scorer — Is an optional local scorer configured and working?

Each check reports pass, warn, or fail along with a remediation hint. The overall status is either ok, warnings, or needs_attention.

Add --json to get machine-readable output:

gittensory-mcp doctor --json

Step 3 — Start the MCP server#

gittensory-mcp --stdio

This starts the MCP server over stdio transport 24. It is how MCP clients — Claude Desktop, Codex, Cursor, and others — communicate with Gittensory. You do not normally run this command directly; instead, you wire it into your coding agent's configuration.

Wiring into your coding agent#

The quickest way is to let the CLI print the correct configuration snippet for your editor:

gittensory-mcp init-client --print codex
gittensory-mcp init-client --print claude
gittensory-mcp init-client --print cursor

Paste the printed snippet into your agent's config file. See the MCP client setup docs for editor-specific instructions.

For any MCP-compatible client, the generic stdio config is 25:

{
  "mcpServers": {
    "gittensory": {
      "command": "gittensory-mcp",
      "args": ["--stdio"]
    }
  }
}

Heads-up: if your MCP client does not inherit your shell's PATH, replace "gittensory-mcp" with the absolute path to the binary (e.g., the output of which gittensory-mcp). 26

Available MCP tools#

Once connected, your coding agent has access to the following Gittensory tools 27:

• gittensory_agent_plan_next_work — rank and explain next actions
• gittensory_agent_start_run — start a deterministic agent run
• gittensory_agent_get_run — fetch a run result by ID
• gittensory_agent_explain_next_action — explain blockers for a specific action
• gittensory_agent_prepare_pr_packet — draft a public-safe PR packet

Running Tests#

Gittensory uses Vitest for its test suite with a 97% coverage threshold enforced across all metrics 28. Tests are organized into two separate configurations: one for standard Node.js tests, and one for Cloudflare Workers-specific tests 29.

Run all tests#

npm test

This is an alias for vitest run and runs every test file matching test/**/*.test.ts except those under test/workers/ .

Run specific test suites#

# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

# Cloudflare Workers tests (uses a separate vitest config)
npm run test:workers

The unit suite 32 runs files under test/unit/, the integration suite 33 runs files under test/integration/, and test:workers 34 uses vitest.workers.config.ts with @cloudflare/vitest-pool-workers to run tests against the real Cloudflare Workers runtime 29.

Watch mode#

npm run test:watch

Runs vitest without the run flag, keeping the process alive and re-running affected tests on every file save 35.

Coverage report#

npm run test:coverage

This runs vitest run --coverage 36 and generates a coverage report using the v8 provider 37. Coverage is collected from src/**/*.ts, excluding src/env.d.ts 38.

The build will fail if any of these thresholds are not met 28:

Tip: when writing new code, aim for 98%+ branch coverage locally to leave a comfortable margin above the gate 39.

Full CI gate#

npm run test:ci

This is the complete validation pipeline run on every PR 40:

git diff --check # no whitespace errors
npm run actionlint # GitHub Actions workflow linting
npm run typecheck # TypeScript type checking
npm run test:coverage # unit + integration tests with coverage
npm run test:workers # Cloudflare Workers tests
npm run build:mcp # MCP package build
npm run test:mcp-pack # MCP package file hygiene
npm run ui:openapi:check # OpenAPI contract check
npm run ui:lint # frontend linting
npm run ui:typecheck # frontend type checking
npm run ui:build # frontend production build
npm audit --audit-level=moderate # dependency vulnerability audit

Run this locally before opening a PR to catch issues early.

Test organization#

The test/ directory is structured as follows:

41

Common Issues / Troubleshooting#

Node version mismatch#

Symptom: npm install or npm run dev fails with an error like The engine "node" is incompatible with this module.

Fix: Gittensory requires Node.js ≥ 22.0.0 1. Check your version with node --version and upgrade if needed. With nvm:

nvm install 22
nvm use 22

Or with fnm:

fnm install 22
fnm use 22

Stale global MCP install#

Symptom: A command like gittensory-mcp agent plan is not recognized, or the CLI behaves unexpectedly.

Fix: Run gittensory-mcp doctor — it checks whether your installed version matches npm latest and prints the exact upgrade command if you are behind 42. This is a known real-world issue 43. Upgrade with:

npm install -g @jsonbored/gittensory-mcp@latest

Or use the no-install fallback: npx @jsonbored/gittensory-mcp@latest <command>.

Missing secrets / environment variables#

Symptom: npm run dev starts but requests fail with 500 errors, or Wrangler complains about missing bindings.

Fix: Set each required secret with wrangler secret put. All seven secrets listed in the Environment Configuration section are needed for full functionality 12. For purely local offline development, you can defer secrets that only apply to deployed features (GitHub webhooks, OAuth).

Database migration failures#

Symptom: npm run db:migrate:local exits with an error, or the Worker crashes with SQL errors at startup.

Fix: Make sure you are running the command from the repo root (where wrangler.jsonc lives). Wrangler uses the migrations_dir: "migrations" path from that config 8. If the local D1 database file is corrupted, delete Wrangler's local state directory (usually .wrangler/) and re-run the migration:

rm -rf .wrangler
npm run db:migrate:local

Port conflicts#

Symptom: npm run dev (Wrangler) fails with EADDRINUSE or a similar port-in-use error.

Fix: Wrangler's API Worker defaults to port 8787. The UI preview server uses port 4173 44. Kill any processes already on those ports:

# macOS / Linux
lsof -ti:8787 | xargs kill -9
lsof -ti:4173 | xargs kill -9

Or configure Wrangler to use a different port by passing --port <N> to wrangler dev.

Authentication issues (MCP)#

Symptom: gittensory-mcp analyze-branch or other commands return authentication errors.

Fix: Run gittensory-mcp doctor first — it reports the exact auth state and prints remediation steps 45:

gittensory-mcp doctor

If the auth check shows fail, re-authenticate:

gittensory-mcp login

If you are using a static API token instead of a session, set GITTENSORY_API_TOKEN (or GITTENSORY_MCP_TOKEN / GITTENSORY_TOKEN) in your environment.

gittensory-mcp not found in MCP client#

Symptom: Your coding agent (Claude Desktop, Codex, Cursor) fails to start the MCP server with a "command not found" error.

Fix: Many MCP clients launch processes without inheriting your shell's full PATH. Use the absolute path to the binary in your agent config 26:

which gittensory-mcp # copy this path

Then update your config:

{
  "mcpServers": {
    "gittensory": {
      "command": "/absolute/path/to/gittensory-mcp",
      "args": ["--stdio"]
    }
  }
}

GITTENSORY_UPLOAD_SOURCE error#

Symptom: gittensory-mcp doctor reports a fail on the source_upload check.

Fix: Source upload is unsupported in v1 and fails closed if the variable is set to true . Unset the variable:

unset GITTENSORY_UPLOAD_SOURCE

GitHub App installation issues#

Symptom: The GitHub App is installed but fails to respond to webhooks or health checks show missing permissions.

Fix: Verify that the GitHub App has the required repository permissions (Metadata: read, Pull requests: read, Issues: write) and is subscribed to the required events (Pull request, Issues, Issue comment, Repository) 47. The maintainer can run a structured repair workflow from the API to diagnose and fix missing permissions:

• GET /v1/installations/{id}/repair — Returns detailed repair diagnostics including missing permissions, missing webhook events, mode-specific impacts (comment/label/check_run), and step-by-step repair instructions. The diagnostics explain exactly which permissions and webhook events are missing, how they impact different Gittensory modes, and provide actionable repair steps.
• POST /v1/installations/{id}/repair/refresh — Rechecks the live GitHub App installation metadata after you update permissions on GitHub. Returns updated diagnostics with a "refreshed": true flag. Call this endpoint after changing GitHub App permissions to recheck the installation health.

Getting more help#

• GitHub Issues: https://github.com/JSONbored/gittensory/issues 49
• Support policy: see SUPPORT.md in the repository root
• Code of Conduct: CODE_OF_CONDUCT.md
• Security issues: SECURITY.md — do not file security vulnerabilities as public issues 50